threejs-impl-animation

Quick Reference

Architecture

AnimationClip        (data: array of KeyframeTrack objects)
  └── AnimationAction  (playback controller: play, pause, fade, crossfade)
        └── AnimationMixer (master scheduler: one per animated root object)
              └── Clock    (provides delta time for mixer.update)

ALWAYS create exactly ONE AnimationMixer per animated root object. ALWAYS call mixer.update(delta) every frame inside the render loop. NEVER instantiate AnimationAction directly -- ALWAYS use mixer.clipAction(clip).

Essential Imports

import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

Minimal Animation Setup

import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const clock = new THREE.Clock();
let mixer;

const loader = new GLTFLoader();
loader.load('character.glb', (gltf) => {
  scene.add(gltf.scene);
  mixer = new THREE.AnimationMixer(gltf.scene);

  // Play all animations from the GLTF file
  gltf.animations.forEach((clip) => {
    mixer.clipAction(clip).play();
  });
});

function animate() {
  const delta = clock.getDelta();
  if (mixer) mixer.update(delta);
  renderer.render(scene, camera);
}
renderer.setAnimationLoop(animate);

Critical Warnings

NEVER forget to call mixer.update(delta) in the render loop -- animations will NOT play without it.

NEVER use new Date() or performance.now() to compute delta manually -- ALWAYS use THREE.Clock or renderer.setAnimationLoop which provides stable frame timing.

NEVER call mixer.clipAction(clip) repeatedly in the render loop -- it caches internally, but the lookup is unnecessary overhead. ALWAYS store the returned action in a variable.

NEVER call .play() every frame -- call it ONCE to start playback. Calling .play() again on an already-playing action has no effect, but it signals misunderstanding.

ALWAYS call .reset() before .play() when restarting a stopped or finished action, or the action may resume from its last position.

ALWAYS set action.clampWhenFinished = true when using LoopOnce -- otherwise the action resets to the first frame when finished.

AnimationMixer

The master scheduler that drives all animation actions for a single object hierarchy.

Constructor

const mixer = new THREE.AnimationMixer(rootObject);

rootObject is the root Object3D of the animated model (typically gltf.scene).

Properties

Methods

Events

Listen via mixer.addEventListener(type, callback):

Event object properties: { action, loopDelta, type }.

Blend Modes

Pass as the third argument to mixer.clipAction(clip, root, blendMode):

AnimationAction

Controls playback of a single animation clip. NEVER instantiate directly.

Properties

Loop Modes

Playback Methods

Fading and Crossfade Methods

Speed and Timing Methods

Query Methods

AnimationClip

A reusable set of keyframe tracks. Typically loaded from GLTF files.

Constructor

const clip = new THREE.AnimationClip(name, duration, tracks, blendMode);

• name -- string identifier (GLTF clips use names from the file)
• duration -- seconds; -1 to auto-calculate from tracks
• tracks -- array of KeyframeTrack objects
• blendMode -- optional blend mode constant

Key Static Methods

KeyframeTrack Types

Interpolation Modes

PropertyBinding Path Format

"meshName.position"                    // animate position
"meshName.material.opacity"            // animate material property
"meshName.morphTargetInfluences[0]"    // animate morph target
"boneName.quaternion"                  // animate bone rotation

Clock

Constructor

const clock = new THREE.Clock(autoStart); // autoStart defaults to true

Methods

Crossfade Pattern (Character State Machine)

const actions = {};
gltf.animations.forEach((clip) => {
  actions[clip.name] = mixer.clipAction(clip);
});

let currentAction = actions['Idle'];
currentAction.play();

function switchAction(toName, duration = 0.5) {
  const toAction = actions[toName];
  toAction.reset();
  toAction.setEffectiveTimeScale(1);
  toAction.setEffectiveWeight(1);
  toAction.crossFadeFrom(currentAction, duration, true);
  toAction.play();
  currentAction = toAction;
}

ALWAYS call .reset() on the incoming action before crossfading. ALWAYS store the current action reference for the next transition.

Additive Animation Blending

const baseAction = mixer.clipAction(baseClip);
const additiveAction = mixer.clipAction(
  additiveClip, undefined, THREE.AdditiveAnimationBlendMode
);

baseAction.play();
additiveAction.play();
additiveAction.setEffectiveWeight(0.5);

Use additive blending for layered effects: breathing, damage reactions, aim offsets.

Morph Target Animation

// Manual control
mesh.morphTargetInfluences[0] = Math.sin(elapsed) * 0.5 + 0.5;

// Via GLTF animation clip (preferred)
const morphAction = mixer.clipAction(morphClip);
morphAction.play();

Reference Links

• references/methods.md -- Full API signatures
• references/examples.md -- Working code examples
• references/anti-patterns.md -- What NOT to do

Official Sources

• https://threejs.org/docs/#api/en/animation/AnimationMixer
• https://threejs.org/docs/#api/en/animation/AnimationAction
• https://threejs.org/docs/#api/en/animation/AnimationClip
• https://threejs.org/docs/#api/en/animation/KeyframeTrack
• https://threejs.org/docs/#api/en/core/Clock
• https://threejs.org/examples/#webgl_animation_skinning_blending