Three.js-Animation
Wann verwenden
- Sie müssen Objekte, Rigs, Morph-Ziele oder importierte GLTF-Animationen in Three.js animieren.
- Die Aufgabe umfasst Mixer, Clips, Keyframes, prozedurale Bewegungen oder Animations-Mixing.
- Sie bauen Bewegungsverhalten in einer Three.js-Szene auf, nicht nur statisches Rendering.
Schnellstart
import * as THREE from "three";
// Einfache prozedurale Animation mit Timer (empfohlen ab 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);
});
Hinweis: THREE.Timer wird ab r183 gegenüber THREE.Clock bevorzugt. Timer pausiert, wenn die Seite versteckt ist, und hat eine sauberere API. THREE.Clock funktioniert weiterhin, gilt aber als veraltet.
Überblick über das Animationssystem
Das Three.js-Animationssystem besteht aus drei Hauptkomponenten:
- AnimationClip – Container für Keyframe-Daten
- AnimationMixer – Spielt Animationen auf einem Basisobjekt ab
- AnimationAction – Steuert die Wiedergabe eines Clips
AnimationClip
Speichert Keyframe-Animationsdaten.
// Animationsclip erstellen
const times = [0, 1, 2]; // Keyframe-Zeiten (Sekunden)
const values = [0, 1, 0]; // Werte an jedem Keyframe
const track = new THREE.NumberKeyframeTrack(
".position[y]", // Eigenschaftspfad
times,
values,
);
const clip = new THREE.AnimationClip("bounce", 2, [track]);
KeyframeTrack-Typen
// Zahlen-Track (einzelner Wert)
new THREE.NumberKeyframeTrack(".opacity", times, [1, 0]);
new THREE.NumberKeyframeTrack(".material.opacity", times, [1, 0]);
// Vektor-Track (Position, Skalierung)
new THREE.VectorKeyframeTrack(".position", times, [
0,
0,
0, // t=0
1,
2,
0, // t=1
0,
0,
0, // t=2
]);
// Quaternion-Track (Rotation)
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],
);
// Farb-Track
new THREE.ColorKeyframeTrack(".material.color", times, [
1,
0,
0, // rot
0,
1,
0, // grün
0,
0,
1, // blau
]);
// Boolean-Track
new THREE.BooleanKeyframeTrack(".visible", [0, 0.5, 1], [true, false, true]);
// Zeichenfolgen-Track (für Morph-Ziele)
new THREE.StringKeyframeTrack(
".morphTargetInfluences[smile]",
[0, 1],
["0", "1"],
);
Interpolationsmodi
const track = new THREE.VectorKeyframeTrack(".position", times, values);
// Interpolation
track.setInterpolation(THREE.InterpolateLinear); // Standard
track.setInterpolation(THREE.InterpolateSmooth); // Kubischer Spline
track.setInterpolation(THREE.InterpolateDiscrete); // Treppenfunktion
BezierInterpolant (r183)
Three.js r183 fügt THREE.BezierInterpolant für Bézier-Kurveninterpolation in Keyframe-Tracks hinzu, was glattere Animationskurven mit Tangentenkontrolle ermöglicht.
AnimationMixer
Spielt Animationen auf einem Objekt und seinen Nachkommen ab.
const mixer = new THREE.AnimationMixer(model);
// Aktion aus Clip erstellen
const action = mixer.clipAction(clip);
action.play();
// In der Animationsschleife aktualisieren
function animate() {
const delta = clock.getDelta();
mixer.update(delta); // Erforderlich!
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
Mixer-Ereignisse
mixer.addEventListener("finished", (e) => {
console.log("Animation beendet:", e.action.getClip().name);
});
mixer.addEventListener("loop", (e) => {
console.log("Animation wiederholt:", e.action.getClip().name);
});
AnimationAction
Steuert die Wiedergabe eines Animationsclips.
const action = mixer.clipAction(clip);
// Wiedergabesteuerung
action.play();
action.stop();
action.reset();
action.halt(fadeOutDuration);
// Wiedergabestatus
action.isRunning();
action.isScheduled();
// Zeitsteuerung
action.time = 0.5; // Aktuelle Zeit
action.timeScale = 1; // Wiedergabegeschwindigkeit (negativ = rückwärts)
action.paused = false;
// Gewicht (für Blending)
action.weight = 1; // 0-1, Beitrag zur endgültigen Pose
action.setEffectiveWeight(1);
// Schleifenmodi
action.loop = THREE.LoopRepeat; // Standard: unendlich wiederholen
action.loop = THREE.LoopOnce; // Einmal abspielen und stoppen
action.loop = THREE.LoopPingPong; // Abwechselnd vorwärts/rückwärts
action.repetitions = 3; // Anzahl der Wiederholungen (Standard: Unendlich)
// Clamping
action.clampWhenFinished = true; // Letzten Frame halten, wenn fertig
// Blending
action.blendMode = THREE.NormalAnimationBlendMode;
action.blendMode = THREE.AdditiveAnimationBlendMode;
Ein-/Ausblenden
// Einblenden
action.reset().fadeIn(0.5).play();
// Ausblenden
action.fadeOut(0.5);
// Überblenden zwischen Animationen
const action1 = mixer.clipAction(clip1);
const action2 = mixer.clipAction(clip2);
action1.play();
// Später zu action2 überblenden
action1.crossFadeTo(action2, 0.5, true);
action2.play();
GLTF-Animationen laden
Häufigste Quelle für Skelett-Animationen.
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);
// Mixer erstellen
const mixer = new THREE.AnimationMixer(model);
// Alle Clips abrufen
const clips = gltf.animations;
console.log(
"Verfügbare Animationen:",
clips.map((c) => c.name),
);
// Erste Animation abspielen
if (clips.length > 0) {
const action = mixer.clipAction(clips[0]);
action.play();
}
// Bestimmte Animation nach Namen abspielen
const walkClip = THREE.AnimationClip.findByName(clips, "Walk");
if (walkClip) {
mixer.clipAction(walkClip).play();
}
// Mixer für Aktualisierungsschleife speichern
window.mixer = mixer;
});
// Animationsschleife
function animate() {
const delta = clock.getDelta();
if (window.mixer) window.mixer.update(delta);
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
Skelett-Animation
Skelett und Knochen
// Auf Skelett von SkinnedMesh zugreifen
const skinnedMesh = model.getObjectByProperty("type", "SkinnedMesh");
const skeleton = skinnedMesh.skeleton;
// Auf Knochen zugreifen
skeleton.bones.forEach((bone) => {
console.log(bone.name, bone.position, bone.rotation);
});
// Bestimmten Knochen nach Namen finden
const headBone = skeleton.bones.find((b) => b.name === "Head");
if (headBone) headBone.rotation.y = Math.PI / 4; // Kopf drehen
// Skelett-Helfer
const helper = new THREE.SkeletonHelper(model);
scene.add(helper);
Programmgesteuerte Knochen-Animation
function animate() {
const time = clock.getElapsedTime();
// Knochen animieren
const headBone = skeleton.bones.find((b) => b.name === "Head");
if (headBone) {
headBone.rotation.y = Math.sin(time) * 0.3;
}
// Mixer aktualisieren, falls auch Clips abgespielt werden
mixer.update(clock.getDelta());
}
Knochen-Befestigungen
// Objekt an Knochen befestigen
const weapon = new THREE.Mesh(weaponGeometry, weaponMaterial);
const handBone = skeleton.bones.find((b) => b.name === "RightHand");
if (handBone) handBone.add(weapon);
// Versatz der Befestigung
weapon.position.set(0, 0, 0.5);
weapon.rotation.set(0, Math.PI / 2, 0);
Morph-Ziele
Überblendung zwischen verschiedenen Netzformen.
// Morph-Ziele sind in der Geometrie gespeichert
const geometry = mesh.geometry;
console.log("Morph-Attribute:", Object.keys(geometry.morphAttributes));
// Auf Morph-Ziel-Einflüsse zugreifen
mesh.morphTargetInfluences; // Array von Gewichten
mesh.morphTargetDictionary; // Name -> Index-Zuordnung
// Morph-Ziel nach Index setzen
mesh.morphTargetInfluences[0] = 0.5;
// Nach Name setzen
const smileIndex = mesh.morphTargetDictionary["smile"];
mesh.morphTargetInfluences[smileIndex] = 1;
Morph-Ziele animieren
// Prozedural
function animate() {
const t = clock.getElapsedTime();
mesh.morphTargetInfluences[0] = (Math.sin(t) + 1) / 2;
}
// Mit Keyframe-Animation
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();
Animations-Mixing
Mehrere Animationen mischen.
// Aktionen einrichten
const idleAction = mixer.clipAction(idleClip);
const walkAction = mixer.clipAction(walkClip);
const runAction = mixer.clipAction(runClip);
// Alle mit unterschiedlichen Gewichten abspielen
idleAction.play();
walkAction.play();
runAction.play();
// Anfangsgewichte setzen
idleAction.setEffectiveWeight(1);
walkAction.setEffectiveWeight(0);
runAction.setEffectiveWeight(0);
// Basierend auf Geschwindigkeit mischen
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);
}
}
Additives Blending
// Basis-Pose
const baseAction = mixer.clipAction(baseClip);
baseAction.play();
// Additive Ebene (z. B. Atmen)
const additiveAction = mixer.clipAction(additiveClip);
additiveAction.blendMode = THREE.AdditiveAnimationBlendMode;
additiveAction.play();
// Clip in additiv umwandeln
THREE.AnimationUtils.makeClipAdditive(additiveClip);
Animations-Hilfsfunktionen
import * as THREE from "three";
// Clip nach Namen finden
const clip = THREE.AnimationClip.findByName(clips, "Walk");
// Unterclip erstellen
const subclip = THREE.AnimationUtils.subclip(clip, "subclip", 0, 30, 30);
// In additiv umwandeln
THREE.AnimationUtils.makeClipAdditive(clip);
THREE.AnimationUtils.makeClipAdditive(clip, 0, referenceClip);
// Clip klonen
const clone = clip.clone();
// Clip-Dauer abrufen
clip.duration;
// Clip optimieren (redundante Keyframes entfernen)
clip.optimize();
// Clip auf ersten Frame zurücksetzen
clip.resetDuration();
Prozedurale Animationsmuster
Sanfte Dämpfung
// Sanftes Folgen/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);
}
Feder-Physik
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);
}
Oszillation
function animate() {
const t = clock.getElapsedTime();
// Sinuswelle
mesh.position.y = Math.sin(t * 2) * 0.5;
// Hüpfen
mesh.position.y = Math.abs(Math.sin(t * 3)) * 2;
// Kreisbewegung
mesh.position.x = Math.cos(t) * 2;
mesh.position.z = Math.sin(t) * 2;
// Acht
mesh.position.x = Math.sin(t) * 2;
mesh.position.z = Math.sin(t * 2) * 1;
}
Leistungstipps
- Clips teilen: Derselbe AnimationClip kann auf mehreren Mixern verwendet werden
- Clips optimieren: Rufen Sie
clip.optimize()auf, um redundante Keyframes zu entfernen - Bei Nicht-Sichtbarkeit deaktivieren: Stoppen Sie Mixer-Updates für unsichtbare Objekte
- LOD für Animationen verwenden: Einfachere Rigs für entfernte Charaktere
- Aktive Mixer begrenzen: Jeder
mixer.update()hat Kosten
// Animation pausieren, wenn nicht sichtbar
mesh.onBeforeRender = () => {
action.paused = false;
};
mesh.onAfterRender = () => {
// Prüfen, ob es im nächsten Frame sichtbar sein wird
if (!isInFrustum(mesh)) {
action.paused = true;
}
};
// Clips cachen
const clipCache = new Map();
function getClip(name) {
if (!clipCache.has(name)) {
clipCache.set(name, loadClip(name));
}
return clipCache.get(name);
}
Siehe auch
threejs-loaders– Animierte GLTF-Modelle ladenthreejs-fundamentals– Clock und Animationsschleifethreejs-shaders– Vertex-Animation in Shadern
Einschränkungen
- Verwenden Sie diese Fähigkeit nur, wenn die Aufgabe eindeutig zum oben beschriebenen Umfang passt.
- Behandeln Sie die Ausgabe nicht als Ersatz für umgebungsspezifische Validierung, Tests oder Expertenprüfung.
- Fragen Sie nach, wenn erforderliche Eingaben, Berechtigungen, Sicherheitsgrenzen oder Erfolgskriterien fehlen.