Class: core/AnimationFeature

core/AnimationFeature(host)

Feature for managing animations on an object.

Constructor

new core/AnimationFeature(host)

Parameters:
Name Type Description
host core/HostObject

Host object that owns the feature.

Properties:
Name Type Description
EVENTS Object

Built-in messages that the feature emits. When the
feature is added to a core/HostObject, event names will be prefixed by the
name of the feature class + '.'.

Properties
Name Type Attributes Default Description
addLayer string <optional>
onAddLayerEvent

Message that is emitted after
addLayer has been successfully executed.
An object representing the name of the layer that was added and its index in
the layer stack with the signature {name: string, index: number} is supplied
as an argument to listener functions.

removeLayer string <optional>
onRemoveLayerEvent

Message that is
emitted after removeLayer has been
successfully executed. An object representing the name of the layer that was
removed and its index in the layer stack with the signature {name: string, index: number}
is supplied as an argument to listener functions.

renameLayer string <optional>
onRenameLayerEvent

Message that is
emitted after renameLayer has been
successfully executed. An object representing the original name of the layer
that was renamed and its updated name with the signature {oldName: string, newName: string}
is supplied as an argument to listener functions.

addAnimation string <optional>
onAddAnimationEvent

Message that is
emitted after addAnimation has been
successfully executed. An object representing the name of the layer that the
animation was added to and the name of the animation that was added with the
signature {layerName: string, animationName: string} is supplied as an argument
to listener functions.

removeAnimation string <optional>
onRemovedAnimationEvent

Message
that is emitted after removeAnimation
has been successfully executed. An object representing the name of the layer
that the animation was removed from and the name of the animation that was removed
with the signature {layerName: string, animationName: string} is supplied as
an argument to listener functions.

renameAnimation string <optional>
onRenameAnimationEvent

Message
that is emitted after renameAnimation
has been successfully executed. An object representing the name of the layer
that contains the animation that was renamed, the original name of the animation
that was renamed and its updated name with the signature {layerName: string, oldName: string, newName: string}
is supplied as an argument to listener functions.

play string <optional>
onPlayEvent

Message that is emitted after
each call to play. An object representing
the name of the layer contains the animation that was played and the name of
the animation that was played with the signature {layerName: string, animationName: string}
is supplied as an argument to listener functions.

pause string <optional>
onPauseEvent

Message that is emitted after
each call to pause. An object representing
the name of the layer contains the animation that was paused and the name of
the animation that was paused with the signature {layerName: string, animationName: string}
is supplied as an argument to listener functions.

resume string <optional>
onResumeEvent

Message that is emitted after
each call to resume. An object representing
the name of the layer contains the animation that was resumed and the name of
the animation that was resumed with the signature {layerName: string, animationName: string}
is supplied as an argument to listener functions.

interrupt string <optional>
onInterruptEvent

Message that is emitted
if there is a current speech in progress and play
or resume are executed for a new speech.
An object representing the name of the layer contains the animation that was
interrupted and the name of the animation that was interrupted with the signature
{layerName: string, animationName: string} is supplied as an argument to listener
functions.

stop string <optional>
onStopEvent

Message that is emitted after
each call to stop and when a speech reaches
the end of playback. An object representing
the name of the layer contains the animation that was stopped and the name of
the animation that was stopped with the signature {layerName: string, animationName: string}
is supplied as an argument to listener functions.

Extends

Members

(readonly) host

Gets the host that manages the feature.

Overrides:

(readonly) layers :Array.<string>

Gets an array of names of animation layers.

Type:
  • Array.<string>

(readonly) owner

Gets the engine owner object of the host.

Overrides:

(readonly) paused :boolean

Gets whether or not all animations are paused.

Type:
  • boolean

Methods

addAnimation(layerName, animationName, optionsopt) → {string}

Add a new animation to an animation layer.

Parameters:
Name Type Attributes Description
layerName string

Name of the layer to add the animation to.

animationName string

Name to use when calling the animation.

options Object <optional>

Options to pass to the constructor for the new
SingleState animation.

Returns:
  • The name of the animation that was added
Type
string

addLayer(nameopt, optionsopt, indexopt) → {number}

Create and store a new animation layer.

Parameters:
Name Type Attributes Default Description
name string <optional>
'NewLayer'

Name for the layer.

options Object <optional>
{}

Options to pass to AnimationLayer#constructor

index index <optional>

Index to insert the new layer at. If none is provided
it will be added to the end of the stack.

Returns:

Index of the new layer.

Type
number

discard()

Clean up once the feature is no longer in use. Remove the feature namespace
from the host and remove reference to the host.

Overrides:

emit(message, valueopt)

Emit feature messages from the host. Feature messages will be prefixed with
the class name of the feature.

Parameters:
Name Type Attributes Description
message string

The message to emit.

value any <optional>

Optional parameter to pass to listener callbacks.

Overrides:

getAnimationBlendNames(layerName, animationName) → {Array.<string>}

Returns the names of blend states in an animation in a layer.

Parameters:
Name Type Description
layerName string

Name of the layer containing the animation containing
the blend state to update.

animationName string

Name of the animation containing the blend state
to update.

Returns:
  • Names of blend states.
Type
Array.<string>

getAnimationBlendWeight(layerName, animationName, blendName) → {number}

Returns the weight for a blend state in an animation in a layer.

Parameters:
Name Type Description
layerName string

Name of the layer containing the animation containing
the blend state to update.

animationName string

Name of the animation containing the blend state
to update.

blendName string

Name of the blend state to update.

Returns:
  • Weight of the blend state.
Type
number

getAnimations(layerName) → {Array.<string>}

Return an array of the names of all states the layer with the given name controls.

Parameters:
Name Type Description
layerName string

Name of the layer to search.

Returns:
Type
Array.<string>

getAnimationType(layerName, animationName) → {string}

Return the type name of the given animation. @see AnimationTypes.

Parameters:
Name Type Description
layerName string

Name of the layer that contains the animation.

animationName string

Name of the animation to check.

Returns:
Type
string

getCurrentAnimation(layerName) → {string|null}

Return the name of the state currently active on the layer with the given name.
Return null if there is no current animation for the layer.

Parameters:
Name Type Description
layerName string

Name of the layer.

Returns:
Type
string | null

getLayerWeight(name) → {number}

Return the weight of an animation layer.

Parameters:
Name Type Description
name string

Name of the layer to return weight from.

Returns:
Type
number

getPaused(layerName) → {boolean}

Return whether or not a layer with the given name is currently playing an
animation and that animation is paused.

Parameters:
Name Type Description
layerName string

Name of the layer.

Returns:
Type
boolean

getTransitioning(layerName) → {boolean}

Return whether or not the animation layer with the given name is currently
transitioning between animations.

Parameters:
Name Type Description
layerName string

Name of the layer to check.

Returns:
Type
boolean

installApi()

Adds a namespace to the host with the name of the feature to contain properties
and methods from the feature that users of the host need access to.

Overrides:
See:

listenTo(message, callback)

Listen to a feature message from the host object.

Parameters:
Name Type Description
message string

Message to listen for.

callback function

The callback to execute when the message is received.

Overrides:

moveLayer(name, index) → {number}

Re-order the layer stack so that the layer with the given name is positioned
at the given index.

Parameters:
Name Type Description
name string

Name of the layer to move.

index number

New index to position the layer at.

Returns:

The new index of the layer

Type
number

pause() → {boolean}

Pause current animation and weight interpolation animation on all layers.

Returns:
  • Whether or not there was an existing interpolation or
    current animations to pause.
Type
boolean

pauseAnimation(name) → {boolean}

Pause the current animation on a layer.

Parameters:
Name Type Description
name string

Name of the layer to pause.

Returns:

Whether or not an animation was successfully paused.

Type
boolean

pauseLayer(name) → {boolean}

Pause current animation and weight interpolation animation on a layer with
the given name.

Parameters:
Name Type Description
name string

Name of the layer to pause.

Returns:
  • Whether or not there was an existing interpolation or
    current animation to pause.
Type
boolean

pauseLayerWeight(name) → {boolean}

Pause weight interpolation animation on a layer with the given name.

Parameters:
Name Type Description
name string

Name of the layer to pause.

Returns:
  • Whether or not there was an existing interpolation to pause.
Type
boolean

playAnimation(layerName, animationName, secondsopt, easingFnopt) → {Deferred}

Pause the currently playing animation and play a new animation from the beginning.

Parameters:
Name Type Attributes Description
layerName string

Name of the layer that contains the animation.

animationName string

Name of the animation state to play.

seconds number <optional>

The number of seconds it should take to transition
to the new animation. Default is zero and will set immediately.

easingFn function <optional>

The easing function to use while transitioning
between animations. Default is Easing.Linear.InOut.

Returns:
  • Resolves once the animation reaches the end of its
    timeline. Looping animations can only resolve if they are interrupted or
    manually stopped.
Type
Deferred

playNextAnimation(layerName, animationNameopt, secondsopt, easingFnopt) → {Deferred}

Play the next animation in the queue of a QueueState animation.

Parameters:
Name Type Attributes Description
layerName string

Name of the layer that contains the queue animation.

animationName string <optional>

Name of the animation queue animation. Defaults
to the name of the current animation for the layer.

seconds number <optional>

The number of seconds it should take to transition
to the queue animation if it's not already currently playing. Default is zero
and will set immediately.

easingFn function <optional>

The easing function to use while transitioning
to the queue animation if it isn't already playing. Default is Easing.Linear.InOut.

Returns:
  • Resolves once the last animation in the queue finishes
    playing.
Type
Deferred

removeAnimation(layerName, name) → {boolean}

Remove an animation from an animation layer.

Parameters:
Name Type Description
layerName string

Name of the layer to remove the animation from.

name string

Name of the animation to remove.

Returns:
Type
boolean

removeLayer(name) → {boolean}

Remove an animation layer from the stack. Animations on this layer will no
longer be evaluated.

Parameters:
Name Type Description
name string

Name for the layer to remove.

Returns:

Whether or not removal was successful.

Type
boolean

renameAnimation(layerName, currentAnimationName, newAnimationName) → {string}

Update the name of an animation. Names must be unique on each layer, if the new
name is not unique it will have trailing numbers appended until it is unique.

Parameters:
Name Type Description
layerName string

Name of the layer that contains the animation that
will be renamed,

currentAnimationName string

Current name of the animation.

newAnimationName string

New name to set on the animation.

Returns:
  • The new name of the animation
Type
string

renameLayer(currentName, newName) → {string}

Update the name of a layer. Names must be unique, if the new name is not
unique it will have trailing numbers appended until it is unique.

Parameters:
Name Type Description
currentName string

Current name of the layer.

newName string

New name to set on the layer.

Returns:

The new name of the layer

Type
string

resume() → {boolean}

Resume current animation and weight interpolation animation on all layers.

Returns:
  • Whether or not there was an existing interpolation or
    current animations to resume.
Type
boolean

resumeAnimation(layerName, animationNameopt, secondsopt, easingFnopt) → {Deferred}

Pause the currently playing animation and play a new animation from where it
last left off.

Parameters:
Name Type Attributes Description
layerName string

Name of the layer that contains the animation.

animationName string <optional>

Name of the animation state to resume. Defaults
to the name of the current animation for the layer.

seconds number <optional>

The number of seconds it should take to transition
to the new animation. Default is zero and will set immediately.

easingFn function <optional>

The easing function to use while transitioning
between animations. Default is Easing.Linear.InOut.

Returns:
  • Resolves once the animation reaches the end of its
    timeline. Looping animations can only resolve if they are interrupted or
    manually stopped.
Type
Deferred

resumeLayer(name) → {Deferred}

Resume current animation and weight interpolation animation on a layer with
the given name.

Parameters:
Name Type Description
name string

Name of the layer to resume.

Returns:
  • Resolves once the layer's weight reaches its target value
    and it's current animation finishes playing.
Type
Deferred

resumeLayerWeight(name) → {Deferred}

Resume weight interpolation animation on a layer with the given name.

Parameters:
Name Type Description
name string

Name of the layer to resume.

Returns:
  • Resolves once the layer's weight reaches its target value.
Type
Deferred

setAnimationBlendWeight(layerName, animationName, blendName, weight, secondsopt, easingFnopt) → {Deferred}

Update the weight for a blend state in an animation in a layer.

Parameters:
Name Type Attributes Description
layerName string

Name of the layer containing the animation containing
the blend state to update.

animationName string

Name of the animation containing the blend state
to update.

blendName string

Name of the blend state to update.

weight number

Weight value to set on the animation. This number shoudld be
in the 0-1 range.

seconds number <optional>

Number of seconds it should take to reach the new weight.
Default is zero and will set immediately.

easingFn function <optional>

Easing function to use while interpolating the new
weight. Default is Easing.Linear.InOut.

Returns:
  • Promise that will resolve once the animation's weight reaches
    the target value.
Type
Deferred

setLayerWeight(name, weight, secondsopt, easingFnopt) → {Deferred}

Update the weight of an animation layer.

Parameters:
Name Type Attributes Description
name string

The name of the layer to update.

weight number

The weight value to set on the layer. This number
should be in the 0-1 range.

seconds number <optional>

The number of seconds it should take to reach the
new weight. Default is zero and will set immediately.

easingFn function <optional>

The easing function to use while interpolating
the weight. Default is Easing.Linear.InOut.

Returns:

A promise that will resolve once the layer's weight reaches
the target value.

Type
Deferred

stopAnimation(name) → {boolean}

Stop the current animation on a layer. Stop rewinds the animation to the
beginning and prevents it from progressing forward.

Parameters:
Name Type Description
name string

Name of the layer that contains the animation.

Returns:

Whether or not an animation was successfully stopped.

Type
boolean

stopListening(message, callbackopt)

Stop listening to a message from the host object.

Parameters:
Name Type Attributes Description
message string

Message to stop listening for.

callback function <optional>

Optional callback to remove. If none is defined,
remove all callbacks for the message.

Overrides:

stopListeningByRegexp(regexp, callbackopt)

Stop listening to a message matching the given regular expression from the
host object.

Parameters:
Name Type Attributes Description
regexp Regexp

The regular expression to stop listening for.

callback function <optional>

Optional callback to remove. If none is defined,
remove all callbacks for the message.

Overrides:

stopListeningToAll()

Stop listening to all messages.

Overrides:

update(deltaTime)

Update each animation layer.

Parameters:
Name Type Description
deltaTime number

Time since the last update.

Overrides: