threejs-impl-animation
快速參考
架構
AnimationClip (資料: KeyframeTrack 物件陣列)
└── AnimationAction (播放控制器: play, pause, fade, crossfade)
└── AnimationMixer (主排程器: 每個動畫根物件一個)
└── Clock (提供 delta 時間給 mixer.update)
永遠為每個動畫根物件建立剛好一個 AnimationMixer。
永遠在渲染迴圈中的每一幀呼叫 mixer.update(delta)。
絕對不要直接實例化 AnimationAction——永遠使用 mixer.clipAction(clip)。
必要匯入
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
最小動畫設定
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);
// 播放 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);
關鍵警告
絕對不要忘記在渲染迴圈中呼叫 mixer.update(delta)——否則動畫將不會播放。
絕對不要使用 new Date() 或 performance.now() 手動計算 delta——永遠使用 THREE.Clock 或 renderer.setAnimationLoop,後者可提供穩定的幀時間。
絕對不要在渲染迴圈中重複呼叫 mixer.clipAction(clip)——它雖然內部會快取,但每次查詢都是不必要的開銷。永遠將傳回的 action 儲存在變數中。
絕對不要每幀都呼叫 .play()——只呼叫一次以開始播放。對已在播放的 action 再次呼叫 .play() 雖然沒有作用,但這表示理解有誤。
永遠在重新啟動已停止或結束的 action 時,在 .play() 之前呼叫 .reset(),否則 action 可能會從最後的位置繼續播放。
永遠在使用 LoopOnce 時設定 action.clampWhenFinished = true——否則 action 會在結束時重置到第一幀。
AnimationMixer
為單一物件層級結構驅動所有動畫 action 的主排程器。
建構子
const mixer = new THREE.AnimationMixer(rootObject);
rootObject 是動畫模型的根 Object3D(通常是 gltf.scene)。
屬性
| 屬性 | 型別 | 預設值 | 說明 |
|---|---|---|---|
.time | number | 0 | 全域混合器時間(秒) |
.timeScale | number | 1 | 全域速度倍數;0 會暫停所有 action |
方法
| 方法 | 回傳值 | 說明 |
|---|---|---|
.clipAction(clip, root?, blendMode?) | AnimationAction | 傳回或為該 clip 建立一個 action |
.existingAction(clip, root?) | AnimationAction | null | 傳回先前建立的 action 或 null |
.update(delta) | this | 將混合器推進 delta 秒——必須每幀呼叫 |
.setTime(seconds) | this | 設定全域時間,更新所有 action |
.stopAllAction() | this | 停用所有已排程的 action |
.getRoot() | Object3D | 傳回混合器的根物件 |
.uncacheAction(clip, root?) | void | 釋放快取的 action |
.uncacheClip(clip) | void | 釋放 clip 資料 |
.uncacheRoot(root) | void | 釋放根物件資料 |
事件
透過 mixer.addEventListener(type, callback) 監聽:
| 事件 | 觸發時機 |
|---|---|
'finished' | Action 完成(僅在 LoopOnce + clampWhenFinished = true 時) |
'loop' | Action 完成一次循環迭代 |
事件物件屬性:{ action, loopDelta, type }。
混合模式
作為第三個引數傳遞給 mixer.clipAction(clip, root, blendMode):
| 常數 | 行為 |
|---|---|
THREE.NormalAnimationBlendMode | 標準混合(預設) |
THREE.AdditiveAnimationBlendMode | 層疊在基底動畫之上 |
AnimationAction
控制單一動畫 clip 的播放。絕對不要直接實例化。
屬性
| 屬性 | 型別 | 預設值 | 說明 |
|---|---|---|---|
.blendMode | number | NormalAnimationBlendMode | 混合策略 |
.clampWhenFinished | boolean | false | 完成時停留在最後一幀 |
.enabled | boolean | true | 停用但不重設 |
.loop | number | LoopRepeat | 循環模式 |
.paused | boolean | false | 凍結播放 |
.repetitions | number | Infinity | 循環次數 |
.time | number | 0 | 本地時間(秒) |
.timeScale | number | 1 | 速度:0 暫停,負值倒轉 |
.weight | number | 1 | 混合影響程度 [0, 1] |
.zeroSlopeAtEnd | boolean | true | 循環結束時平滑插值 |
.zeroSlopeAtStart | boolean | true | 循環開始時平滑插值 |
循環模式
| 常數 | 行為 |
|---|---|
THREE.LoopOnce | 播放一次,停止 |
THREE.LoopRepeat | 每次循環從頭開始 |
THREE.LoopPingPong | 交替正向/反向 |
播放方法
| 方法 | 說明 |
|---|---|
.play() | 開始播放 |
.stop() | 停止並重設到開頭 |
.reset() | 將時間、權重、速度重設為初始狀態 |
.startAt(mixerTime) | 延遲開始直到指定的混合器時間 |
淡入淡出與交叉淡入淡出方法
| 方法 | 說明 |
|---|---|
.fadeIn(duration) | 將權重從 0 淡入到 1 |
.fadeOut(duration) | 將權重從 1 淡出到 0 |
.crossFadeFrom(fadeOutAction, duration, warp) | 從另一個 action 交叉淡入到這個 action |
.crossFadeTo(fadeInAction, duration, warp) | 從這個 action 交叉淡出到另一個 action |
.stopFading() | 取消任何進行中的淡化 |
速度與時間方法
| 方法 | 說明 |
|---|---|
.halt(duration) | 在 duration 時間內將 timeScale 減速至 0 |
.warp(startScale, endScale, duration) | 平順過渡播放速度 |
.stopWarping() | 取消任何進行中的 warp |
.setDuration(seconds) | 調整 timeScale 使一次循環剛好花費 seconds 秒 |
.setEffectiveTimeScale(scale) | 設定有效時間比例 |
.setEffectiveWeight(weight) | 設定有效權重 |
.setLoop(mode, repetitions) | 設定循環模式與次數 |
.syncWith(otherAction) | 與另一個 action 同步時間 |
查詢方法
| 方法 | 回傳值 | 說明 |
|---|---|---|
.isRunning() | boolean | 僅在積極播放時回傳 true |
.isScheduled() | boolean | 若已呼叫 .play() 則回傳 true |
.getClip() | AnimationClip | 關聯的 clip |
.getMixer() | AnimationMixer | 所屬的混合器 |
.getRoot() | Object3D | 根物件 |
.getEffectiveTimeScale() | number | 計算出的時間比例 |
.getEffectiveWeight() | number | 計算出的權重 |
AnimationClip
一組可重複使用的關鍵幀軌道。通常從 GLTF 檔案載入。
建構子
const clip = new THREE.AnimationClip(name, duration, tracks, blendMode);
name-- 字串識別碼(GLTF clip 使用檔案中的名稱)duration-- 秒數;設為-1可自動從 tracks 計算tracks--KeyframeTrack物件的陣列blendMode-- 可選的混合模式常數
主要靜態方法
| 方法 | 說明 |
|---|---|
AnimationClip.findByName(arrayOrObject, name) | 依名稱查詢 clip |
AnimationClip.CreateFromMorphTargetSequence(name, targets, fps, noLoop) | 從變形目標建立 clip |
AnimationClip.parse(json) | 從 JSON 反序列化 |
KeyframeTrack 型別
| 軌道型別 | 值型別 | 使用案例 |
|---|---|---|
VectorKeyframeTrack | Vector3 | 位置、縮放 |
QuaternionKeyframeTrack | Quaternion | 旋轉(使用 slerp) |
NumberKeyframeTrack | number | 不透明度、強度 |
BooleanKeyframeTrack | boolean | 可見性切換 |
ColorKeyframeTrack | Color | 顏色動畫 |
StringKeyframeTrack | string | 離散字串值 |
插值模式
| 常數 | 行為 |
|---|---|
THREE.InterpolateDiscrete | 階梯函數,無平滑 |
THREE.InterpolateLinear | 線性插值(預設) |
THREE.InterpolateSmooth | 三次樣條插值 |
PropertyBinding 路徑格式
"meshName.position" // 動畫位置
"meshName.material.opacity" // 動畫材質屬性
"meshName.morphTargetInfluences[0]" // 動畫變形目標
"boneName.quaternion" // 動畫骨骼旋轉
Clock
建構子
const clock = new THREE.Clock(autoStart); // autoStart 預設為 true
方法
| 方法 | 回傳值 | 說明 |
|---|---|---|
.getDelta() | number | 自上次呼叫 getDelta() 以來的秒數 |
.getElapsedTime() | number | 總共經過的秒數 |
.start() | void | 啟動時鐘 |
.stop() | void | 停止但不重設 |
交叉淡入淡出模式(角色狀態機)
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;
}
永遠在交叉淡入淡出前對傳入的 action 呼叫 .reset()。
永遠儲存目前 action 的參考以供下一次轉換使用。
附加式動畫混合
const baseAction = mixer.clipAction(baseClip);
const additiveAction = mixer.clipAction(
additiveClip, undefined, THREE.AdditiveAnimationBlendMode
);
baseAction.play();
additiveAction.play();
additiveAction.setEffectiveWeight(0.5);
使用附加式混合來實現分層效果:呼吸、受傷反應、瞄準偏移。
變形目標動畫
// 手動控制
mesh.morphTargetInfluences[0] = Math.sin(elapsed) * 0.5 + 0.5;
// 透過 GLTF 動畫 clip(建議)
const morphAction = mixer.clipAction(morphClip);
morphAction.play();
參考連結
- references/methods.md -- 完整的 API 簽章
- references/examples.md -- 可運作的程式碼範例
- references/anti-patterns.md -- 不該做的事項
官方來源
- 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