SpriteBase Guide

Introduction

"SpriteBase" is a known engine type that handles the rendering properites of the scene objects "Sprite" and "Scroller". SpriteBase is derived from a base type called "SceneObject". That means it includes all the fields from that type as well as adding its own fields specific to itself.

Although it handles the assignment of image properties, a SpriteBase object cannot render itself within a scene. As such, it is not included in the list of scene objects available for use within a game.

TorqueScript Bindings

• SpriteBase

Exposed Fields

The SpriteBase type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

• Image
• setImage(imageAssetId)
• getImage()
• Frame
• setImageFrame(int)
• getImageFrame()
• NamedFrame
• setNamedImageFrame(frame)
• getNamedImageFrame()
• Animation
• playAnimation(animationAssetId)

It is playAnimation here, but setAnimation on a GuiSpriteCtrl. The scene object and the GUI control name this differently, so code copied from one to the other fails with an unknown-command warning rather than anything that points at the cause.

• getAnimation()

The following is a complete description of each of these fields.

Image (imageAssetId)

Specifies the ImageAsset to be used for the object derived from SpriteBase. This must be given as a valid ImageAsset ID.

%object.Image = "ToyAssets:Tiles";

Frame (int)

Sets the object derived from SpriteBase to use the specified image frame.

%object.Frame = 1;

NamedFrame (string)

When the ImageAsset uses named cells (explicit/named mode), selects the frame by its name rather than its numeric index. The object must be a static frame provider (i.e. not currently playing an animation).

%object.NamedFrame = "doorOpen";

Animation (animationAssetId)

Specifies the AnimationAsset to be used for the object derived from SpriteBase. This must be given as a valid AnimationAsset ID.

%object.Animation = "ToyAssets:TileAnimation";

Callbacks

The SpriteBase type has the following callbacks in addition to those it inherits.

onAnimationEnd (%this)

This is called when the animation reaches the last frame it is supposed to play. Note that a looping animation would not trigger this callback as the animation continues from the last frame back to the first frame without stopping.

Additional API

The following methods are available to further configure and control SpriteBase or its derived object classes.

isStaticFrameProvider(bool)

Gets whether the sprite is in static or dynamic (animated) mode.

pauseAnimation(bool)

If true, this pauses the current animation. When set to false, the animation will continue its playback.

stopAnimation()

Stops the current animation. This also results in a reset of the animation cycle, so the animation would start at the beginning if played again.

setAnimationFrame(int)

This manually sets the frame of the animation to play.

getAnimationFrame()

Gets the current animation frame.

getAnimationTime()

Gets the current animation time.

getIsAnimationFinished()

Checks the animation status to find out whether the animation has finished playing or not.

setAnimationTimeScale(float)

This method will change the rate of animation. It scales the animation speed, with a speed of 1 being the default.

getAnimationTimeScale()

This method will return the value of the animation time scale.