Animation¶

Overview¶

An easing-based controllable animation.

We use some terminology to describe points and regions in time for an animation:

        starts                            begins                                finishes
          |             delay               |             animation                |

time--> | (waiting) | (animated values changing) |¶

          |------------------------------running-----------------------------------|
                                            |-------------animating----------------|

TODO #3: pause/cancel (and stop->cancel renaming) TODO #3: function for blending with angular/rotational values TODO #3: consider keyframed animation helper? TODO #3: Hooks for attaching/detaching stepping via screens/nodes TODO #3: Add documentation examples (contingent on how screen/node hooks work)

@author Jonathan Olson <jonathan.olson@colorado.edu>

Class Animation¶

import { Animation } from 'scenerystack/twixt';

Constructor¶

new Animation( providedConfig : AnimationOptions<SelfType, SelfObjectType, TargetTypes, TargetObjectTypes> )¶

Instance Methods¶

start( dt? : number ) : this¶

Starts the animation (or if it has a delay, sets the animation to start after that delay).

@param [dt] - If provided, step this far into the animation initially. Used for chaining animations.

stop() : this¶

Stops the animation (or if waiting for the delay, will not "start" the animation).

step( dt : number ) : this¶

Steps the animation forward by a certain amount of time.

@param dt - In seconds

then( animation : Animation ) : Animation¶

After this animation is complete, the given animation will be started.

@returns - Returns the passed-in animation so things can be chained nicely.

dispose()¶

Instance Properties¶

runningProperty : BooleanProperty¶

(readonly)

True while the animation is being stepped through (both the delay portion AND the actual animation portion).

animatingProperty : BooleanProperty¶

(readonly)

True while the animation is actually changing the value (false while waiting for the delay, or while the animation is not running at all).

startEmitter : Emitter¶

(readonly)

Fired when the animation is "started" (i.e. when start() is called and the delay, if one is there, starts).

beginEmitter : Emitter¶

(readonly)

Fired when the actual animation of the value begins (i.e. when the delay finishes and the actual animation begins).

finishEmitter : Emitter¶

(readonly)

Fired when the animation finishes naturally (was not abnormally stopped). A {number} is provided as a single argument to the emit callback, and represents how much "extra" time occurred after the end of the animation. For example, if you have a 1-second animation and stepped it by 3 seconds, this finished emitter would be called with 2 seconds.

stopEmitter : Emitter¶

(readonly)

Fired when the animation is manually stopped (with stop()). Does NOT fire when it finishes normally.

endedEmitter : Emitter¶

(readonly)

Fired when the animation ends, regardless of whether it fully finished, or was stopped prematurely.

updateEmitter : Emitter¶

(readonly)

Fired when (just after) the animation has changed animated values/targets.

Type AnimationOptions¶

IMPORTANT: See AnimationTarget's config documentation, as those config can be passed in either here, or in the targets array.

import type { AnimationOptions } from 'scenerystack/twixt';

• targets?: { [K in keyof TargetTypes]: AnimationTargetOptions<TargetTypes[K], TargetObjectTypes[K]> } | null
  Can be provided instead of setValue/property/object, and it contains an array of config-style objects that allows animating multiple different things at the same time. See AnimationTarget for details about all of the supported config. NOTE: speed, if provided, should be only specified on exactly one of the targets' config if multiple targets are specified.
• duration?: number | null
  If provided, the animation's length will be this value (in seconds). If omitted, one of the targets' speed option should be set (the length of the animation will be based on that).
• delay?: number
  The amount of time (in seconds) between when the animation is "started" and when the actual animation of the value begins. Negative delays are not supported.
• stepEmitter?: TReadOnlyEmitter<[ number ]> | null
  One of the following config: The Emitter (which provides a dt {number} value on emit) which drives the animation, or null if the client will drive the animation by calling step(dt) manually. Defaults to the joist Timer which runs automatically as part of the Sim time step. TODO #3: {ScreenView} - animates only when the ScreenView is the active one. TODO #3: {Node} - animates only when the node's trail is visible on a Display
• & AnimationTargetOptions<SelfType, SelfObjectType> & DisposableOptions

Source Code¶

See the source for Animation.ts in the twixt repository.