ThreeJS AnimationAction

AnimationActions are used to schedule the playback of animations saved in AnimationClips.

Note that the majority of AnimationAction's methods can be chained together.

The "Animation System" page in the "Next Steps" part of the handbook provides an overview of the various elements of the three.js animation system.

Constructor

AnimationAction( mixer : AnimationMixer, clip : AnimationClip, localRoot : Object3D )

mixer - the AnimationMixer that is controlled by this action.

clip - the AnimationClip that holds the animation data for this action.

localRoot - the root object on which this action is performed.

Note: Instead of invoking this function Object() { [native code] } directly, use AnimationMixer to create an AnimationAction. Because clipAction supports caching for greater speed, it's a good choice.

Properties

.clampWhenFinished : Boolean

The animation will be automatically paused on its last frame if clampWhenFinished is set to true.

If clampWhenFinished is set to false, enabled will be converted to false when the action's last loop completes, ensuring that the action has no further effect.

The default value is false.

If the action is paused, clampWhenFinished has no effect (it has only an effect if its last loop has really finished).

.enabled : Boolean

When enabled is set to false, this action is disabled and has no effect. True is the default value.

The animation continues from the current time when the action is re-enabled (changing enabled to false does not restart the action).

Note that the setting enabled to true does not force the animation to restart. When enabled is set to true, the animation will only be restarted if the following condition is met: This activity has not been canceled in the interim (by issuing a stop or reset command), and neither weight nor timeScale is 0.

.loop : Number

The looping mode (can be changed with setLoop). Default is THREE.LoopRepeat (with an infinite number of repetitions)

Must be one of these constants:

• THREE.LoopOnce - playing the clip once,
• THREE.LoopRepeat - playing the clip with the chosen number of repetitions, each time jumping from the end of the clip directly to its beginning,
• THREE.LoopPingPong - playing the clip with the chosen number of repetitions, alternately playing forward and backward.

.paused : Boolean

By setting the effective time scale to 0 and setting paused to true, the action is paused. The default value is false.

.repetitions : Number

Over the course of this action, the number of times the AnimationClip has been performed. setLoop is a function that can be used to set the loop length. Infinity is set as the default value.

Setting this number has no effect if the loop mode is set to THREE.LoopOnce.

.time : Number

This action takes place at a specific time in the local area (in seconds, starting with 0).

0...clip.duration is clamped or wrapped around the value (according to the loop state). By altering timeScale, it can be scaled relative to the global mixer time (using setEffectiveTimeScale or setDuration).

.timeScale : Number

For the period, there is a scaling factor. The animation is paused when the value is 0. The animation will play backward if the value is negative. The default value is 1.

Properties/methods concerning timeScale (respectively time) are: getEffectiveTimeScale, halt, paused, setDuration, setEffectiveTimeScale, stopWarping, syncWith, warp.

.weight : Number

The degree of influence of this action (in the interval [0, 1]). Values between 0 (no impact) and 1 (full impact) can be used to blend between several actions. Default is 1.

Properties/methods concerning weight are: crossFadeFrom, crossFadeTo, enabled, fadeIn, fadeOut, getEffectiveWeight, setEffectiveWeight, stopFading.

.zeroSlopeAtEnd : Boolean

Allows for seamless interpolation without the need for a distinct start, loop, and finish clips. True is the default value.

.zeroSlopeAtStart : Boolean

Allows for seamless interpolation without the need for a distinct start, loop, and finish clips. True is the default value.

Methods

.crossFadeFrom ( fadeOutAction : AnimationAction, durationInSeconds : Number, warpBoolean : Boolean ) : this

Within the time interval, causes this action to fade in a while concurrently fading out another action. This approach can be used repeatedly.

Additional warping (gradual changes in time scales) will be applied if warpBoolean is true.

Note: The fading begins and ends with a weight of 1, just like fadeIn/fadeOut.

.crossFadeTo ( fadeInAction : AnimationAction, durationInSeconds : Number, warpBoolean : Boolean ) : this

This action fades out, while another action fades in at the same moment, inside the time interval. This approach can be used repeatedly.

Additional warping (gradual changes in time scales) will be applied if warpBoolean is true.

Note: The fading begins and ends with a weight of 1, just like fadeIn/fadeOut.

.fadeIn ( durationInSeconds : Number ) : this

Increases the weight of this action gradually from 0 to 1, within the passed time interval. This method can be chained.

.fadeOut ( durationInSeconds : Number ) : this

Decreases the weight of this action gradually from 1 to 0, within the passed time interval. This method can be chained.

.getEffectiveTimeScale () : Number

Returns the effective time scale

.getEffectiveWeight () : Number

Returns the effective weight

.getClip () : AnimationClip

Returns the clip which holds the animation data for this action.

.getMixer () : AnimationMixer

Returns the mixer, which is responsible for playing this action.

.getRoot () : Object3D

Returns the root object on which this action is performed.

.halt ( durationInSeconds : Number ) : this

Reduces the speed of this animation to 0 by gradually decreasing timeScale (beginning from its current value) over the passed time interval. This approach can be used repeatedly.

.isRunning () : Boolean

If the action's timer is currently running, this method returns true.

The following conditions must be met in addition to being activated in the mixer (see isScheduled): paused is equal to false, enabled is equal to true, timeScale is not equal to 0, and there is no scheduling for a delayed start (startAt).

Note that just because isRunning is true doesn't mean the animation can be viewed. Only if weight is also set to a non-zero value will this happen.

.isScheduled () : Boolean

Returns true if this action is activated in the mixer.

Note that this does not always imply that the animation is active (compare the additional conditions for isRunning).

.play () : this

This command instructs the mixer to begin the action. This approach can be used repeatedly.

Note that activating this action does not guarantee that the animation will begin immediately: A reset is required if the action has already been completed (by reaching the end of its last loop) or if a time for a delayed start has been provided (through startAt).

.reset () : this

Resets the action. This method can be chained.

This method sets paused to false, enabled to true, time to 0, eliminating the internal loop count and scheduling for the delayed beginning.

.setDuration ( durationInSeconds : Number ) : this

Sets the duration for a single loop of this action (by adjusting timeScale and stopping any scheduled warping). This method can be chained.

.setEffectiveTimeScale ( timeScale : Number ) : this

Stops any scheduled warping and sets the timeScale. This approach can be used repeatedly.

The effective time scale (an internal property) will be set to this value if paused is false; otherwise, the effective time scale (directly impacting the animation at this time) will be set to 0.

.setEffectiveWeight ( weight : Number ) : this

Stops any scheduled fading and sets the weight. This approach can be used repeatedly.

If enabled is true, the effective weight (an internal property) will be set to this value as well; otherwise, the effective weight (which is now affecting the animation) will be set to 0.

.setLoop ( loopMode : Number, repetitions : Number ) : this

Sets the loop mode and the number of repetitions. This method can be chained.

.startAt ( startTimeInSeconds : Number ) : this

Defines the time for a delayed start (usually passed as AnimationMixer.time + deltaTimeInSeconds). This method can be chained.

.stop () : this

Tells the mixer to deactivate this action. This method can be chained.

The action will be immediately stopped and completely reset.

.stopFading () : this

Stops any scheduled fading which is applied to this action. This method can be chained.

.stopWarping () : this

Stops any scheduled warping which is applied to this action. This method can be chained.

.syncWith ( otherAction : AnimationAction ) : this

This action is synchronized with the passed other action. This approach can be used repeatedly.

Setting the time and timeScale values of this action to the corresponding values of the other action synchronizes them (stopping any scheduled warping).

Future changes to the time and timeScale of the other actions will not be recognized.

.warp ( startTimeScale : Number, endTimeScale : Number, durationInSeconds : Number ) : this

Changes the playback speed, within the passed time interval, by modifying timeScale gradually from startTimeScale to endTimeScale. This method can be chained.

Events

There are two events that indicate when a single loop of the action has completed, as well as when the entire action has been completed. You can respond to them by:

mixer.addEventListener( 'loop', function( e ) { …} ); // properties of e: type, action and loopDelta
mixer.addEventListener( 'finished', function( e ) { …} ); // properties of e: type, action and direction