AnimationState

Hoisted, observable playback state for a single glTF Animator, created with rememberAnimationState and passed to GltfInstance. It auto-advances on every frame and drives the animator each frame in one of two modes:

Single-track (the convenience path). Set animationIndex and the active clip plays, looping at its length; assigning a new index cross-fades from the outgoing clip over crossFadeDuration. This covers the common "play idle, blend into walk" case without touching the mixer.

Multi-track mixer. Add tracks with rememberAnimationTrack and the state blends them by AnimationTrack.weight every frame — a blend tree (e.g. idle↔walk↔run driven by a speed parameter). While the mixer has tracks it takes precedence and animationIndex is ignored. Filament blends two clips per call, but weighted cross-fades chain, so an arbitrary number of weighted clips compose into one pose.

For an imperative game loop (an animation state machine outside composition), use AnimationMixer directly instead of this hoisted state — see rememberAnimationMixer.

Per-bone masks and additive layers are not expressible — the native animator blends the whole skeleton. For that, or any fully manual control, use GltfInstance's onUpdate and call the Animator directly.

// Single-track with auto cross-fade:
val anim = rememberAnimationState(initialAnimationIndex = idle, initialCrossFadeDuration = 0.25f)
GltfInstance(asset = character, animationState = anim)
anim.animationIndex = walk   // cross-fades

// Blend tree — hold both clips and drive the weight from a parameter:
val anim = rememberAnimationState(initialAnimationIndex = null)
rememberAnimationTrack(anim, walkIndex, weight = 1f - speed)
rememberAnimationTrack(anim, runIndex,  weight = speed)