threejs-impl-animation
Referencia Rápida
Arquitectura
AnimationClip (datos: array de objetos KeyframeTrack)
└── AnimationAction (controlador de reproducción: play, pause, fade, crossfade)
└── AnimationMixer (programador maestro: uno por objeto raíz animado)
└── Clock (proporciona el delta de tiempo para mixer.update)
SIEMPRE crea EXACTAMENTE UN AnimationMixer por objeto raíz animado.
SIEMPRE llama a mixer.update(delta) cada frame dentro del bucle de renderizado.
NUNCA instancies AnimationAction directamente — SIEMPRE usa mixer.clipAction(clip).
Importaciones Esenciales
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
Configuración Mínima de Animación
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);
// Reproducir todas las animaciones del archivo 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);
Advertencias Críticas
NUNCA olvides llamar a mixer.update(delta) en el bucle de renderizado — las animaciones NO se reproducirán sin ello.
NUNCA uses new Date() o performance.now() para calcular el delta manualmente — SIEMPRE usa THREE.Clock o renderer.setAnimationLoop, que proporcionan un tiempo de cuadro estable.
NUNCA llames a mixer.clipAction(clip) repetidamente en el bucle de renderizado — aunque hace caché internamente, la búsqueda es una sobrecarga innecesaria. SIEMPRE almacena la acción devuelta en una variable.
NUNCA llames a .play() cada frame — llámalo UNA VEZ para iniciar la reproducción. Llamar a .play() de nuevo sobre una acción que ya se está reproduciendo no tiene efecto, pero indica una mala comprensión.
SIEMPRE llama a .reset() antes de .play() al reiniciar una acción detenida o finalizada, de lo contrario la acción podría reanudarse desde su última posición.
SIEMPRE establece action.clampWhenFinished = true al usar LoopOnce — de lo contrario, la acción se reinicia al primer fotograma al terminar.
AnimationMixer
El programador maestro que gestiona todas las acciones de animación para una jerarquía de objetos.
Constructor
const mixer = new THREE.AnimationMixer(rootObject);
rootObject es el Object3D raíz del modelo animado (generalmente gltf.scene).
Propiedades
| Propiedad | Tipo | Por defecto | Descripción |
|---|---|---|---|
.time | number | 0 | Tiempo global del mixer en segundos |
.timeScale | number | 1 | Multiplicador de velocidad global; 0 pausa TODAS las acciones |
Métodos
| Método | Retorna | Descripción |
|---|---|---|
.clipAction(clip, root?, blendMode?) | AnimationAction | Retorna o crea una acción para el clip |
.existingAction(clip, root?) | AnimationAction | null | Retorna una acción creada previamente o null |
.update(delta) | this | Avanza el mixer en delta segundos — DEBE llamarse cada frame |
.setTime(seconds) | this | Establece el tiempo global, actualiza todas las acciones |
.stopAllAction() | this | Desactiva todas las acciones programadas |
.getRoot() | Object3D | Retorna el objeto raíz del mixer |
.uncacheAction(clip, root?) | void | Libera la acción almacenada en caché |
.uncacheClip(clip) | void | Libera los datos del clip |
.uncacheRoot(root) | void | Libera los datos del objeto raíz |
Eventos
Escucha a través de mixer.addEventListener(type, callback):
| Evento | Se Dispara Cuando |
|---|---|
'finished' | La acción se completa (SOLO con LoopOnce + clampWhenFinished = true) |
'loop' | La acción completa una iteración del bucle |
Propiedades del objeto de evento: { action, loopDelta, type }.
Modos de Mezcla
Pasa como tercer argumento a mixer.clipAction(clip, root, blendMode):
| Constante | Comportamiento |
|---|---|
THREE.NormalAnimationBlendMode | Mezcla estándar (por defecto) |
THREE.AdditiveAnimationBlendMode | Superpuesta sobre la animación base |
AnimationAction
Controla la reproducción de un clip de animación individual. NUNCA instanciar directamente.
Propiedades
| Propiedad | Tipo | Por defecto | Descripción |
|---|---|---|---|
.blendMode | number | NormalAnimationBlendMode | Estrategia de mezcla |
.clampWhenFinished | boolean | false | Pausa en el último fotograma al terminar |
.enabled | boolean | true | Deshabilitar sin reiniciar |
.loop | number | LoopRepeat | Modo de bucle |
.paused | boolean | false | Congela la reproducción |
.repetitions | number | Infinity | Número de repeticiones |
.time | number | 0 | Tiempo local en segundos |
.timeScale | number | 1 | Velocidad: 0 pausa, negativo invierte |
.weight | number | 1 | Influencia de mezcla [0, 1] |
.zeroSlopeAtEnd | boolean | true | Interpolación suave al final del bucle |
.zeroSlopeAtStart | boolean | true | Interpolación suave al inicio del bucle |
Modos de Bucle
| Constante | Comportamiento |
|---|---|
THREE.LoopOnce | Se reproduce una vez, se detiene |
THREE.LoopRepeat | Se reinicia desde el principio cada bucle |
THREE.LoopPingPong | Alterna hacia adelante/atrás |
Métodos de Reproducción
| Método | Descripción |
|---|---|
.play() | Iniciar reproducción |
.stop() | Detener y reiniciar al inicio |
.reset() | Reiniciar tiempo, peso, velocidad al estado inicial |
.startAt(mixerTime) | Retrasar el inicio hasta el tiempo especificado del mixer |
Métodos de Desvanecimiento y Transición (Crossfade)
| Método | Descripción |
|---|---|
.fadeIn(duration) | Desvanecer el peso de 0 a 1 |
.fadeOut(duration) | Desvanecer el peso de 1 a 0 |
.crossFadeFrom(fadeOutAction, duration, warp) | Transición desde otra acción hacia esta |
.crossFadeTo(fadeInAction, duration, warp) | Transición desde esta acción hacia otra |
.stopFading() | Cancelar cualquier desvanecimiento activo |
Métodos de Velocidad y Tiempo
| Método | Descripción |
|---|---|
.halt(duration) | Desacelerar timeScale a 0 durante una duración |
.warp(startScale, endScale, duration) | Transicionar suavemente la velocidad de reproducción |
.stopWarping() | Cancelar cualquier warp activo |
.setDuration(seconds) | Ajustar timeScale para que un bucle dure exactamente seconds |
.setEffectiveTimeScale(scale) | Establecer la escala de tiempo efectiva |
.setEffectiveWeight(weight) | Establecer el peso efectivo |
.setLoop(mode, repetitions) | Establecer modo de bucle y número de repeticiones |
.syncWith(otherAction) | Sincronizar tiempo con otra acción |
Métodos de Consulta
| Método | Retorna | Descripción |
|---|---|---|
.isRunning() | boolean | true solo si está reproduciéndose activamente |
.isScheduled() | boolean | true si se llamó a .play() |
.getClip() | AnimationClip | El clip asociado |
.getMixer() | AnimationMixer | El mixer propietario |
.getRoot() | Object3D | El objeto raíz |
.getEffectiveTimeScale() | number | Escala de tiempo calculada |
.getEffectiveWeight() | number | Peso calculado |
AnimationClip
Un conjunto reutilizable de pistas de fotogramas clave. Normalmente se carga desde archivos GLTF.
Constructor
const clip = new THREE.AnimationClip(name, duration, tracks, blendMode);
name-- identificador de texto (los clips GLTF usan nombres del archivo)duration-- segundos;-1para calcular automáticamente a partir de las pistastracks-- array de objetosKeyframeTrackblendMode-- constante de modo de mezcla opcional
Métodos Estáticos Clave
| Método | Descripción |
|---|---|
AnimationClip.findByName(arrayOrObject, name) | Buscar clip por nombre |
AnimationClip.CreateFromMorphTargetSequence(name, targets, fps, noLoop) | Crear clip a partir de morph targets |
AnimationClip.parse(json) | Deserializar desde JSON |
Tipos de KeyframeTrack
| Tipo de Pista | Tipo de Valor | Caso de Uso |
|---|---|---|
VectorKeyframeTrack | Vector3 | Posición, escala |
QuaternionKeyframeTrack | Quaternion | Rotación (usa slerp) |
NumberKeyframeTrack | number | Opacidad, intensidad |
BooleanKeyframeTrack | boolean | Alternar visibilidad |
ColorKeyframeTrack | Color | Animación de color |
StringKeyframeTrack | string | Valores discretos de texto |
Modos de Interpolación
| Constante | Comportamiento |
|---|---|
THREE.InterpolateDiscrete | Función escalón, sin suavizado |
THREE.InterpolateLinear | Interpolación lineal (por defecto) |
THREE.InterpolateSmooth | Interpolación por spline cúbico |
Formato de Ruta de PropertyBinding
"meshName.position" // animar posición
"meshName.material.opacity" // animar propiedad del material
"meshName.morphTargetInfluences[0]" // animar morph target
"boneName.quaternion" // animar rotación de hueso
Clock
Constructor
const clock = new THREE.Clock(autoStart); // autoStart por defecto es true
Métodos
| Método | Retorna | Descripción |
|---|---|---|
.getDelta() | number | Segundos desde la última llamada a getDelta() |
.getElapsedTime() | number | Tiempo total transcurrido en segundos |
.start() | void | Iniciar el reloj |
.stop() | void | Detener sin reiniciar |
Patrón de Transición (Máquina de Estados de Personaje)
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;
}
SIEMPRE llama a .reset() en la acción entrante antes de hacer crossfade.
SIEMPRE almacena la referencia de la acción actual para la siguiente transición.
Mezcla de Animación Aditiva
const baseAction = mixer.clipAction(baseClip);
const additiveAction = mixer.clipAction(
additiveClip, undefined, THREE.AdditiveAnimationBlendMode
);
baseAction.play();
additiveAction.play();
additiveAction.setEffectiveWeight(0.5);
Usa mezcla aditiva para efectos superpuestos: respiración, reacciones a daño, offsets de puntería.
Animación de Morph Targets
// Control manual
mesh.morphTargetInfluences[0] = Math.sin(elapsed) * 0.5 + 0.5;
// Mediante clip de animación GLTF (preferido)
const morphAction = mixer.clipAction(morphClip);
morphAction.play();
Enlaces de Referencia
- references/methods.md -- Firmas completas de la API
- references/examples.md -- Ejemplos de código funcionales
- references/anti-patterns.md -- Lo que NO hay que hacer
Fuentes Oficiales
- 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