threejs-impl-animation
Référence rapide
Architecture
AnimationClip (données : tableau d'objets KeyframeTrack)
└── AnimationAction (contrôleur de lecture : play, pause, fade, crossfade)
└── AnimationMixer (planificateur maître : un par objet racine animé)
└── Clock (fournit le temps delta pour mixer.update)
Créez TOUJOURS exactement UN AnimationMixer par objet racine animé.
Appelez TOUJOURS mixer.update(delta) à chaque frame dans la boucle de rendu.
N'instanciez JAMAIS AnimationAction directement — utilisez TOUJOURS mixer.clipAction(clip).
Imports essentiels
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
Configuration minimale d'animation
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);
// Jouer toutes les animations du fichier GLTF
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);
Avertissements critiques
NE JAMAIS oublier d'appeler mixer.update(delta) dans la boucle de rendu — les animations ne seront PAS lues sans cela.
NE JAMAIS utiliser new Date() ou performance.now() pour calculer delta manuellement — utilisez TOUJOURS THREE.Clock ou renderer.setAnimationLoop qui fournit un timing d'image stable.
NE JAMAIS appeler mixer.clipAction(clip) de manière répétée dans la boucle de rendu — il met en cache en interne, mais la recherche est une surcharge inutile. Stockez TOUJOURS l'action retournée dans une variable.
NE JAMAIS appeler .play() à chaque frame — appelez-le UNE FOIS pour démarrer la lecture. Appeler .play() à nouveau sur une action déjà en cours n'a aucun effet, mais indique une méprise.
Appelez TOUJOURS .reset() avant .play() lors du redémarrage d'une action arrêtée ou terminée, sinon l'action peut reprendre depuis sa dernière position.
Définissez TOUJOURS action.clampWhenFinished = true avec LoopOnce — sinon l'action revient à la première image une fois terminée.
AnimationMixer
Le planificateur maître qui gère toutes les actions d'animation pour une hiérarchie d'objets unique.
Constructeur
const mixer = new THREE.AnimationMixer(rootObject);
rootObject est l'Object3D racine du modèle animé (généralement gltf.scene).
Propriétés
| Propriété | Type | Défaut | Description |
|---|---|---|---|
.time | number | 0 | Temps global du mixer en secondes |
.timeScale | number | 1 | Multiplicateur de vitesse global ; 0 met PAUSE toutes les actions |
Méthodes
| Méthode | Retourne | Description |
|---|---|---|
.clipAction(clip, root?, blendMode?) | AnimationAction | Retourne ou crée une action pour le clip |
.existingAction(clip, root?) | AnimationAction | null | Retourne l'action précédemment créée ou null |
.update(delta) | this | Avance le mixer du delta en secondes — DOIT être appelée à chaque frame |
.setTime(seconds) | this | Définit le temps global, met à jour toutes les actions |
.stopAllAction() | this | Désactive toutes les actions planifiées |
.getRoot() | Object3D | Retourne l'objet racine du mixer |
.uncacheAction(clip, root?) | void | Désalloue l'action mise en cache |
.uncacheClip(clip) | void | Désalloue les données du clip |
.uncacheRoot(root) | void | Désalloue les données de l'objet racine |
Événements
Écoutez via mixer.addEventListener(type, callback) :
| Événement | Déclenché quand |
|---|---|
'finished' | L'action se termine (UNIQUEMENT avec LoopOnce + clampWhenFinished = true) |
'loop' | L'action termine une itération de boucle |
Propriétés de l'objet événement : { action, loopDelta, type }.
Modes de mélange
Passez comme troisième argument à mixer.clipAction(clip, root, blendMode) :
| Constante | Comportement |
|---|---|
THREE.NormalAnimationBlendMode | Mélange standard (par défaut) |
THREE.AdditiveAnimationBlendMode | Superposé à l'animation de base |
AnimationAction
Contrôle la lecture d'un seul clip d'animation. Ne jamais instancier directement.
Propriétés
| Propriété | Type | Défaut | Description |
|---|---|---|---|
.blendMode | number | NormalAnimationBlendMode | Stratégie de mélange |
.clampWhenFinished | boolean | false | Pause sur la dernière image une fois terminée |
.enabled | boolean | true | Désactiver sans réinitialiser |
.loop | number | LoopRepeat | Mode de boucle |
.paused | boolean | false | Geler la lecture |
.repetitions | number | Infinity | Nombre de répétitions |
.time | number | 0 | Temps local en secondes |
.timeScale | number | 1 | Vitesse : 0 met en pause, négatif inverse |
.weight | number | 1 | Influence du mélange [0, 1] |
.zeroSlopeAtEnd | boolean | true | Interpolation lisse à la fin de la boucle |
.zeroSlopeAtStart | boolean | true | Interpolation lisse au début de la boucle |
Modes de boucle
| Constante | Comportement |
|---|---|
THREE.LoopOnce | Joue une fois, s'arrête |
THREE.LoopRepeat | Redémarre depuis le début à chaque boucle |
THREE.LoopPingPong | Alterne avant/arrière |
Méthodes de lecture
| Méthode | Description |
|---|---|
.play() | Démarrer la lecture |
.stop() | Arrêter et réinitialiser au début |
.reset() | Réinitialiser le temps, le poids, la vitesse à l'état initial |
.startAt(mixerTime) | Retarder le démarrage jusqu'au temps spécifié du mixer |
Méthodes de fondu et de fondu enchaîné
| Méthode | Description |
|---|---|
.fadeIn(duration) | Fondre le poids de 0 à 1 |
.fadeOut(duration) | Fondre le poids de 1 à 0 |
.crossFadeFrom(fadeOutAction, duration, warp) | Fondu enchaîné depuis une autre action vers celle-ci |
.crossFadeTo(fadeInAction, duration, warp) | Fondu enchaîné de cette action vers une autre |
.stopFading() | Annuler tout fondu actif |
Méthodes de vitesse et de timing
| Méthode | Description |
|---|---|
.halt(duration) | Décélérer timeScale jusqu'à 0 sur la durée |
.warp(startScale, endScale, duration) | Transiter en douceur la vitesse de lecture |
.stopWarping() | Annuler toute transition de vitesse active |
.setDuration(seconds) | Ajuster timeScale pour qu'une boucle prenne exactement seconds |
.setEffectiveTimeScale(scale) | Définir l'échelle de temps effective |
.setEffectiveWeight(weight) | Définir le poids effectif |
.setLoop(mode, repetitions) | Définir le mode de boucle et le nombre de répétitions |
.syncWith(otherAction) | Synchroniser le temps avec une autre action |
Méthodes de requête
| Méthode | Retourne | Description |
|---|---|---|
.isRunning() | boolean | true uniquement si en lecture active |
.isScheduled() | boolean | true si .play() a été appelé |
.getClip() | AnimationClip | Le clip associé |
.getMixer() | AnimationMixer | Le mixer propriétaire |
.getRoot() | Object3D | L'objet racine |
.getEffectiveTimeScale() | number | Échelle de temps calculée |
.getEffectiveWeight() | number | Poids calculé |
AnimationClip
Un ensemble réutilisable de pistes d'images clés. Généralement chargé depuis des fichiers GLTF.
Constructeur
const clip = new THREE.AnimationClip(name, duration, tracks, blendMode);
name-- identifiant chaîne (les clips GLTF utilisent les noms du fichier)duration-- secondes ;-1pour calcul automatique à partir des pistestracks-- tableau d'objetsKeyframeTrackblendMode-- constante de mode de mélange optionnelle
Méthodes statiques clés
| Méthode | Description |
|---|---|
AnimationClip.findByName(arrayOrObject, name) | Rechercher un clip par nom |
AnimationClip.CreateFromMorphTargetSequence(name, targets, fps, noLoop) | Créer un clip à partir de cibles de morphing |
AnimationClip.parse(json) | Désérialiser depuis JSON |
Types de KeyframeTrack
| Type de piste | Type de valeur | Cas d'usage |
|---|---|---|
VectorKeyframeTrack | Vector3 | Position, échelle |
QuaternionKeyframeTrack | Quaternion | Rotation (utilise slerp) |
NumberKeyframeTrack | number | Opacité, intensité |
BooleanKeyframeTrack | boolean | Commutateurs de visibilité |
ColorKeyframeTrack | Color | Animation de couleur |
StringKeyframeTrack | string | Valeurs discrètes de chaîne |
Modes d'interpolation
| Constante | Comportement |
|---|---|
THREE.InterpolateDiscrete | Fonction échelon, pas de lissage |
THREE.InterpolateLinear | Interpolation linéaire (par défaut) |
THREE.InterpolateSmooth | Interpolation par spline cubique |
Format du chemin PropertyBinding
"meshName.position" // animer la position
"meshName.material.opacity" // animer une propriété de matériau
"meshName.morphTargetInfluences[0]" // animer une cible de morphing
"boneName.quaternion" // animer la rotation d'un os
Clock
Constructeur
const clock = new THREE.Clock(autoStart); // autoStart vaut true par défaut
Méthodes
| Méthode | Retourne | Description |
|---|---|---|
.getDelta() | number | Secondes depuis le dernier appel à getDelta() |
.getElapsedTime() | number | Temps total écoulé en secondes |
.start() | void | Démarrer le chronomètre |
.stop() | void | Arrêter sans réinitialiser |
Modèle de fondu enchaîné (machine à états de personnage)
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;
}
Appelez TOUJOURS .reset() sur l'action entrante avant le fondu enchaîné.
Stockez TOUJOURS la référence de l'action courante pour la prochaine transition.
Mélange d'animations additif
const baseAction = mixer.clipAction(baseClip);
const additiveAction = mixer.clipAction(
additiveClip, undefined, THREE.AdditiveAnimationBlendMode
);
baseAction.play();
additiveAction.play();
additiveAction.setEffectiveWeight(0.5);
Utilisez le mélange additif pour des effets superposés : respiration, réactions aux dégâts, décalages de visée.
Animation de morph targets
// Contrôle manuel
mesh.morphTargetInfluences[0] = Math.sin(elapsed) * 0.5 + 0.5;
// Via un clip d'animation GLTF (recommandé)
const morphAction = mixer.clipAction(morphClip);
morphAction.play();
Liens de référence
- references/methods.md -- Signatures d'API complètes
- references/examples.md -- Exemples de code fonctionnel
- references/anti-patterns.md -- Ce qu'il NE FAUT PAS faire
Sources officielles
- 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