threejs-impl-animation
クイックリファレンス
アーキテクチャ
AnimationClip (データ: KeyframeTrack オブジェクトの配列)
└── AnimationAction (再生制御: play, pause, fade, crossfade)
└── AnimationMixer (マスタースケジューラ: アニメーションルートオブジェクトごとに1つ)
└── Clock (mixer.update にデルタ時間を提供)
アニメーションルートオブジェクトごとに、必ず 1つだけ 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() を使用してデルタ時間を手動で計算しないでください。必ず THREE.Clock または安定したフレームタイミングを提供する renderer.setAnimationLoop を使用してください。
絶対に レンダーループ内で mixer.clipAction(clip) を繰り返し呼び出さないでください。内部でキャッシュされますが、ルックアップは不要なオーバーヘッドです。必ず 返されたアクションを変数に保存してください。
絶対に .play() を毎フレーム呼び出さないでください。開始時に一度だけ呼び出します。すでに再生中のアクションに .play() を再度呼び出しても効果はありませんが、誤解を示します。
停止または終了したアクションを再開するときは、必ず .play() の前に .reset() を呼び出してください。そうしないと、アクションは最後の位置から再開される可能性があります。
LoopOnce を使用する場合は、必ず action.clampWhenFinished = true を設定してください。そうしないと、アクションは終了時に最初のフレームにリセットされます。
AnimationMixer
単一のオブジェクト階層に対するすべてのアニメーションアクションを駆動するマスタースケジューラです。
コンストラクタ
const mixer = new THREE.AnimationMixer(rootObject);
rootObject はアニメーションモデルのルート Object3D です(通常は gltf.scene)。
プロパティ
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
.time | number | 0 | ミキサーのグローバル時間(秒) |
.timeScale | number | 1 | グローバル速度倍率。0 ですべてのアクションを一時停止 |
メソッド
| メソッド | 戻り値 | 説明 |
|---|---|---|
.clipAction(clip, root?, blendMode?) | AnimationAction | クリップのアクションを返すか作成します |
.existingAction(clip, root?) | AnimationAction | null | 以前に作成されたアクションを返すか、null を返します |
.update(delta) | this | ミキサーをデルタ秒進めます。毎フレーム呼び出す必要があります |
.setTime(seconds) | this | グローバル時間を設定し、すべてのアクションを更新します |
.stopAllAction() | this | スケジュールされたすべてのアクションを非アクティブ化します |
.getRoot() | Object3D | ミキサーのルートオブジェクトを返します |
.uncacheAction(clip, root?) | void | キャッシュされたアクションを解放します |
.uncacheClip(clip) | void | クリップデータを解放します |
.uncacheRoot(root) | void | ルートオブジェクトデータを解放します |
イベント
mixer.addEventListener(type, callback) でリスニングします:
| イベント | 発火タイミング |
|---|---|
'finished' | アクションが完了したとき(LoopOnce + clampWhenFinished = true の場合のみ) |
'loop' | アクションがループの反復を完了したとき |
イベントオブジェクトのプロパティ: { action, loopDelta, type }。
ブレンドモード
mixer.clipAction(clip, root, blendMode) の第3引数として渡します:
| 定数 | 動作 |
|---|---|
THREE.NormalAnimationBlendMode | 標準ブレンディング(デフォルト) |
THREE.AdditiveAnimationBlendMode | 基本アニメーションの上にレイヤーとして重ねる |
AnimationAction
単一のアニメーションクリップの再生を制御します。直接インスタンス化しないでください。
プロパティ
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
.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 | 1回再生して停止 |
THREE.LoopRepeat | ループごとに最初から再開 |
THREE.LoopPingPong | 順方向/逆方向を交互に繰り返す |
再生メソッド
| メソッド | 説明 |
|---|---|
.play() | 再生を開始 |
.stop() | 停止して最初にリセット |
.reset() | 時間、重み、速度を初期状態にリセット |
.startAt(mixerTime) | 指定されたミキサー時間まで開始を遅延 |
フェードおよびクロスフェードメソッド
| メソッド | 説明 |
|---|---|
.fadeIn(duration) | 重みを 0 から 1 にフェードイン |
.fadeOut(duration) | 重みを 1 から 0 にフェードアウト |
.crossFadeFrom(fadeOutAction, duration, warp) | 別のアクションからこれにクロスフェード |
.crossFadeTo(fadeInAction, duration, warp) | このアクションから別のアクションにクロスフェード |
.stopFading() | アクティブなフェードをキャンセル |
速度およびタイミングメソッド
| メソッド | 説明 |
|---|---|
.halt(duration) | timeScale を duration かけて 0 に減速 |
.warp(startScale, endScale, duration) | 再生速度をスムーズに遷移 |
.stopWarping() | アクティブなワープをキャンセル |
.setDuration(seconds) | 1ループがちょうど seconds になるように timeScale を調整 |
.setEffectiveTimeScale(scale) | 実効時間スケールを設定 |
.setEffectiveWeight(weight) | 実効重みを設定 |
.setLoop(mode, repetitions) | ループモードと回数を設定 |
.syncWith(otherAction) | 別のアクションと時間を同期 |
クエリメソッド
| メソッド | 戻り値 | 説明 |
|---|---|---|
.isRunning() | boolean | アクティブに再生中の場合のみ true |
.isScheduled() | boolean | .play() が呼び出された場合 true |
.getClip() | AnimationClip | 関連付けられたクリップ |
.getMixer() | AnimationMixer | 所有するミキサー |
.getRoot() | Object3D | ルートオブジェクト |
.getEffectiveTimeScale() | number | 計算された時間スケール |
.getEffectiveWeight() | number | 計算された重み |
AnimationClip
キーフレームトラックの再利用可能なセットです。通常は GLTF ファイルから読み込まれます。
コンストラクタ
const clip = new THREE.AnimationClip(name, duration, tracks, blendMode);
name-- 文字列識別子(GLTF クリップはファイルからの名前を使用)duration-- 秒。-1でトラックから自動計算tracks--KeyframeTrackオブジェクトの配列blendMode-- オプションのブレンドモード定数
主要な静的メソッド
| メソッド | 説明 |
|---|---|
AnimationClip.findByName(arrayOrObject, name) | 名前でクリップを検索 |
AnimationClip.CreateFromMorphTargetSequence(name, targets, fps, noLoop) | モーフターゲットからクリップを作成 |
AnimationClip.parse(json) | JSON からデシリアライズ |
KeyframeTrack の種類
| トラックタイプ | 値の型 | 使用例 |
|---|---|---|
VectorKeyframeTrack | Vector3 | 位置、スケール |
QuaternionKeyframeTrack | Quaternion | 回転(スラープを使用) |
NumberKeyframeTrack | number | 不透明度、強度 |
BooleanKeyframeTrack | boolean | 可視性の切り替え |
ColorKeyframeTrack | Color | 色のアニメーション |
StringKeyframeTrack | string | 個別の文字列値 |
補間モード
| 定数 | 動作 |
|---|---|
THREE.InterpolateDiscrete | ステップ関数、スムージングなし |
THREE.InterpolateLinear | 線形補間(デフォルト) |
THREE.InterpolateSmooth | 3次スプライン補間 |
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;
}
クロスフェードの前に、必ず 入ってくるアクションに対して .reset() を呼び出してください。
次の遷移のために、必ず 現在のアクション参照を保存してください。
加算アニメーションブレンディング
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 アニメーションクリップ経由(推奨)
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