Skip to content

AnimationAsset Guide

Jump to bottom
Peter Robinson edited this page Jul 5, 2020 · 2 revisions

Introduction

All assets are known engine types that allow instances to be created at runtime. The "AnimationAsset", like all assets, is derived from a base type of "AssetBase". That means it includes all the fields from that type as well as adding its own fields specific to itself.

The AnimationAsset provides a way to refer to any ImageAsset that contains frames and select those frames for playing in a specified order to produce an animation of images.

For an AnimationAsset to be valid, it must contain at least a single frame selected from a valid ImageAsset.

TorqueScript Bindings

Exposed Fields

The AnimationAsset 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()
  • AnimationFrames
    • setAnimationFrames(string)
    • getAnimationFrames()
  • NamedAnimationFrames
    • setNamedAnimationFrames(string)
    • getNamedAnimationFrames()
  • AnimationTime
    • setAnimationTime(float)
    • getAnimationTime();
  • AnimationCycle
    • setAnimationCycle(bool)
    • getAnimationCycle()
  • RandomStart
    • setRandomStart(bool)
    • getRandomStart()
  • NamedCellsMode
    • setNamedCellsMode(bool)
    • getNamedCellsMode()

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

Image (string)

This is a mandatory field and refers to the image asset that should be used as the source for frames. This field should be an asset-Id that refers to an ImageAsset. If it does not refer to a valid asset (or the module the asset is defined in has not been loaded) or it is not an ImageAsset or the asset is not valid then the animation is not be valid.

An example is:

<AnimationAsset
    AnimationName="FireAnimation"
    Image="EffectsModule:FireImage"
...
/>

This example defines an animation named "FireAnimation" and refers to an ImageAsset named "FireImage" in the "EffectsModule" i.e. its asset-Id is "EffectsModule:FireImage".

AnimationFrames

This is a mandatory field only when NamedCellsMode is left at its default false value. This specifies the actual frames to use from the selected ImageAsset. You can select any number of frames and use each as many times as you like:

<AnimationAsset
    AnimationName="FireAnimation"
    Image="EffectsModule:FireImage"
    AnimationFrames="0 1 2 3 4 5 4 3 2 1"
/>

This example defines an animation that plays, in sequence, frames 0 to 5 to 1 i.e. it is a 10 frame animation.

NamedAnimationFrames

This is a mandatory field only when NamedCellsMode is true. This specifies the actual frame names to use from the selected ImageAsset. You can select any number of frames and use each as many times as you like:

<AnimationAsset
    AnimationName="ExtinguishFireAnimation"
    Image="EffectsModule:ExplicitFireImage"
    NamedCellsMode="true"
    NamedAnimationFrames="fire_01 fire_02 fire_03 fireWithSmoke_01 fireWithSmoke_02 onlySmoke"
/>

This example defines a 6 frame animation sequence.

AnimationTime

Whilst this field is not mandatory as it defaults to one (second), it's obviously important in determining how fast the animation runs.

The animation time is how long it takes, in seconds, for the animation to play *all the specified animation frames.

<AnimationAsset
    AnimationName="FireAnimation"
    Image="EffectsModule:FireImage"
    AnimationFrames="0 1 2 3 4 5 4 3 2 1"
    AnimationTime="5"    
/>

This example plays all 10 frames in 5 seconds i.e. 0.5 seconds per frame. You are free to use any value greater than zero including floating-point values.

AnimationCycle

This is an optional field that controls whether the animation, when reaching the end of the selected frames should start again at the beginning or not. By default, animation cycle is true therefore all animations are "cyclic" animations by default therefore unless you want an animation that plays only once then you do not need to specify it.

<AnimationAsset
    AnimationName="FireAnimation"
    Image="EffectsModule:FireImage"
    AnimationFrames="0 1 2 3 4 5 4 3 2 1"
    AnimationTime="5"    
    AnimationCycle="false"
/>

The example plays all 10 frame 0 to 5 to 1 then stops because the animation cycle is false.

RandomStart

This is an optional field that controls whether the animation, when starting, should start at a random selection of one of the specified frames. By default, random start is off therefore the animation will start at the first frame specified.

<AnimationAsset
    AnimationName="FireAnimation"
    Image="EffectsModule:FireImage"
    AnimationFrames="0 1 2 3 4 5 4 3 2 1"
    AnimationTime="5"    
    RandomStart="true"
/>

The example animation could start at any of the frames specified i.e. 0, 1, 2, 3, 4, 5, 4, 3, 2 or 1.

When starting lots of animations at the same time, having them all synchronized can look very odd, especially if the animation represents something typically random in nature such as fire, a flicker light, a swarm of insects etc. By using random start, you ensure that all these animations appear more random.

NamedCellsMode

This is an optional field that specifies whether the animation frames are defined by their index number or with individual names. By default, this field is false which means the animation would be specified by the frame index from the referenced ImageAsset. This field can be seen in the example above for NamedAnimationFrames.

Additional API

The AnimationAsset exposes a few additional methods that can be useful under certain circumstances.

getAnimationFrameCount( [bool validatedFrames] )

getNamedAnimationFrameCount( [bool validatedFrames] )

These methods get the frames that compose the animation i.e. the frames originally specified in the TAML file. They are returned as a space-separated list identical to how they were originally specified.

More useful is that the animation frames specified are validated when the AnimationAsset is loaded. During this validation, any frames that don't exist in the specified ImageAsset are discounted.

Invalid frames don't invalidate the animation, they are simply dropped. This often occurs when an ImageAsset is changed after an AnimationAsset has established a set of frames. Reducing the number of frames in an ImageAsset might result in selected animation frames being invalid.

This method allows you to optionally retrieve these "validated" frames by simply passing in "true" as the optional argument. Again, this will return a space-separated list of frames.

In a fully valid animation, both the specified animations frames and the validated animation frames will result in an identical string with identical animation frames. This method at least allows you to determine something has gone wrong beyond seeing a warning in the console.

Clone this wiki locally