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
.claude/rules/animation-system.mdWhat 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
walkclip withAnimationMixerand 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.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/animation-system.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/animation-system.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/animation-system.mdManually: put the files in place
.clinerules/animation-system.mdStep 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