Constructors

- SceneObject

Constructor Summary

SceneObject
(sprites,
behaviors,
posX,
posY,
name)
A Scene Object is an entity that can be added to the scene in WADE.

Functions Summary

addBehavior
(behaviorClass)
Add a behavior to the scene object
addSprite
(sprite,
offset,
index)
Add a sprite to the scene object
clone
(positionX,
positionY)
Clone the scene object
drawToImage
(imageName,
replace)
Draw a SceneObject to an image in CPU memory.
fadeIn
(time,
callback)
Fade in effect, gradually changing the opacity (alpha) of the all the sprites of this object from 0 to 1.
fadeOut
(time,
callback)
Fade out effect, gradually changing the opacity (alpha) of the all the sprites of this object from 1 to 0.
Get the screen alignment of a scene object.
Get the current angular velocity of the object
getBehavior
(name)
Get a behavior of the scene object
Get a behavior of the scene object, give its index in the array of behaviors
Get an array containing all the behaviors of this object
Get a reference to the current flow chart data structure associated with this SceneObject.
Get the script (as a string) that defines the functions associated with this object when it was constructed or the last time importFunctions was called
Get the scene object's movement speed
Get the current name of this object, if it was set when the object was created or with SceneObject.setName()
getOverlappingObjects
(searchAllLayers,
precision)
Get an array of objects overlapping this object
Get the currently active Path for this SceneObject
Get the world space position of the scene object
Get the current rotation angle of the scene object
getSprite
(index)
Get the sprite object corresponding to a given sprite index
getSpriteAtPosition
(screenPosition)
Get a sprite of the scene object at a given screen position (if there is one).
Get a sprite object given its name
Get the number of sprites in the scene object
getSpriteIndex
(sprite)
Get the current index of a sprite
getSpriteOffset
(indexOrName)
Get the position of a sprite relative to the position of its parent scene object
Get the position where the scene object is moving to
Get the rotation angle the scene object is rotating to.
Get the current linear velocity of the object
importFunctions
(functionObject)
Import functions from an object that contains their string representations
interval
(time,
functionName,
data,
variance)
Schedule the execution and processing of a function for this object, repeating it periodically.
Check whether any sprite in the scene object is playing any animation
Check whether the scene object is in the scene
isListeningFor
(eventName)
Check if the object is currently listening for a specific type of event.
Check whether the scene object is currently moving
Check whether the SceneObject is currently visible on the screen
Check whether this object is a template.
isVisible
(checkAllSprites)
Check if a scene object is visible.
listenFor
(eventName)
Start listening for an event.
moveTo
(posX,
posY,
speed)
Move a scene object to the specified world space position, with a given speed
overlapsObject
(object,
precision)
Check whether this scene object overlaps another scene object
overlapsSprite
(sprite,
precision)
Check whether this scene object overlaps a sprite
playAnimation
(name,
direction)
Play an animation on all the sprites of the scene object that have an animation with a matching name
process
(functionName,
data)
Execute a function of this object and its behaviors.
processEvent
(eventName,
eventData)
Process an event for the scene object and all its behaviors.
Remove all the sprites from the scene object.
Remove a behavior from a scene object
Remove a behavior from a scene object, using the behavior index
removeSprite
(sprite)
Remove a sprite from the scene object
Remove a sprite from the scene object, given a sprite index
Resume playing any animations that had been stopped
rotateTo
(angle,
angularVelocity)
Gradually rotate an object towards a target angle
schedule
(time,
functionName,
data)
Schedule the execution and processing of a function for this object.
serialize
(stringify,
propertiesToExclude,
serializeFunctions)
Export this SceneObject to an object that can then be used to create a new SceneObject like this one (by passing the resulting object to the SceneObject constructor).
setAlignment
(leftRight,
topBottom)
Set the screen alignment of a scene object.
setAngularVelocity
(velocity)
Set the angular velocity of the object.
setAsTemplate
(toggle)
Set a scene object to be a template.
setFlowChart
(flowChartData)
Assigns a flow chart to this SceneObject.
setName
(name)
Set a name for the scene object, so it can be retrieved via wade.getSceneObject().
setPath
(path,
setInitialValues,
speedMultiplier)
Set the currently active Path for this SceneObject.
setPosition
(positionX,
positionY)
Set the world space position of the scene object.
setRotation
(rotation)
Set a rotation angle for the scene object
setSpriteOffset
(indexOrName,
offset)
Set the position of a sprite relative to the position of the scene object
setSpriteOffsets
(spriteOffsets)
Set the world space position offsets for the sprites of the scene object (i.e.
setVelocity
(velocityX,
velocityY)
Set the current linear velocity of the object.
setVisible
(toggle)
Show or hide a scene object
step()
Perform a simulation step for the scene object.
Stop any animations that are currently playing
stopListeningFor
(eventName)
Stop listening for an event.
Stop a scene object that is currently moving.
toGrid
(numColumns,
numRows,
marginX,
marginY)
Create a grid of clones of this SceneObject.
unschedule
(eventName)
Cancel any scheduled events with the given name for this object

Constructor Details


(sprites,
behaviors,
posX,
posY,
name)
A Scene Object is an entity that can be added to the scene in WADE. It may contain sprites and may have behaviors associated with it.

Parameters:


{Sprite|Array|object}spritesOptional
A sprite object, or an array of sprites. You can also use this constructor by passing in a single object (so just the first parameter) that contains all the SceneObject properties that you want to set (see remarks below for more details).
{Function|Array}behaviorsOptional
A behavior function, or an array of behavior functions
{number}posXOptional, Default: 0
The X coordinate of the initial world space position
{number}posYOptional, Default: 0
The Y coordinate of the initial world space position
{string}nameOptional
The name of the scene object (so you can obtain a reference to this object via wade.getSceneObject)

Remarks:
You can also use this constructor by passing in a single object (so just the first parameter) that contains all the SceneObject properties that you want to set. In this case, the object structure is as follows (all fields are optional):
 {
    type: 'SceneObject',
    position: {x: number, y: number},
    rotation: number,
    behaviors: Array,
    sprites: Array,
    spriteOffsets: Array,
    alignment: {x: string, y: string},
    name: string,
    visible: boolean,
    isTemplate: boolean,
    path: string,
    addToScene: {autoListen: boolean, params: {}},
    flowChart: {},
    functions: {},
    properties: {}
 }
 
Where properties is a set of properties to copy into the new scene object. Note that properties are deep-copied, and cannot contain functions or cyclical references.
The sprites array can contain any number of sprites. See the Sprite documentation for more details about the format used to describe each sprite.
The path parameter can be used to specify the name of a Path that the object should follow when it's added to the scene. Note that the path must already be in the scene when the SceneObject is created. The flowChart object may contain flow chart data as described in the documentation for wade.runFlowChart(). This flow chart would then be executed every time the object is added to the scene. The addToScene object can be used if you want the object to be added to the scene immediately. In this case, you can specify which set of parameters should be passed to the onAddToScene event (params), and whether you want the object to automatically listen for handled input events (autoListen).
The functions object can contain any number of strings that will be interpreted as member functions of the SceneObject.

Function Details


(behaviorClass)
Add a behavior to the scene object

Parameters:


behaviorClass
The definition of a behavior function. Note that this is not the same as an instance of a behavior function.

Returns:


{Object}
The instance of the behavior function that was just added to the object.

(sprite,
offset,
index)
Add a sprite to the scene object

Parameters:


{Sprite}sprite
The sprite to add
{object}offsetOptional
An object with 'x' and 'y' fields representing the position offset and an 'angle' field representing the angular offset. If omitted or falsy, the offset will be (0, 0, 0). If any of the fields is omitted, its value will be 0.
{number}indexOptional
Where to add the sprite. If omitted, the sprite will be added after any sprites already present in this scene object. If 'index' is greater than the number of sprites currently present in the scene object, the sprite will be added at the end. Check the returned value to detrmine the actual index that was used.

Returns:


{number}
The index of the sprite that was just added

(positionX,
positionY)
Clone the scene object

Parameters:


{number}positionXOptional
The new X coordinate for the clone's position. If omitted the X coordinate of the original object is used
{number}positionYOptional
The new Y coordinate for the clone's position. If omitted the Y coordinate of the original object is used

Returns:


{object}
A copy of the scene object. Note that the new object won't be automatically added to the scene, even if the object you are cloning was in the scene.

(imageName,
replace)
Draw a SceneObject to an image in CPU memory.

Parameters:


{string}imageName
The target image name
{boolean}replaceOptional
Whether to replace any existing image with that name. Set this to false to draw on top of an existing image.

(time,
callback)
Fade in effect, gradually changing the opacity (alpha) of the all the sprites of this object from 0 to 1. If any sprite is invisible, it is set to visible before fading in.

Parameters:


{number}time
How many seconds the transition should last. Note that this won't be extremely accurate - to make the effect smooth, it must ultimately depend on the actual frame rate of the app.
{function}callbackOptional
A function to execute when the transition is over

(time,
callback)
Fade out effect, gradually changing the opacity (alpha) of the all the sprites of this object from 1 to 0. After fading out, all sprites are set to invisible.

Parameters:


{number}time
How many seconds the transition should last. Note that this won't be extremely accurate - to make the effect smooth, it must ultimately depend on the actual frame rate of the app.
{function}callbackOptional
A function to execute when the transition is over
()
Get the screen alignment of a scene object. This determines where the object is positioned following a resize event

Returns:


{Object}
An object whose 'x' and 'y' fields represent the alignment of the scene object. If the alignment is set, valid values are 'left' and 'right' for the 'x' field, and 'top' and 'bottom' for the 'y' field
()
Get the current angular velocity of the object

Returns:


{number}
The angular velocity of the object, in radians per second

(name)
Get a behavior of the scene object

Parameters:


{string}nameOptional
The name of the behavior to get.

Returns:


{Object}
The requested behavior. If the 'name' parameter is omitted or falsy, the first behavior that was registered with the scene object.

(index)
Get a behavior of the scene object, give its index in the array of behaviors

Parameters:


{number}indexOptional
The index of the sprite to retrieve

Returns:


{Object}
The requested behavior. Note that this is an instance of the behavior, not the behavior class that was passed to the SceneObject's constructor.
()
Get an array containing all the behaviors of this object

Returns:


{Array}
An array containing all the behaviors of this object.
()
Get a reference to the current flow chart data structure associated with this SceneObject. This will be null unless it was set via setFlowChart, or via the SceneObject constructor.

Returns:


{Object}
The flow chart data. See the documentation of wade.runFlowChart() for details.
()
Get the script (as a string) that defines the functions associated with this object when it was constructed or the last time importFunctions was called

Returns:


{string}
The source of the functions script
()
Get the scene object's movement speed

Returns:


{number}
The current movement speed
()
Get the current name of this object, if it was set when the object was created or with SceneObject.setName()

Returns:


{string}
The name of this object

(searchAllLayers,
precision)
Get an array of objects overlapping this object

Parameters:


{boolean}searchAllLayersOptional
Whether to extend the search to all layers. This is false by default, meaning that only overlapping sprites on the same layer will be considered.
{string}precisionOptional
How accurately to search for overlaps. This can be either 'axis-aligned' (which would consider the axis-aligned bounding box of the sprites), or 'oriented', which takes into account the rotation of each sprite. Default is 'axis-aligned'.

Returns:


{Array}
All the objects that are overlapping this object
()
Get the currently active Path for this SceneObject

Returns:


{Path}
The currently active path.
()
Get the world space position of the scene object

Returns:


{Object}
An object with 'x' and 'y' field representing world space coordinates
()
Get the current rotation angle of the scene object

Returns:


{number}
The current rotation angle in radians. A positive value indicates a clockwise rotation

(index)
Get the sprite object corresponding to a given sprite index

Parameters:


{number|string}indexOptional
The sprite index or the sprite name. If omitted or falsy, the first sprite is returned.

Returns:


{Sprite|undefined}
The sprite object

(screenPosition)
Get a sprite of the scene object at a given screen position (if there is one).
Note that at most one sprite will be returned. If more sprites are present at the same screen position, the one at the front will be returned.


Parameters:


{Object}screenPosition
A position object, with 'x' and 'y' coordinates

Returns:


{Object}
An object with the following fields: isPresent - A boolean that describes whether any sprite was found topLayer - The id of the top layer where a sprite was found spriteIndex - The index of the sprite that was found. You can use this to get the sprite object with a call to getSprite

(name)
Get a sprite object given its name

Parameters:


{string}name
The name of the sprite

Returns:


{Sprite}
The sprite object corresponding to the given name
()
Get the number of sprites in the scene object

Returns:


{number}
The number of sprites

(sprite)
Get the current index of a sprite

Parameters:


{Sprite}sprite
The sprite to look for

Returns:


{number}
The index of the sprite

(indexOrName)
Get the position of a sprite relative to the position of its parent scene object

Parameters:


{number}indexOrNameOptional
The sprite index or a string representing the sprite name. If omitted or falsy, the first sprite offset is returned.

Returns:


{Object}
An object with 'x' and 'y' fields representing the position offset and an 'angle' field representing the angular offset
()
Get the position where the scene object is moving to

Returns:


{Object}
An object with 'x' and 'y' fields representing a world space position, or null if no target position is set
()
Get the rotation angle the scene object is rotating to. Note that if there is no target rotation angle, this will simply return the current rotation angle of the object.

Returns:


{number}
The target rotation angle
()
Get the current linear velocity of the object

Returns:


{{x: number|y: number}}
An object with x and y fields representing the linear velocity of the object

(functionObject)
Import functions from an object that contains their string representations

Parameters:


{Object}functionObject
An object in the format {functionName1: functionCode1, functionName2: functionCode2, ...} where functionCode is always a string.

(time,
functionName,
data,
variance)
Schedule the execution and processing of a function for this object, repeating it periodically. The scheduled function will be cancelled when the object is removed from the scene, or when SceneObject.unschedule is called

Parameters:


{number}time
How many milliseconds to wait between function calls
{string}functionName
The name of the function to execute for this object. If the object or any of its behaviors have a function with this name, it will be executed
{object}dataOptional
The data to pass to the event function
{number}varianceOptional
A maximum amount of milliseconds to randomly add or subtract to the time parameter
()
Check whether any sprite in the scene object is playing any animation

Returns:


{Boolean}
Whether any sprite in the scene object is playing any animation
()
Check whether the scene object is in the scene

Returns:


{boolean}
Whether the scene object is in the scene

(eventName)
Check if the object is currently listening for a specific type of event. This is the same as calling wade.isEventListener(SceneObject, eventName)

Parameters:


{string}eventName
The name of the event

Returns:


{boolean}
Whether the object is currently listening for the event
()
Check whether the scene object is currently moving

Returns:


{boolean}
Whether the scene object is currently moving
()
Check whether the SceneObject is currently visible on the screen

Returns:


{boolean}
Whether the SceneObject is currently visible on the screen
()
Check whether this object is a template. A template is a scene object that never receives any events, and is set to be invisible as soon as it's added to the scene

Returns:


{boolean}
whether this object is a template

(checkAllSprites)
Check if a scene object is visible. This returns true if at least one of the child sprites is visible, unless you set checkAllSprites to true, in which case this function only returns true if all sprites are visible.

Parameters:


{boolean}checkAllSpritesOptional, Default: false
Whether to check all sprites

Returns:


{boolean}
Whether the SceneObject is currently visible

(eventName)
Start listening for an event. This is the same as calling wade.addEventListener(SceneObject, eventName)

Parameters:


{string}eventName
The name of the event

(posX,
posY,
speed)
Move a scene object to the specified world space position, with a given speed

Parameters:


{number}posX
The X coordinate of the target position
{number}posY
The Y coordinate of the target position
{number}speed
The movement speed, in world space units per second

(object,
precision)
Check whether this scene object overlaps another scene object

Parameters:


{SceneObject}object
The other scene object to test
{string}precisionOptional
How accurate the test should be. This could be 'axis-aligned' (the default value when this parameter is omitted), which only considers the axis-aligned bounding boxes of both Sprites; 'oriented' which takes into account the rotations of both Sprites; or 'pixel' that does a (much slower) per-pixel test, discarding transparent pixels.

Returns:


{boolean}
Whether the two scene objects overlap each other

(sprite,
precision)
Check whether this scene object overlaps a sprite

Parameters:


{Sprite}sprite
The sprite to test
{string}precisionOptional
How accurate the test should be. This could be 'axis-aligned' (the default value when this parameter is omitted), which only considers the axis-aligned bounding boxes of both Sprites; 'oriented' which takes into account the rotations of both Sprites; or 'pixel' that does a (much slower) per-pixel test, discarding transparent pixels.*

Returns:


{boolean}
Whether the scene object and the sprite overlap each other

(name,
direction)
Play an animation on all the sprites of the scene object that have an animation with a matching name

Parameters:


{string}name
The animation name
{string}directionOptional
The direction of the animation. It can be 'forward', 'reverse' or 'ping-pong' (which means forward and then reverse). Default is 'forward'

(functionName,
data)
Execute a function of this object and its behaviors. If the scene object or any of its behaviors have member functions matching the functionName parameter, those functions will be called and will be passed the data parameter

Parameters:


{string}functionName
The name of the function(s) to execute
dataOptional
The data to pass to the functions. This can be any type and is optional.

Returns:


{boolean}
Whether any of the functions called returned a truthy value.

(eventName,
eventData)
Process an event for the scene object and all its behaviors. If the scene object or any of its behaviors have member functions matching the eventName parameter, those functions will be called, passing the eventData parameter

Parameters:


{string}eventName
The name of the event to process
{Object}eventDataOptional
The data to pass to the functions that will be called

Returns:


{Boolean}
Whether any of the functions called return a truthy value.
()
Remove all the sprites from the scene object.


(name)
Remove a behavior from a scene object

Parameters:


{string}name
The name of the behavior to remove

Returns:


{boolean}
Whether any behavior with the specified name was found and removed

(index)
Remove a behavior from a scene object, using the behavior index

Parameters:


{number}index
The index of the behavior to remove

(sprite)
Remove a sprite from the scene object

Parameters:


{Sprite}sprite
The sprite to remove

(index)
Remove a sprite from the scene object, given a sprite index

Parameters:


{number}index
The sprite to remove
()
Resume playing any animations that had been stopped


(angle,
angularVelocity)
Gradually rotate an object towards a target angle

Parameters:


{number}angle
The target angle (in radians)
{number}angularVelocity
The angular velocity (in radians per second)

(time,
functionName,
data)
Schedule the execution and processing of a function for this object. The scheduled function will be cancelled when the object is removed from the scene, or when SceneObject.unschedule is called

Parameters:


{number}time
How many milliseconds to wait before firing the event
{string}functionName
The name of the function to execute for this object. If the object or any of its behaviors have a function with this name, it will be executed
{object}dataOptional
The data to pass to the event function

(stringify,
propertiesToExclude,
serializeFunctions)
Export this SceneObject to an object that can then be used to create a new SceneObject like this one (by passing the resulting object to the SceneObject constructor).

Parameters:


{boolean}stringifyOptional
Whether the resulting object should be serialized to JSON. If this is set to true, this function returns a string representation of the scene object.
{Array}propertiesToExcludeOptional
An array of strings that contains the name of the properties of this SceneObject that you do NOT want to export.
{boolean}serializeFunctionsOptional
Whether to serialize functions (such as onMouseDown, etc). False by default

Returns:


{object|string}
An object that represents the current scene object

(leftRight,
topBottom)
Set the screen alignment of a scene object. This determines where the object is positioned following a resize event

Parameters:


{string}leftRightOptional
If this is 'left' or 'right', the distance between the object and one edge of the screen will be kept constant after a resize event
{string}topBottomOptional
If this is 'top' or 'bottom', the distance between the object and one edge of the screen will be kept constant after a resize event

(velocity)
Set the angular velocity of the object.

Parameters:


{number}velocity
The angular velocity of the object, in radians per second

(toggle)
Set a scene object to be a template. A template is a scene object that never receives any events, and is set to be invisible as soon as it's added to the scene. By default, scene objects are note templates.

Parameters:


{boolean}toggleOptional
Whether this scene object should be a template or not. If omitted, this parameter is assumed to be true.

(flowChartData)
Assigns a flow chart to this SceneObject. If the object is already in the scene, the flow chart is executed immediately. If the object is not in the scene, the flow chart is executed the next time (and every time) the object is added to the scene. In any case, the flow chart is cancelled when the object is removed from the scene. This means that any node in the chart that is supposed to be executed when the object is not in the scene will not be executed. However the active node (even those that include asynchrnous operations) will always be fully executed.

Parameters:


{object}flowChartData
A data structure describing the flow chart. See the documentation of wade.runFlowChart() for details.

(name)
Set a name for the scene object, so it can be retrieved via wade.getSceneObject(). Note that you can't have more objects with the same name in the scene at the same time.

Parameters:


{string}nameOptional
The name to set

(path,
setInitialValues,
speedMultiplier)
Set the currently active Path for this SceneObject. The SceneObject will start following the path immediately.

Parameters:


{Path|string}path
A Path object, or the name of a path that is currently in the scene.
{boolean}setInitialValuesOptional
Whether the object and its sprite should be scanned to set the initial values of all properties that are used on Node 1 (the second node) of the path. Note that this effectively creates a copy of the path, it doesn't modify the original one.
{number}speedMultiplierOptional, Default: 1
A factor to multiply the base speed defined in the path data

(positionX,
positionY)
Set the world space position of the scene object. The position of all its sprites will be updated accordingly.

Parameters:


{number|Object}positionX
A coordinate for the horizontal axis, or an object with 'x' and 'y' fields representing world space coordinates
{number}positionYOptional
A coordinate for the vertical axis

(rotation)
Set a rotation angle for the scene object

Parameters:


{number}rotation
The rotation angle in radians. A positive value indicates a clockwise rotation

(indexOrName,
offset)
Set the position of a sprite relative to the position of the scene object

Parameters:


{number}indexOrName
The sprite index or the name of the sprite
{Object}offset
An object with optional 'x' and 'y' fields representing the sprite offset and an 'angle' field representing the angular offset

(spriteOffsets)
Set the world space position offsets for the sprites of the scene object (i.e. the sprite positions relative to the scene object's position)

Parameters:


{Object}spriteOffsets
An object, or an array of objects, with optional 'x' and 'y' fields representing the position offsets and an 'angle' field representing the angular offsets

(velocityX,
velocityY)
Set the current linear velocity of the object. Note that calling this function on an object that is moving towards a specific target (that had been set with a call to moveTo) will cancel the current movement towards the target.

Parameters:


{number|{x: number|y: number}}velocityX
The x component of the velocity (a number), or an object with x and y fields representing the linear velocity of the object
{number}velocityY
The y component of the velocity

(toggle)
Show or hide a scene object

Parameters:


{boolean}toggle
Whether to show the scene object
()
Perform a simulation step for the scene object.
This function is called automatically by WADE, that aims to maintain a constant calling rate where possible (30Hz by default).

()
Stop any animations that are currently playing


(eventName)
Stop listening for an event. This is the same as calling wade.removeEventListener(SceneObject, eventName)

Parameters:


{string}eventName
The name of the event
()
Stop a scene object that is currently moving. An 'onMoveComplete' event will be triggered.


(numColumns,
numRows,
marginX,
marginY)
Create a grid of clones of this SceneObject. This SceneObject becomes the top-left element of the grid

Parameters:


{number}numColumns
The number of columns in the grid
{number}numRows
The number of rows in the grid
{number}marginXOptional
The horizontal spacing between columns (in world units). This is 0 by default
{number}marginYOptional
The vertical spacing between rows (in world units). This is 0 by default

Returns:


{Array}
A bidimensional array containing all grid elements. The element at column X and row Y can be accessed via returnValue[x][y]. Column and row indices start at 0

(eventName)
Cancel any scheduled events with the given name for this object

Parameters:


{string}eventName
The name of the scheduled event to cancel