Sprite script interface

The ISpriteInstance interface derives from IWorldInstance to add APIs specific to the Sprite plugin.

Sprite events

See instance event for standard instance event object properties.

"framechange"
Fired when the currently displayed animation frame changes during playback of an animation. The event object has the additional properties:

  • animationName: a string of the name of the currently playing animation

  • animationFrame: a zero-based index with the animation frame number of the new frame in its animation
"animationend"
Fired when playback of the current animation reaches the end. The event object has the additional properties:

  • animationName: a string of the name of the animation that finished

Sprite APIs

animation
A reference to a IAnimation script interface representing the current animation, which can be used to access additional details such as the frames in the animation.
setAnimation(name, from = "beginning")
Set the current animation by a string of its name (case-insensitive). If the animation name does not exist, an exception will be thrown. from can be set to either "current-frame" to switch to the same frame index in the new animation, or "beginning" to rewind to the first frame.
getAnimation(name)
Get an IAnimation for an animation in the Sprite object by a case-insensitive string of its name. Returns null if no animation is found.
animationName
A read-only string of the current animation name. Use the setAnimation() method to change the animation.
startAnimation(from = "current-frame")
Start playback of the current animation. from can be set to either "current-frame" to play from the existing frame, or "beginning" to play from the first frame.
stopAnimation()
Stop playback of the current animation.
animationFrame
The zero-based index of the current animation frame.
animationFrameTag
A string of the current animation frame tag (which is an empty string when not set). If assigned a new tag, and the current animation has multiple animation frames with the same tag, then it will use the first one.
animationSpeed
The current animation playback speed, in animation frames per second.
animationRepeatToFrame
The zero-based index of the animation frame to rewind to when repeating an animation.
imageWidth
imageHeight
getImageSize()
Read-only numbers indicating the size of the current animation frame's source image, in pixels. The method allows getting both values at the same time.
getImagePointCount()
Return the number of image points on the current animation frame.
getImagePointX(nameOrIndex)
getImagePointY(nameOrIndex)
getImagePointZ(nameOrIndex)
getImagePoint(nameOrIndex)
Return the location of an image point on the current animation frame in layout co-ordinates. The Z co-ordinate can be useful when using 3D mesh distortion. Image points are identified either by a case-insensitive string of their name, or their index. Note image point 0 is the origin, so index 1 is the first image point. If the image point is not found, this returns the origin instead. The getImagePoint variant returns [x, y, z].
getPolyPointCount()
Return the number of collision polygon points on the current animation frame.
getPolyPointX(index)
getPolyPointY(index)
getPolyPoint(index)
Return the location of a collision polygon point on the current animation frame in layout co-ordinates, by its zero-based index. The getPolyPoint variant returns [x, y].
setSolidCollisionFilter(isInclusive, tags)
Enable or disable collisions with the Solid behavior according to tags. Specify tags using a string of space-separated tag names. If isInclusive is true, collisions are only enabled with solids that match any of the given tags; if no tags are specified, collisions are disabled with all solids. If isInclusive is false, collisions are disabled with solids that match any of the given tags; if no tags are specified, collisions are enabled for all solids (the default). See also the tags property of ISolidBehaviorInstance.
async replaceCurrentAnimationFrame(blob)
Replace the current animation frame image with the contents of a Blob representing an image file such as a PNG image. The blob can be locally generated or retrieved from a URL, for example:

// Loading an image from a URL
const response = await fetch(url);
const blob = await response.blob();
await spriteInst.replaceCurrentAnimationFrame(blob);
Construct 3 Manual 2024-02-14