threejs-impl-animation
Kurzreferenz
Architektur
AnimationClip (Daten: Array von KeyframeTrack-Objekten)
└── AnimationAction (Wiedergabesteuerung: play, pause, fade, crossfade)
└── AnimationMixer (Master-Scheduler: einer pro animiertem Wurzelobjekt)
└── Clock (liefert Delta-Zeit für mixer.update)
ALWAYS genau EINEN AnimationMixer pro animiertem Wurzelobjekt erstellen.
ALWAYS mixer.update(delta) in jedem Frame innerhalb der Render-Schleife aufrufen.
NIEMALS AnimationAction direkt instanziieren – ALWAYS mixer.clipAction(clip) verwenden.
Wichtige Imports
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
Minimales Animations-Setup
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);
// Alle Animationen aus der GLTF-Datei abspielen
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);
Kritische Warnungen
NIEMALS vergessen, mixer.update(delta) in der Render-Schleife aufzurufen – Animationen werden OHNE diesen Aufruf NICHT abgespielt.
NIEMALS new Date() oder performance.now() verwenden, um Delta manuell zu berechnen – ALWAYS THREE.Clock oder renderer.setAnimationLoop nutzen, die stabile Frame-Zeiten liefern.
NIEMALS mixer.clipAction(clip) wiederholt in der Render-Schleife aufrufen – es wird zwar intern gecached, aber der Lookup ist unnötiger Overhead. ALWAYS die zurückgegebene Aktion in einer Variablen speichern.
NIEMALS .play() in jedem Frame aufrufen – einmal aufrufen, um die Wiedergabe zu starten. Ein erneuter Aufruf von .play() bei einer bereits laufenden Aktion hat keine Wirkung, zeigt aber ein Missverständnis an.
ALWAYS .reset() vor .play() aufrufen, wenn eine gestoppte oder beendete Aktion neu gestartet wird – andernfalls kann die Aktion von ihrer letzten Position fortsetzen.
ALWAYS action.clampWhenFinished = true setzen, wenn LoopOnce verwendet wird – andernfalls setzt die Aktion beim Beenden auf den ersten Frame zurück.
AnimationMixer
Der Master-Scheduler, der alle Animationsaktionen für eine einzelne Objekthierarchie steuert.
Konstruktor
const mixer = new THREE.AnimationMixer(rootObject);
rootObject ist das Wurzel-Object3D des animierten Modells (normalerweise gltf.scene).
Eigenschaften
| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
.time | number | 0 | Globale Mixer-Zeit in Sekunden |
.timeScale | number | 1 | Globaler Geschwindigkeitsmultiplikator; 0 pausiert ALLE Aktionen |
Methoden
| Methode | Rückgabe | Beschreibung |
|---|---|---|
.clipAction(clip, root?, blendMode?) | AnimationAction | Gibt eine Aktion für den Clip zurück oder erstellt sie |
.existingAction(clip, root?) | AnimationAction | null | Gibt eine zuvor erstellte Aktion oder null zurück |
.update(delta) | this | Bewegt den Mixer um delta Sekunden vorwärts – MUSS in jedem Frame aufgerufen werden |
.setTime(seconds) | this | Setzt die globale Zeit, aktualisiert alle Aktionen |
.stopAllAction() | this | Deaktiviert alle geplanten Aktionen |
.getRoot() | Object3D | Gibt das Wurzelobjekt des Mixers zurück |
.uncacheAction(clip, root?) | void | Gibt eine gecachte Aktion frei |
.uncacheClip(clip) | void | Gibt Clip-Daten frei |
.uncacheRoot(root) | void | Gibt Wurzelobjekt-Daten frei |
Ereignisse
Hören Sie mit mixer.addEventListener(type, callback):
| Ereignis | Wird ausgelöst, wenn |
|---|---|
'finished' | Aktion abgeschlossen (NUR bei LoopOnce + clampWhenFinished = true) |
'loop' | Aktion eine Schleifeniteration abgeschlossen hat |
Ereignisobjekt-Eigenschaften: { action, loopDelta, type }.
Blend-Modi
Als drittes Argument an mixer.clipAction(clip, root, blendMode) übergeben:
| Konstante | Verhalten |
|---|---|
THREE.NormalAnimationBlendMode | Standard-Überblendung (Standard) |
THREE.AdditiveAnimationBlendMode | Überlagert auf der Basis-Animation |
AnimationAction
Steuert die Wiedergabe eines einzelnen Animationsclips. NIEMALS direkt instanziieren.
Eigenschaften
| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
.blendMode | number | NormalAnimationBlendMode | Überblendungsstrategie |
.clampWhenFinished | boolean | false | Am letzten Frame pausieren, wenn fertig |
.enabled | boolean | true | Deaktivieren ohne Zurücksetzen |
.loop | number | LoopRepeat | Schleifenmodus |
.paused | boolean | false | Wiedergabe einfrieren |
.repetitions | number | Infinity | Schleifenanzahl |
.time | number | 0 | Lokale Zeit in Sekunden |
.timeScale | number | 1 | Geschwindigkeit: 0 pausiert, negativ kehrt um |
.weight | number | 1 | Blend-Einfluss [0, 1] |
.zeroSlopeAtEnd | boolean | true | Glatte Interpolation am Schleifenende |
.zeroSlopeAtStart | boolean | true | Glatte Interpolation am Schleifenstart |
Schleifenmodi
| Konstante | Verhalten |
|---|---|
THREE.LoopOnce | Einmal abspielen, dann anhalten |
THREE.LoopRepeat | Am Anfang jeder Schleife neu starten |
THREE.LoopPingPong | Wechselt vorwärts/rückwärts |
Wiedergabe-Methoden
| Methode | Beschreibung |
|---|---|
.play() | Wiedergabe starten |
.stop() | Anhalten und auf Start zurücksetzen |
.reset() | Zeit, Gewicht und Geschwindigkeit auf Ausgangszustand zurücksetzen |
.startAt(mixerTime) | Start bis zur angegebenen Mixer-Zeit verzögern |
Überblendungs- und Crossfade-Methoden
| Methode | Beschreibung |
|---|---|
.fadeIn(duration) | Gewicht von 0 auf 1 überblenden |
.fadeOut(duration) | Gewicht von 1 auf 0 überblenden |
.crossFadeFrom(fadeOutAction, duration, warp) | Von einer anderen Aktion in diese überblenden |
.crossFadeTo(fadeInAction, duration, warp) | Von dieser Aktion in eine andere überblenden |
.stopFading() | Aktives Überblenden abbrechen |
Geschwindigkeits- und Timing-Methoden
| Methode | Beschreibung |
|---|---|
.halt(duration) | timeScale über die Dauer auf 0 verlangsamen |
.warp(startScale, endScale, duration) | Wiedergabegeschwindigkeit sanft überblenden |
.stopWarping() | Aktives Warp abbrechen |
.setDuration(seconds) | timeScale so anpassen, dass eine Schleife genau seconds dauert |
.setEffectiveTimeScale(scale) | Effektiven Zeitmaßstab setzen |
.setEffectiveWeight(weight) | Effektives Gewicht setzen |
.setLoop(mode, repetitions) | Schleifenmodus und -anzahl setzen |
.syncWith(otherAction) | Zeit mit einer anderen Aktion synchronisieren |
Abfrage-Methoden
| Methode | Rückgabe | Beschreibung |
|---|---|---|
.isRunning() | boolean | true nur, wenn aktiv abgespielt wird |
.isScheduled() | boolean | true, wenn .play() aufgerufen wurde |
.getClip() | AnimationClip | Der zugehörige Clip |
.getMixer() | AnimationMixer | Der besitzende Mixer |
.getRoot() | Object3D | Das Wurzelobjekt |
.getEffectiveTimeScale() | number | Berechneter Zeitmaßstab |
.getEffectiveWeight() | number | Berechnetes Gewicht |
AnimationClip
Ein wiederverwendbarer Satz von Keyframe-Spuren. Normalerweise aus GLTF-Dateien geladen.
Konstruktor
const clip = new THREE.AnimationClip(name, duration, tracks, blendMode);
name– Zeichenketten-Identifikator (GLTF-Clips verwenden Namen aus der Datei)duration– Sekunden;-1für automatische Berechnung aus den Spurentracks– Array vonKeyframeTrack-ObjektenblendMode– optionaler Blend-Mode-Konstante
Wichtige statische Methoden
| Methode | Beschreibung |
|---|---|
AnimationClip.findByName(arrayOrObject, name) | Clip nach Namen suchen |
AnimationClip.CreateFromMorphTargetSequence(name, targets, fps, noLoop) | Clip aus Morph-Zielen erstellen |
AnimationClip.parse(json) | Aus JSON deserialisieren |
KeyframeTrack-Typen
| Spurtyp | Werttyp | Anwendungsfall |
|---|---|---|
VectorKeyframeTrack | Vector3 | Position, Skalierung |
QuaternionKeyframeTrack | Quaternion | Rotation (verwendet Slerp) |
NumberKeyframeTrack | number | Deckkraft, Intensität |
BooleanKeyframeTrack | boolean | Sichtbarkeit umschalten |
ColorKeyframeTrack | Color | Farbanimation |
StringKeyframeTrack | string | Diskrete Zeichenkettenwerte |
Interpolationsmodi
| Konstante | Verhalten |
|---|---|
THREE.InterpolateDiscrete | Sprungfunktion, keine Glättung |
THREE.InterpolateLinear | Lineare Interpolation (Standard) |
THREE.InterpolateSmooth | Kubische Spline-Interpolation |
PropertyBinding-Pfadformat
"meshName.position" // Position animieren
"meshName.material.opacity" // Materialeigenschaft animieren
"meshName.morphTargetInfluences[0]" // Morph-Ziel animieren
"boneName.quaternion" // Knochenrotation animieren
Clock
Konstruktor
const clock = new THREE.Clock(autoStart); // autoStart standardmäßig true
Methoden
| Methode | Rückgabe | Beschreibung |
|---|---|---|
.getDelta() | number | Sekunden seit dem letzten getDelta()-Aufruf |
.getElapsedTime() | number | Gesamtverstrichene Zeit in Sekunden |
.start() | void | Uhr starten |
.stop() | void | Anhalten ohne zurückzusetzen |
Crossfade-Muster (Charakter-Zustandsautomat)
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;
}
ALWAYS .reset() auf der eingehenden Aktion vor dem Crossfade aufrufen.
ALWAYS die Referenz auf die aktuelle Aktion für die nächste Transition speichern.
Additive Animationsüberblendung
const baseAction = mixer.clipAction(baseClip);
const additiveAction = mixer.clipAction(
additiveClip, undefined, THREE.AdditiveAnimationBlendMode
);
baseAction.play();
additiveAction.play();
additiveAction.setEffectiveWeight(0.5);
Additives Blending für überlagerte Effekte verwenden: Atmen, Schadensreaktionen, Zieloffsets.
Morph-Ziel-Animation
// Manuelle Steuerung
mesh.morphTargetInfluences[0] = Math.sin(elapsed) * 0.5 + 0.5;
// Über GLTF-Animationsclip (bevorzugt)
const morphAction = mixer.clipAction(morphClip);
morphAction.play();
Referenzlinks
- references/methods.md – Vollständige API-Signaturen
- references/examples.md – Funktionierende Codebeispiele
- references/anti-patterns.md – Was NICHT zu tun ist
Offizielle Quellen
- https://threejs.org/docs/#api/de/animation/AnimationMixer
- https://threejs.org/docs/#api/de/animation/AnimationAction
- https://threejs.org/docs/#api/de/animation/AnimationClip
- https://threejs.org/docs/#api/de/animation/KeyframeTrack
- https://threejs.org/docs/#api/de/core/Clock
- https://threejs.org/examples/#webgl_animation_skinning_blending