Skip to main content
rule CX Codex

animation-system — Claude Code rule for Three.js animation

animation-system — a practical guide to Three.js animation, from playing and blending clips to morph targets and bones. Useful when building scenes with animated models.

MIT ★ 4,719 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/animation-system.md
Open on GitHub

What animation-system does

The rule walks through AnimationMixer, AnimationClip, KeyframeTrack, and AnimationAction. It covers starting a clip, updating the mixer with frame delta, and transitioning between actions. Loop behavior, playback speed, and finished or loop events are included too.

Examples cover direct morph-target control, keyframed animation, and editing bones on a SkinnedMesh. You can also build clips for position, rotation, or material color. The render loop must pass delta time to the mixer; when disposing of a model, stop its actions and clear the mixer's references.

What it helps with

  • play an animation clip on a model
  • blend walking into running
  • animate a facial expression with morph targets
  • change a bone's rotation
  • build a position, rotation, or color clip

Example prompts for the agent

  • Show me how to play the walk clip with AnimationMixer and update it in the render loop.
  • Write an example that crossfades from walking to running.
  • Animate a smile using morphTargetInfluences.

How to install animation-system

Manually: put the files in place

.claude/rules/animation-system.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about animation-system

How do I install animation-system in Claude Code?

Use the path .claude/rules/animation-system.md.

What does the animation-system rule do?

It explains Three.js animation playback and blending, along with morph targets, skeletal animation, and custom keyframe tracks.

How should I update AnimationMixer?

Pass frame delta to mixer.update() from the render loop. The guide recommends one mixer for each animated object hierarchy.

Source text

animation-system.md · MIT
# Animation System

Complete guide to Three.js animation system including AnimationMixer, blending, morph targets, and skeletal animation.

## System Components

```
AnimationClip          --- Contains KeyframeTracks
    |
    +-- KeyframeTrack  --- Data for one animated property
    |   +-- times[]    --- Keyframe times
    |   +-- values[]   --- Values at each keyframe
    |
AnimationMixer         --- Connects clips with objects
    |
    +-- AnimationAction --- Controls playback
        +-- play()
        +-- pause()
        +-- stop()
        +-- reset()
        +-- setLoop()
        +-- setEffectiveWeight()
        +-- crossFadeTo()
```

## Basic Usage

```javascript
const mixer = new THREE.AnimationMixer(model);

// Play animation
const clip = THREE.AnimationClip.findByName(model.animations, 'walk');
const action = mixer.clipAction(clip);
action.play();

// In render loop
function animate() {
  const delta = clock.getDelta();
  mixer.update(delta);
}
```

## Animation Blending

```javascript
const walkAction = mixer.clipAction(walkClip);
const runAction = mixer.clipAction(runClip);

// Start both
walkAction.play();
runAction.play();

// Crossfade from walk to run
walkAction.crossFadeTo(runAction, 0.5, true);

// Or manual weight control
walkAction.setEffectiveWeight(0.7);
runAction.setEffectiveWeight(0.3);
```

## Morph Targets

```javascript
// Access morph targets
const mesh = model.getObjectByName('Face');
const morphTargetDictionary = mesh.morphTargetDictionary;
const morphTargetInfluences = mesh.morphTargetInfluences;

// Animate manually
morphTargetInfluences[morphTargetDictionary['smile']] = 0.5;

// Or use AnimationClip
const smileTrack = new THREE.NumberKeyframeTrack(
  'Face.morphTargetInfluences[smile]',
  [0, 1, 2],     // times
  [0, 1, 0]      // values
);
const clip = new THREE.AnimationClip('SmileAnim', 2, [smileTrack]);
```

## Skeletal Animation

```javascript
gltfLoader.load('character.glb', (gltf) => {
  const model = gltf.scene;

  // Find SkinnedMesh
  model.traverse((child) => {
    if (child.isSkinnedMesh) {
      // Access bones
      const skeleton = child.skeleton;
      const bones = skeleton.bones;

      // Manipulate bone directly
      const head = bones.find(b => b.name === 'Head');
      head.rotation.y = Math.PI / 4;
    }
  });
});
```

## Loop Modes

```javascript
action.setLoop(THREE.LoopOnce);       // Play once
action.setLoop(THREE.LoopRepeat);     // Repeat forever (default)
action.setLoop(THREE.LoopPingPong);   // Alternate direction
action.setLoop(THREE.LoopRepeat, 3);  // Repeat 3 times

// Clamp at end
action.clampWhenFinished = true;
```

## Events

```javascript
mixer.addEventListener('finished', (e) => {
  console.log('Animation finished:', e.action.getClip().name);
});

mixer.addEventListener('loop', (e) => {
  console.log('Loop:', e.action.getClip().name);
});
```

## Time Scale & Duration

```javascript
// Speed control
action.setEffectiveTimeScale(2);  // Double speed
action.setEffectiveTimeScale(0.5); // Half speed
action.setEffectiveTimeScale(-1); // Reverse

// Duration
const duration = clip.duration;

// Set to specific time
action.time = 1.5;

// Set to percentage
action.time = duration * 0.5; // 50%
```

## Creating Custom Animations

```javascript
// Position animation
const positionTrack = new THREE.VectorKeyframeTrack(
  '.position',
  [0, 1, 2],                           // times
  [0, 0, 0, 0, 5, 0, 0, 0, 0]         // positions (x,y,z for each keyframe)
);

// Rotation animation (quaternion)
const rotationTrack = new THREE.QuaternionKeyframeTrack(
  '.quaternion',
  [0, 1],
  [0, 0, 0, 1, 0, 0.707, 0, 0.707]   // quaternions
);

// Color animation
const colorTrack = new THREE.ColorKeyframeTrack(
  '.material.color',
  [0, 1],
  [1, 0, 0, 0, 0, 1]                  // red to blue
);

const clip = new THREE.AnimationClip('custom', 2, [
  positionTrack,
  rotationTrack,
  colorTrack
]);
```

## Best Practices

1. **Single Mixer**: Use one AnimationMixer per animated object hierarchy

2. **Delta Time**: Always pass delta time to mixer.update()

3. **Weight Management**: Reset weights when switching animations

4. **Cleanup**: Stop actions and remove mixers when disposing objects

5. **Preload**: Create all AnimationActions on init, not during runtime

6. **Performance**: Use animation.optimize() for production

```javascript
// Optimize animation data
clip.optimize();

// Cleanup
action.stop();
mixer.stopAllAction();
mixer.uncacheRoot(model);
```

## References

- [Three.js Animation System](https://threejs.org/docs/#manual/en/introduction/Animation-system)
- [Three.js AnimationMixer](https://threejs.org/docs/#api/en/animation/AnimationMixer)

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set86

The whole set →
audio-spatial The audio-spatial rule for Claude Code provides Three.js 3D audio patterns for source positioning, distance falloff, and response to user interaction. CX Codex +1 ★ 4,719repo stars debug-devtools The debug-devtools rule guides an agent through adding diagnostics for Three.js performance, scene parameters, and WebGL context loss. Use it when tracking down a rendering bottleneck or inspecting a scene. CX Codex +1 ★ 4,719repo stars tsl-post-processing A reference rule for TSL post-processing in Three.js: chain effects onto postProcessing.outputNode instead of stacking EffectComposer passes. CX Codex +1 ★ 4,719repo stars tsl-compute-shaders tsl-compute-shaders guides the agent in writing WebGPU compute shaders with Three.js TSL for GPGPU tasks like particle systems and physics. CX Codex +1 ★ 4,719repo stars gltf-loading-optimization gltf-loading-optimization is a Claude Code rule with Three.js snippets and commands for glTF loading, decoder setup, progress reporting, lazy loading and model compression. CX Codex +1 ★ 4,719repo stars physics-integration physics-integration guides Three.js integration with Rapier and Cannon-es: Vite setup, collider primitives, and mesh synchronization patterns. CX Codex +1 ★ 4,719repo stars raycasting-optimization The raycasting-optimization rule covers ways to reduce Three.js raycasting work, from filtering objects by layer to using BVH or GPU picking. Useful when a scene has complex meshes or frequent pointer checks. CX Codex +1 ★ 4,719repo stars mobile-optimization mobile-optimization is a rule for accelerating Three.js scenes on smartphones and tablets. It reduces GPU load and memory use, helping maintain a stable frame rate. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open