Class SceneObject
Constructor Attributes | Constructor Name and Description |
---|---|
SceneObject(sprites, behaviors, posX, posY, name)
A Scene Object is an entity that can be added to the scene in WADE.
|
Method Attributes | Method Name and Description |
---|---|
addBehavior(behaviorClass)
Add a behavior to the scene object
|
|
addSprite(sprite, offset, index)
Add a sprite to the scene object
|
|
clone()
Clone the scene object
|
|
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
|
|
getBehaviorByIndex(index)
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 the scene object's movement speed
|
|
getName()
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
|
|
getPath()
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).
|
|
getSpriteByName(name)
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
|
|
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.
|
|
isMoving()
Check whether the scene object is currently moving
|
|
Check whether this object is a template.
|
|
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)
Check whether this scene object overlaps another scene object
|
|
overlapsSprite(sprite)
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.
|
|
removeBehavior(name)
Remove a behavior from a scene object
|
|
removeBehaviorByIndex(index)
Remove a behavior from a scene object, using the behavior index
|
|
removeSprite(sprite)
Remove a sprite from the scene object
|
|
removeSpriteByIndex(index)
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.
|
|
setName(name)
Set a name for the scene object, so it can be retrieved via wade.getSceneObject().
|
|
setPath(path, setInitialValues)
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.
|
|
unschedule(eventName)
Cancel any scheduled events with the given name for this object
|
|
Cancel all scheduled events for this object
|
Class Detail
SceneObject(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} sprites Optional
- 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} behaviors Optional
- A behavior function, or an array of behavior functions
- {number} posX Optional, Default: 0
- The X coordinate of the initial world space position
- {number} posY Optional, Default: 0
- The Y coordinate of the initial world space position
- {string} name Optional
- 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: {}}, 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 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.
Method Detail
{Object}
addBehavior(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.
{number}
addSprite(sprite, offset, index)
Add a sprite to the scene object
- Parameters:
- {Sprite} sprite
- The sprite to add
- {object} offset Optional
- 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} index Optional
- 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
{object}
clone()
Clone the scene object
- 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.
fadeIn(time, callback)
Fade in effect, gradually changing the opacity (alpha) of the all the sprites of this object from 0 to 1
- 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} callback Optional
- A function to execute when the transition is over
fadeOut(time, callback)
Fade out effect, gradually changing the opacity (alpha) of the all the sprites of this object from 1 to 0
- 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} callback Optional
- A function to execute when the transition is over
{Object}
getAlignment()
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
{number}
getAngularVelocity()
Get the current angular velocity of the object
- Returns:
- {number} The angular velocity of the object, in radians per second
{Object}
getBehavior(name)
Get a behavior of the scene object
- Parameters:
- {string} name Optional
- 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.
{Object}
getBehaviorByIndex(index)
Get a behavior of the scene object, give its index in the array of behaviors
- Parameters:
- {number} index Optional
- 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.
{Array}
getBehaviors()
Get an array containing all the behaviors of this object
- Returns:
- {Array} An array containing all the behaviors of this object.
{number}
getMovementSpeed()
Get the scene object's movement speed
- Returns:
- {number} The current movement speed
{string}
getName()
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
{Array}
getOverlappingObjects(searchAllLayers, precision)
Get an array of objects overlapping this object
- Parameters:
- {boolean} searchAllLayers Optional
- 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} precision Optional
- 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
{Path}
getPath()
Get the currently active Path for this SceneObject
- Returns:
- {Path} The currently active path.
{Object}
getPosition()
Get the world space position of the scene object
- Returns:
- {Object} An object with 'x' and 'y' field representing world space coordinates
{number}
getRotation()
Get the current rotation angle of the scene object
- Returns:
- {number} The current rotation angle in radians. A positive value indicates a clockwise rotation
{Sprite|undefined}
getSprite(index)
Get the sprite object corresponding to a given sprite index
- Parameters:
- {number} index Optional
- The sprite index. If omitted or falsy, the first sprite is returned.
- Returns:
- {Sprite|undefined} The sprite object
{Object}
getSpriteAtPosition(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.
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
{Sprite}
getSpriteByName(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
{number}
getSpriteCount()
Get the number of sprites in the scene object
- Returns:
- {number} The number of sprites
{number}
getSpriteIndex(sprite)
Get the current index of a sprite
- Parameters:
- {Sprite} sprite
- The sprite to look for
- Returns:
- {number} The index of the sprite
{Object}
getSpriteOffset(indexOrName)
Get the position of a sprite relative to the position of its parent scene object
- Parameters:
- {number} indexOrName Optional
- 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
{Object}
getTargetPosition()
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
{number}
getTargetRotation()
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
{{x: number|y: number}}
getVelocity()
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
importFunctions(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.
{Boolean}
isAnimating()
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
{boolean}
isInScene()
Check whether the scene object is in the scene
- Returns:
- {boolean} Whether the scene object is in the scene
{boolean}
isListeningFor(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
{boolean}
isMoving()
Check whether the scene object is currently moving
- Returns:
- {boolean} Whether the scene object is currently moving
{boolean}
isTemplate()
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
listenFor(eventName)
Start listening for an event. This is the same as calling wade.addEventListener(SceneObject, eventName)
- Parameters:
- {string} eventName
- The name of the event
moveTo(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
{boolean}
overlapsObject(object)
Check whether this scene object overlaps another scene object
- Parameters:
- {SceneObject} object
- The other scene object to test
- Returns:
- {boolean} Whether the two scene objects overlap each other
{boolean}
overlapsSprite(sprite)
Check whether this scene object overlaps a sprite
- Parameters:
- {Sprite} sprite
- The sprite to test
- Returns:
- {boolean} Whether the scene object and the sprite overlap each other
playAnimation(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} direction Optional
- The direction of the animation. It can be 'forward', 'reverse' or 'ping-pong' (which means forward and then reverse). Default is 'forward'
{boolean}
process(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
- data Optional
- 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.
{Boolean}
processEvent(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} eventData Optional
- The data to pass to the functions that will be called
- Returns:
- {Boolean} Whether any of the functions called return a truthy value.
removeAllSprites()
Remove all the sprites from the scene object.
{boolean}
removeBehavior(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
removeBehaviorByIndex(index)
Remove a behavior from a scene object, using the behavior index
- Parameters:
- {number} index
- The index of the behavior to remove
removeSprite(sprite)
Remove a sprite from the scene object
- Parameters:
- {Sprite} sprite
- The sprite to remove
removeSpriteByIndex(index)
Remove a sprite from the scene object, given a sprite index
- Parameters:
- {number} index
- The sprite to remove
resumeAnimation()
Resume playing any animations that had been stopped
rotateTo(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)
schedule(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.
- 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} data Optional
- The data to pass to the event function
{object|string}
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).
- Parameters:
- {boolean} stringify Optional
- 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} propertiesToExclude Optional
- An array of strings that contains the name of the properties of this SceneObject that you do NOT want to export.
- {boolean} serializeFunctions Optional
- Whether to serialize functions (such as onMouseDown, etc). False by default
- Returns:
- {object|string} An object that represents the current scene object
setAlignment(leftRight, topBottom)
Set the screen alignment of a scene object. This determines where the object is positioned following a resize event
- Parameters:
- {string} leftRight Optional
- 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} topBottom Optional
- 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
setAngularVelocity(velocity)
Set the angular velocity of the object.
- Parameters:
- {number} velocity
- The angular velocity of the object, in radians per second
setAsTemplate(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} toggle Optional
- Whether this scene object should be a template or not. If omitted, this parameter is assumed to be true.
setName(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} name Optional
- The name to set
setPath(path, setInitialValues)
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} setInitialValues Optional
- 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.
setPosition(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} positionY Optional
- A coordinate for the vertical axis
setRotation(rotation)
Set a rotation angle for the scene object
- Parameters:
- {number} rotation
- The rotation angle in radians. A positive value indicates a clockwise rotation
setSpriteOffset(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
setSpriteOffsets(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
setVelocity(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
setVisible(toggle)
Show or hide a scene object
- Parameters:
- {boolean} toggle
- Whether to show the scene object
step()
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).
This function is called automatically by WADE, that aims to maintain a constant calling rate where possible (30Hz by default).
stopAnimation()
Stop any animations that are currently playing
stopListeningFor(eventName)
Stop listening for an event. This is the same as calling wade.removeEventListener(SceneObject, eventName)
- Parameters:
- {string} eventName
- The name of the event
stopMoving()
Stop a scene object that is currently moving. An 'onMoveComplete' event will be triggered.
unschedule(eventName)
Cancel any scheduled events with the given name for this object
- Parameters:
- {string} eventName
- The name of the scheduled event to cancel
unscheduleAll()
Cancel all scheduled events for this object