threejs-impl-animation
Referência Rápida
Arquitetura
AnimationClip (dados: array de objetos KeyframeTrack)
└── AnimationAction (controlador de reprodução: play, pause, fade, crossfade)
└── AnimationMixer (agendador mestre: um por objeto raiz animado)
└── Clock (fornece tempo delta para mixer.update)
SEMPRE crie exatamente UM AnimationMixer por objeto raiz animado.
SEMPRE chame mixer.update(delta) a cada frame dentro do loop de renderização.
NUNCA instancie AnimationAction diretamente -- SEMPRE use mixer.clipAction(clip).
Importações Essenciais
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
Configuração Mínima de Animação
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);
// Reproduz todas as animações do arquivo 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);
Avisos Críticos
NUNCA se esqueça de chamar mixer.update(delta) no loop de renderização -- as animações NÃO funcionarão sem isso.
NUNCA use new Date() ou performance.now() para calcular delta manualmente -- SEMPRE use THREE.Clock ou renderer.setAnimationLoop, que fornece temporização de frame estável.
NUNCA chame mixer.clipAction(clip) repetidamente no loop de renderização -- ele faz cache internamente, mas a busca é uma sobrecarga desnecessária. SEMPRE armazene a ação retornada em uma variável.
NUNCA chame .play() a cada frame -- chame-o UMA VEZ para iniciar a reprodução. Chamar .play() novamente em uma ação já em execução não tem efeito, mas indica falta de compreensão.
SEMPRE chame .reset() antes de .play() ao reiniciar uma ação parada ou finalizada, caso contrário a ação pode retomar da última posição.
SEMPRE defina action.clampWhenFinished = true ao usar LoopOnce -- caso contrário, a ação retorna ao primeiro quadro quando termina.
AnimationMixer
O agendador mestre que controla todas as ações de animação para uma única hierarquia de objetos.
Construtor
const mixer = new THREE.AnimationMixer(rootObject);
rootObject é o Object3D raiz do modelo animado (geralmente gltf.scene).
Propriedades
| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
.time | number | 0 | Tempo global do mixer em segundos |
.timeScale | number | 1 | Multiplicador de velocidade global; 0 pausa TODAS as ações |
Métodos
| Método | Retorno | Descrição |
|---|---|---|
.clipAction(clip, root?, blendMode?) | AnimationAction | Retorna ou cria uma ação para o clipe |
.existingAction(clip, root?) | AnimationAction | null | Retorna a ação criada anteriormente ou null |
.update(delta) | this | Avança o mixer em delta segundos -- DEVE ser chamado a cada frame |
.setTime(seconds) | this | Define o tempo global, atualiza todas as ações |
.stopAllAction() | this | Desativa todas as ações agendadas |
.getRoot() | Object3D | Retorna o objeto raiz do mixer |
.uncacheAction(clip, root?) | void | Desaloca a ação em cache |
.uncacheClip(clip) | void | Desaloca os dados do clipe |
.uncacheRoot(root) | void | Desaloca os dados do objeto raiz |
Eventos
Escute via mixer.addEventListener(type, callback):
| Evento | Disparado Quando |
|---|---|
'finished' | A ação é concluída (APENAS com LoopOnce + clampWhenFinished = true) |
'loop' | A ação completa uma iteração do loop |
Propriedades do objeto de evento: { action, loopDelta, type }.
Modos de Blending
Passe como terceiro argumento para mixer.clipAction(clip, root, blendMode):
| Constante | Comportamento |
|---|---|
THREE.NormalAnimationBlendMode | Blending padrão (padrão) |
THREE.AdditiveAnimationBlendMode | Camadas sobrepostas à animação base |
AnimationAction
Controla a reprodução de um único clipe de animação. NUNCA instancie diretamente.
Propriedades
| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
.blendMode | number | NormalAnimationBlendMode | Estratégia de blending |
.clampWhenFinished | boolean | false | Pausa no último frame quando termina |
.enabled | boolean | true | Desabilitar sem redefinir |
.loop | number | LoopRepeat | Modo de loop |
.paused | boolean | false | Congela a reprodução |
.repetitions | number | Infinity | Número de repetições |
.time | number | 0 | Tempo local em segundos |
.timeScale | number | 1 | Velocidade: 0 pausa, negativo reverte |
.weight | number | 1 | Influência do blend [0, 1] |
.zeroSlopeAtEnd | boolean | true | Interpolação suave no final do loop |
.zeroSlopeAtStart | boolean | true | Interpolação suave no início do loop |
Modos de Loop
| Constante | Comportamento |
|---|---|
THREE.LoopOnce | Reproduz uma vez, para |
THREE.LoopRepeat | Reinicia do início a cada loop |
THREE.LoopPingPong | Alterna entre avanço e retrocesso |
Métodos de Reprodução
| Método | Descrição |
|---|---|
.play() | Iniciar reprodução |
.stop() | Parar e redefinir para o início |
.reset() | Redefinir tempo, peso, velocidade para o estado inicial |
.startAt(mixerTime) | Atrasar início até o tempo especificado do mixer |
Métodos de Fade e Crossfade
| Método | Descrição |
|---|---|
.fadeIn(duration) | Transição de peso de 0 para 1 |
.fadeOut(duration) | Transição de peso de 1 para 0 |
.crossFadeFrom(fadeOutAction, duration, warp) | Crossfade de outra ação para esta |
.crossFadeTo(fadeInAction, duration, warp) | Crossfade desta ação para outra |
.stopFading() | Cancelar qualquer fade ativo |
Métodos de Velocidade e Temporização
| Método | Descrição |
|---|---|
.halt(duration) | Desacelerar timeScale para 0 ao longo da duração |
.warp(startScale, endScale, duration) | Transição suave da velocidade de reprodução |
.stopWarping() | Cancelar qualquer warp ativo |
.setDuration(seconds) | Ajustar timeScale para que um loop dure exatamente seconds |
.setEffectiveTimeScale(scale) | Definir escala de tempo efetiva |
.setEffectiveWeight(weight) | Definir peso efetivo |
.setLoop(mode, repetitions) | Definir modo de loop e contagem |
.syncWith(otherAction) | Sincronizar tempo com outra ação |
Métodos de Consulta
| Método | Retorno | Descrição |
|---|---|---|
.isRunning() | boolean | true somente se estiver ativamente tocando |
.isScheduled() | boolean | true se .play() foi chamado |
.getClip() | AnimationClip | O clipe associado |
.getMixer() | AnimationMixer | O mixer proprietário |
.getRoot() | Object3D | O objeto raiz |
.getEffectiveTimeScale() | number | Escala de tempo computada |
.getEffectiveWeight() | number | Peso computado |
AnimationClip
Um conjunto reutilizável de trilhas de keyframe. Geralmente carregado de arquivos GLTF.
Construtor
const clip = new THREE.AnimationClip(name, duration, tracks, blendMode);
name-- identificador de string (clipes GLTF usam nomes do arquivo)duration-- segundos;-1para calcular automaticamente a partir das trilhastracks-- array de objetosKeyframeTrackblendMode-- constante de modo de blending opcional
Principais Métodos Estáticos
| Método | Descrição |
|---|---|
AnimationClip.findByName(arrayOrObject, name) | Buscar clipe pelo nome |
AnimationClip.CreateFromMorphTargetSequence(name, targets, fps, noLoop) | Criar clipe a partir de sequência de morph targets |
AnimationClip.parse(json) | Desserializar de JSON |
Tipos de KeyframeTrack
| Tipo de Trilha | Tipo de Valor | Caso de Uso |
|---|---|---|
VectorKeyframeTrack | Vector3 | Posição, escala |
QuaternionKeyframeTrack | Quaternion | Rotação (usa slerp) |
NumberKeyframeTrack | number | Opacidade, intensidade |
BooleanKeyframeTrack | boolean | Alternância de visibilidade |
ColorKeyframeTrack | Color | Animação de cor |
StringKeyframeTrack | string | Valores discretos de string |
Modos de Interpolação
| Constante | Comportamento |
|---|---|
THREE.InterpolateDiscrete | Função degrau, sem suavização |
THREE.InterpolateLinear | Interpolação linear (padrão) |
THREE.InterpolateSmooth | Interpolação spline cúbica |
Formato do Caminho de PropertyBinding
"meshName.position" // animar posição
"meshName.material.opacity" // animar propriedade de material
"meshName.morphTargetInfluences[0]" // animar morph target
"boneName.quaternion" // animar rotação de osso
Clock
Construtor
const clock = new THREE.Clock(autoStart); // autoStart padrão é true
Métodos
| Método | Retorno | Descrição |
|---|---|---|
.getDelta() | number | Segundos desde a última chamada de getDelta() |
.getElapsedTime() | number | Tempo total decorrido em segundos |
.start() | void | Iniciar o clock |
.stop() | void | Parar sem redefinir |
Padrão de Crossfade (Máquina de Estados do Personagem)
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;
}
SEMPRE chame .reset() na ação de entrada antes do crossfade.
SEMPRE armazene a referência da ação atual para a próxima transição.
Blending Aditivo de Animação
const baseAction = mixer.clipAction(baseClip);
const additiveAction = mixer.clipAction(
additiveClip, undefined, THREE.AdditiveAnimationBlendMode
);
baseAction.play();
additiveAction.play();
additiveAction.setEffectiveWeight(0.5);
Use blending aditivo para efeitos em camadas: respiração, reações de dano, ajustes de mira.
Animação de Morph Target
// Controle manual
mesh.morphTargetInfluences[0] = Math.sin(elapsed) * 0.5 + 0.5;
// Via clipe de animação GLTF (preferido)
const morphAction = mixer.clipAction(morphClip);
morphAction.play();
Links de Referência
- references/methods.md -- Assinaturas completas da API
- references/examples.md -- Exemplos de código funcionais
- references/anti-patterns.md -- O que NÃO fazer
Fontes Oficiais
- 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