Animação Three.js
Quando Usar
- Você precisa animar objetos, rigs, morph targets ou animações GLTF importadas no Three.js.
- A tarefa envolve mixers, clipes, keyframes, movimento procedural ou mistura de animações.
- Você está construindo comportamento de movimento em uma cena Three.js em vez de apenas renderização estática.
Início Rápido
import * as THREE from "three";
// Animação procedural simples com Timer (recomendado a partir de r183)
const timer = new THREE.Timer();
renderer.setAnimationLoop(() => {
timer.update();
const delta = timer.getDelta();
const elapsed = timer.getElapsed();
mesh.rotation.y += delta;
mesh.position.y = Math.sin(elapsed) * 0.5;
renderer.render(scene, camera);
});
Nota: THREE.Timer é recomendado sobre THREE.Clock a partir de r183. O Timer pausa quando a página está oculta e tem uma API mais limpa. THREE.Clock ainda funciona, mas é considerado legado.
Visão Geral do Sistema de Animação
O sistema de animação Three.js possui três componentes principais:
- AnimationClip - Contêiner para dados de keyframe
- AnimationMixer - Reproduz animações em um objeto raiz
- AnimationAction - Controla a reprodução de um clipe
AnimationClip
Armazena dados de animação de keyframe.
// Criar clipe de animação
const times = [0, 1, 2]; // Tempos dos keyframes (segundos)
const values = [0, 1, 0]; // Valores em cada keyframe
const track = new THREE.NumberKeyframeTrack(
".position[y]", // Caminho da propriedade
times,
values,
);
const clip = new THREE.AnimationClip("bounce", 2, [track]);
Tipos de KeyframeTrack
// Track numérico (valor único)
new THREE.NumberKeyframeTrack(".opacity", times, [1, 0]);
new THREE.NumberKeyframeTrack(".material.opacity", times, [1, 0]);
// Track de vetor (posição, escala)
new THREE.VectorKeyframeTrack(".position", times, [
0,
0,
0, // t=0
1,
2,
0, // t=1
0,
0,
0, // t=2
]);
// Track de Quaternion (rotação)
const q1 = new THREE.Quaternion().setFromEuler(new THREE.Euler(0, 0, 0));
const q2 = new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI, 0));
new THREE.QuaternionKeyframeTrack(
".quaternion",
[0, 1],
[q1.x, q1.y, q1.z, q1.w, q2.x, q2.y, q2.z, q2.w],
);
// Track de cor
new THREE.ColorKeyframeTrack(".material.color", times, [
1,
0,
0, // vermelho
0,
1,
0, // verde
0,
0,
1, // azul
]);
// Track booleano
new THREE.BooleanKeyframeTrack(".visible", [0, 0.5, 1], [true, false, true]);
// Track de string (para morph targets)
new THREE.StringKeyframeTrack(
".morphTargetInfluences[smile]",
[0, 1],
["0", "1"],
);
Modos de Interpolação
const track = new THREE.VectorKeyframeTrack(".position", times, values);
// Interpolação
track.setInterpolation(THREE.InterpolateLinear); // Padrão
track.setInterpolation(THREE.InterpolateSmooth); // Spline cúbica
track.setInterpolation(THREE.InterpolateDiscrete); // Função degrau
BezierInterpolant (r183)
Three.js r183 adiciona THREE.BezierInterpolant para interpolação de curvas bezier em tracks de keyframe, permitindo curvas de animação mais suaves com controle de tangente.
AnimationMixer
Reproduz animações em um objeto e seus descendentes.
const mixer = new THREE.AnimationMixer(model);
// Criar ação a partir do clipe
const action = mixer.clipAction(clip);
action.play();
// Atualizar no loop de animação
function animate() {
const delta = clock.getDelta();
mixer.update(delta); // Necessário!
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
Eventos do Mixer
mixer.addEventListener("finished", (e) => {
console.log("Animação finalizada:", e.action.getClip().name);
});
mixer.addEventListener("loop", (e) => {
console.log("Animação repetida:", e.action.getClip().name);
});
AnimationAction
Controla a reprodução de um clipe de animação.
const action = mixer.clipAction(clip);
// Controle de reprodução
action.play();
action.stop();
action.reset();
action.halt(fadeOutDuration);
// Estado de reprodução
action.isRunning();
action.isScheduled();
// Controle de tempo
action.time = 0.5; // Tempo atual
action.timeScale = 1; // Velocidade de reprodução (negativo = reverso)
action.paused = false;
// Peso (para mistura)
action.weight = 1; // 0-1, contribuição para a pose final
action.setEffectiveWeight(1);
// Modos de repetição
action.loop = THREE.LoopRepeat; // Padrão: repetir para sempre
action.loop = THREE.LoopOnce; // Reproduzir uma vez e parar
action.loop = THREE.LoopPingPong; // Alternar avante/trás
action.repetitions = 3; // Número de repetições (Infinito padrão)
// Fixação
action.clampWhenFinished = true; // Manter último quadro quando terminar
// Mistura
action.blendMode = THREE.NormalAnimationBlendMode;
action.blendMode = THREE.AdditiveAnimationBlendMode;
Fade In/Out
// Fade in
action.reset().fadeIn(0.5).play();
// Fade out
action.fadeOut(0.5);
// Crossfade entre animações
const action1 = mixer.clipAction(clip1);
const action2 = mixer.clipAction(clip2);
action1.play();
// Mais tarde, crossfade para action2
action1.crossFadeTo(action2, 0.5, true);
action2.play();
Carregando Animações GLTF
Fonte mais comum de animações esqueléticas.
import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
const loader = new GLTFLoader();
loader.load("model.glb", (gltf) => {
const model = gltf.scene;
scene.add(model);
// Criar mixer
const mixer = new THREE.AnimationMixer(model);
// Obter todos os clipes
const clips = gltf.animations;
console.log(
"Animações disponíveis:",
clips.map((c) => c.name),
);
// Reproduzir primeira animação
if (clips.length > 0) {
const action = mixer.clipAction(clips[0]);
action.play();
}
// Reproduzir animação específica por nome
const walkClip = THREE.AnimationClip.findByName(clips, "Walk");
if (walkClip) {
mixer.clipAction(walkClip).play();
}
// Armazenar mixer para o loop de atualização
window.mixer = mixer;
});
// Loop de animação
function animate() {
const delta = clock.getDelta();
if (window.mixer) window.mixer.update(delta);
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
Animação Esquelética
Esqueleto e Ossos
// Acessar esqueleto de um mesh skinned
const skinnedMesh = model.getObjectByProperty("type", "SkinnedMesh");
const skeleton = skinnedMesh.skeleton;
// Acessar ossos
skeleton.bones.forEach((bone) => {
console.log(bone.name, bone.position, bone.rotation);
});
// Encontrar osso específico por nome
const headBone = skeleton.bones.find((b) => b.name === "Head");
if (headBone) headBone.rotation.y = Math.PI / 4; // Virar cabeça
// Auxiliar de esqueleto
const helper = new THREE.SkeletonHelper(model);
scene.add(helper);
Animação Programática de Ossos
function animate() {
const time = clock.getElapsedTime();
// Animar osso
const headBone = skeleton.bones.find((b) => b.name === "Head");
if (headBone) {
headBone.rotation.y = Math.sin(time) * 0.3;
}
// Atualizar mixer se também estiver reproduzindo clipes
mixer.update(clock.getDelta());
}
Anexos aos Ossos
// Anexar objeto a um osso
const weapon = new THREE.Mesh(weaponGeometry, weaponMaterial);
const handBone = skeleton.bones.find((b) => b.name === "RightHand");
if (handBone) handBone.add(weapon);
// Compensar anexo
weapon.position.set(0, 0, 0.5);
weapon.rotation.set(0, Math.PI / 2, 0);
Morph Targets
Mistura entre diferentes formas de malha.
// Morph targets são armazenados na geometria
const geometry = mesh.geometry;
console.log("Atributos morph:", Object.keys(geometry.morphAttributes));
// Acessar influências de morph target
mesh.morphTargetInfluences; // Array de pesos
mesh.morphTargetDictionary; // Mapa nome -> índice
// Definir morph target por índice
mesh.morphTargetInfluences[0] = 0.5;
// Definir por nome
const smileIndex = mesh.morphTargetDictionary["smile"];
mesh.morphTargetInfluences[smileIndex] = 1;
Animando Morph Targets
// Procedural
function animate() {
const t = clock.getElapsedTime();
mesh.morphTargetInfluences[0] = (Math.sin(t) + 1) / 2;
}
// Com animação keyframe
const track = new THREE.NumberKeyframeTrack(
".morphTargetInfluences[smile]",
[0, 0.5, 1],
[0, 1, 0],
);
const clip = new THREE.AnimationClip("smile", 1, [track]);
mixer.clipAction(clip).play();
Mistura de Animações
Misturar múltiplas animações juntas.
// Configurar ações
const idleAction = mixer.clipAction(idleClip);
const walkAction = mixer.clipAction(walkClip);
const runAction = mixer.clipAction(runClip);
// Reproduzir todas com diferentes pesos
idleAction.play();
walkAction.play();
runAction.play();
// Definir pesos iniciais
idleAction.setEffectiveWeight(1);
walkAction.setEffectiveWeight(0);
runAction.setEffectiveWeight(0);
// Misturar baseado na velocidade
function updateAnimations(speed) {
if (speed < 0.1) {
idleAction.setEffectiveWeight(1);
walkAction.setEffectiveWeight(0);
runAction.setEffectiveWeight(0);
} else if (speed < 5) {
const t = speed / 5;
idleAction.setEffectiveWeight(1 - t);
walkAction.setEffectiveWeight(t);
runAction.setEffectiveWeight(0);
} else {
const t = Math.min((speed - 5) / 5, 1);
idleAction.setEffectiveWeight(0);
walkAction.setEffectiveWeight(1 - t);
runAction.setEffectiveWeight(t);
}
}
Mistura Aditiva
// Pose base
const baseAction = mixer.clipAction(baseClip);
baseAction.play();
// Camada aditiva (ex: respiração)
const additiveAction = mixer.clipAction(additiveClip);
additiveAction.blendMode = THREE.AdditiveAnimationBlendMode;
additiveAction.play();
// Converter clipe para aditivo
THREE.AnimationUtils.makeClipAdditive(additiveClip);
Utilitários de Animação
import * as THREE from "three";
// Encontrar clipe por nome
const clip = THREE.AnimationClip.findByName(clips, "Walk");
// Criar subclipe
const subclip = THREE.AnimationUtils.subclip(clip, "subclip", 0, 30, 30);
// Converter para aditivo
THREE.AnimationUtils.makeClipAdditive(clip);
THREE.AnimationUtils.makeClipAdditive(clip, 0, referenceClip);
// Clonar clipe
const clone = clip.clone();
// Obter duração do clipe
clip.duration;
// Otimizar clipe (remover keyframes redundantes)
clip.optimize();
// Reiniciar duração do clipe
clip.resetDuration();
Padrões de Animação Procedural
Damping Suave
// Seguir suave/lerp
const target = new THREE.Vector3();
const current = new THREE.Vector3();
const velocity = new THREE.Vector3();
function smoothDamp(current, target, velocity, smoothTime, deltaTime) {
const omega = 2 / smoothTime;
const x = omega * deltaTime;
const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x);
const change = current.clone().sub(target);
const temp = velocity
.clone()
.add(change.clone().multiplyScalar(omega))
.multiplyScalar(deltaTime);
velocity.sub(temp.clone().multiplyScalar(omega)).multiplyScalar(exp);
return target.clone().add(change.add(temp).multiplyScalar(exp));
}
function animate() {
current.copy(smoothDamp(current, target, velocity, 0.3, delta));
mesh.position.copy(current);
}
Física de Mola
class Spring {
constructor(stiffness = 100, damping = 10) {
this.stiffness = stiffness;
this.damping = damping;
this.position = 0;
this.velocity = 0;
this.target = 0;
}
update(dt) {
const force = -this.stiffness * (this.position - this.target);
const dampingForce = -this.damping * this.velocity;
this.velocity += (force + dampingForce) * dt;
this.position += this.velocity * dt;
return this.position;
}
}
const spring = new Spring(100, 10);
spring.target = 1;
function animate() {
mesh.position.y = spring.update(delta);
}
Oscilação
function animate() {
const t = clock.getElapsedTime();
// Onda senoidal
mesh.position.y = Math.sin(t * 2) * 0.5;
// Quicar
mesh.position.y = Math.abs(Math.sin(t * 3)) * 2;
// Movimento circular
mesh.position.x = Math.cos(t) * 2;
mesh.position.z = Math.sin(t) * 2;
// Figura 8
mesh.position.x = Math.sin(t) * 2;
mesh.position.z = Math.sin(t * 2) * 1;
}
Dicas de Performance
- Compartilhar clipes: O mesmo AnimationClip pode ser usado em múltiplos mixers
- Otimizar clipes: Chame
clip.optimize()para remover keyframes redundantes - Desativar quando fora da tela: Pare atualizações de mixer para objetos invisíveis
- Use LOD para animações: Rigs mais simples para personagens distantes
- Limite mixers ativos: Cada mixer.update() tem um custo
// Pausar animação quando não visível
mesh.onBeforeRender = () => {
action.paused = false;
};
mesh.onAfterRender = () => {
// Verificar se será visível no próximo quadro
if (!isInFrustum(mesh)) {
action.paused = true;
}
};
// Cache de clipes
const clipCache = new Map();
function getClip(name) {
if (!clipCache.has(name)) {
clipCache.set(name, loadClip(name));
}
return clipCache.get(name);
}
Veja Também
threejs-loaders- Carregar modelos GLTF animadosthreejs-fundamentals- Relógio e loop de animaçãothreejs-shaders- Animação de vértices em shaders
Limitações
- Use este skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate a saída como substituta para validação específica do ambiente, testes ou revisão especializada.
- Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem faltando.