GltfAnimation

@RequiresApi(value = 26)
class GltfAnimation

GltfAnimation represents an animation in a GltfModelEntity.

Multiple animations can play simultaneously. If multiple animations affect the same node, the animation processed last takes precedence. Specifically, only the state of the last processed animation is reflected in the scene for a given frame. Updates from other animations (such as node transforms) for the same target will be overwritten.

A GltfAnimation cannot be used once its associated GltfModelEntity has been destroyed.

Summary

Nested types

Specifies the current animation state of this GltfAnimation.

Public functions
Unit

Registers a listener to be invoked on the main thread when the animation state of the GltfAnimation changes.
Unit

Registers a listener to be invoked when the animation state of this GltfAnimation changes.
Unit

Pauses this animation.
Unit

Unregisters a previously registered animation state update listener.
Unit

Resumes this animation.
Unit

Seeks the animation to a specific time position.
Unit

Sets the playback speed for this animation.
Unit

Starts playing this animation.
Unit

Stops this animation.

Public properties
GltfAnimation.AnimationState

The current state of this animation.
Duration

The duration of this animation.
Int

The index of this animation in the source glTF model.
String?

The name of this animation, or null if the animation is unnamed.

Public functions

addAnimationStateListener

Added in 1.0.0-alpha13
fun addAnimationStateListener(
    listener: Consumer<GltfAnimation.AnimationState>
): Unit

Registers a listener to be invoked on the main thread when the animation state of the GltfAnimation changes.

Parameters
listener: Consumer<GltfAnimation.AnimationState>

The listener to invoke when the state changes. It receives the new AnimationState.

addAnimationStateListener

Added in 1.0.0-alpha13
fun addAnimationStateListener(
    executor: Executor,
    listener: Consumer<GltfAnimation.AnimationState>
): Unit

Registers a listener to be invoked when the animation state of this GltfAnimation changes.

Parameters
executor: Executor

The executor on which the listener will be invoked.
listener: Consumer<GltfAnimation.AnimationState>

The listener to invoke when the state changes. It receives the new AnimationState.

pause

Added in 1.0.0-alpha13
@MainThread
fun pause(): Unit

Pauses this animation.

This freezes the animation at the current frame and transitions the animation state to AnimationState.PAUSED. Use resume to continue playback.

Note: Calling start while in the AnimationState.PAUSED state will reset the playback time to animationOptions.seekStartTime and transition the state to AnimationState.PLAYING.

removeAnimationStateListener

Added in 1.0.0-alpha13
fun removeAnimationStateListener(
    listener: Consumer<GltfAnimation.AnimationState>
): Unit

Unregisters a previously registered animation state update listener.

Parameters
listener: Consumer<GltfAnimation.AnimationState>

The listener to remove.

resume

Added in 1.0.0-alpha13
@MainThread
fun resume(): Unit

Resumes this animation.

This continues the animation from the point where it was paused and transitions the animation state to AnimationState.PLAYING.

Note: Calling resume while in the AnimationState.PLAYING and AnimationState.STOPPED state will have no effect.

seekTo

Added in 1.0.0-alpha13
@MainThread
fun seekTo(time: Duration): Unit

Seeks the animation to a specific time position.

Note: This call is only valid during the AnimationState.PLAYING and AnimationState.PAUSED states. Calling this method while in the AnimationState.STOPPED state has no effect.

The behavior depends on whether the animation is looping:

  • Looping Enabled: The time is treated as cyclical. Values exceeding the duration will wrap around (modulo arithmetic).

  • Looping Disabled: The time is clamped to the valid playback range. Values less than GltfAnimationStartOptions.seekStartTime clamp to the start. Values exceeding the duration (or end time) clamp to the end.

Interaction with GltfAnimationStartOptions.seekStartTime:

Parameters
time: Duration

The offset from the beginning of the animation.
Throws
IllegalArgumentException

if time is negative.

setSpeed

Added in 1.0.0-alpha13
@MainThread
fun setSpeed(speed: Float): Unit

Sets the playback speed for this animation.

The speed multiplier determines the playback rate:

  • 1.0: Normal speed.

  • > 1.0: Faster playback.

  • > 0.0 and < 1.0: Slower playback (e.g., 0.5 is half speed).

  • 0.0: Freezes the animation at the current frame while keeping it active (unlike pausing).

  • < 0.0: Plays the animation in reverse.

Note: This call is only valid during the AnimationState.PLAYING and AnimationState.PAUSED states. Calling this method while in the AnimationState.STOPPED state will have no effect.

Parameters
speed: Float

The playback rate multiplier.

start

Added in 1.0.0-alpha13
@MainThread
fun start(options: GltfAnimationStartOptions = GltfAnimationStartOptions()): Unit

Starts playing this animation.

This transitions the animation state to AnimationState.PLAYING.

Parameters
options: GltfAnimationStartOptions = GltfAnimationStartOptions()

The options that describe how the glTF model will be animated. Using default values if not specified.

stop

Added in 1.0.0-alpha13
@MainThread
fun stop(): Unit

Stops this animation.

This resets the playback time to 0 and transitions the animation state to AnimationState.STOPPED. If this animation is not currently playing or pausing, this method has no effect.

Public properties

animationState

Added in 1.0.0-alpha13
val animationState: GltfAnimation.AnimationState

The current state of this animation.

See also
GltfAnimation.AnimationState

duration

Added in 1.0.0-alpha13
val duration: Duration

The duration of this animation.

index

Added in 1.0.0-alpha13
val index: Int

The index of this animation in the source glTF model.

name

Added in 1.0.0-alpha13
val name: String?

The name of this animation, or null if the animation is unnamed.