zebbern/claude-code-guide / skills/three-best-practices
three-best-practices
VerifiedThree.js performance optimization and best practices guidelines. Use when writing, reviewing, or optimizing Three.js code. Triggers on tasks involving 3D scenes, WebGL/WebGPU rendering, geometries, materials, textures, lighting, shaders, or TSL.
rules/animation-system.md
View on GitHub# 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)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |