Communitygithub.com

Bailipa/EZTor_FULLBLOOD - Three.js アニメーション完全実装ガイド

Three.js でのアニメーション再生、アニメーションステート間のクロスフェード、GLTF からのスケルタルアニメーション読み込みに使用します。`mixer.update(delta)` の呼び出し忘れ、クロスフェード設定の誤り、`Clock` の見落としといったよくあるミスを防ぎます。AnimationMixer、AnimationClip、AnimationAction、KeyframeTrack、クロスフェード、ブレンドを網羅します。

EZTor_FULLBLOOD - Three.js アニメーション完全実装ガイド とは?

このスキルは、Three.js におけるアニメーションシステムを完全に網羅した実装ガイドです。AnimationMixer、AnimationClip、AnimationAction、KeyframeTrack、Clock といったコアコンポーネントの正しい使い方と、よくあるアンチパターンを回避するための具体的なコード例を提供します。GLTF アニメーションの再生、クロスフェードによるステートマシンの構築、加算ブレンディング、モーフターゲットアニメーションなど、幅広いユースケースに対応します。スキルは主に Claude Code や Codex などの AI エージェントと JavaScript 開発者を対象としており、Three.js のアニメーション API のリファレンスとしても機能します。公式ドキュメントへのリンクや三段階のリファレンスファイル(メソッド一覧、実装例、アンチパターン集)を含み、実践的な開発を強力に支援します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Bailipa/EZTor_FULLBLOOD/tree/HEAD/.opencode/skills/threejs/threejs-impl/threejs-impl-animation

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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)。

プロパティ

プロパティ型デフォルト説明
.timenumber0ミキサーのグローバル時間(秒)
.timeScalenumber1グローバル速度倍率。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

単一のアニメーションクリップの再生を制御します。直接インスタンス化しないでください。

プロパティ

プロパティ型デフォルト説明
.blendModenumberNormalAnimationBlendModeブレンディング戦略
.clampWhenFinishedbooleanfalse完了時に最後のフレームで一時停止
.enabledbooleantrueリセットせずに無効化
.loopnumberLoopRepeatループモード
.pausedbooleanfalse再生を一時停止
.repetitionsnumberInfinityループ回数
.timenumber0ローカル時間(秒)
.timeScalenumber1速度: 0 で一時停止、負の値で逆再生
.weightnumber1ブレンドの影響度 [0, 1]
.zeroSlopeAtEndbooleantrueループ終了時のスムーズな補間
.zeroSlopeAtStartbooleantrueループ開始時のスムーズな補間

ループモード

定数動作
THREE.LoopOnce1回再生して停止
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 の種類

トラックタイプ値の型使用例
VectorKeyframeTrackVector3位置、スケール
QuaternionKeyframeTrackQuaternion回転(スラープを使用)
NumberKeyframeTracknumber不透明度、強度
BooleanKeyframeTrackboolean可視性の切り替え
ColorKeyframeTrackColor色のアニメーション
StringKeyframeTrackstring個別の文字列値

補間モード

定数動作
THREE.InterpolateDiscreteステップ関数、スムージングなし
THREE.InterpolateLinear線形補間(デフォルト)
THREE.InterpolateSmooth3次スプライン補間

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();

参考リンク

公式ソース

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Bailipa/EZTor_FULLBLOOD

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.

Bailipa/EZTor_FULLBLOOD

A single-frame motion-design composition with looping CSS animations — rotating type ring, animated globe, ticking timer, parallax labels. Renders as a hero video poster you can hand straight to HyperFrames or any keyframe-based exporter. Use when the brief asks for "motion design", "animated hero", "loop", "video poster", "title card", or pairs Open Claude Design with HyperFrames for a kinetic export.

Bailipa/EZTor_FULLBLOOD

Single-page SaaS landing with hero, features, social proof, pricing, and CTA. Respects the active DESIGN.md color/typography/layout tokens. Trigger keywords: "saas landing", "marketing page", "product landing".

Bailipa/EZTor_FULLBLOOD

A pixel / sprite-style animated explainer slide — full-bleed cream stage, bold display year, animated pixel-art mascot (e.g. Hanafuda card, mushroom, or 8-bit console), kinetic Japanese display type, ticking timeline ribbon. Reads like a single frame of an educational motion video — looping CSS keyframes, no JS, ready to be screen-recorded into a vertical video. Use when the brief asks for a "sprite animation", "pixel-art video", "8-bit explainer", "history of X explainer", "kinetic typography history", "Nintendo-style", "精灵图动画", "像素动画", or "复古动画".

Bailipa/EZTor_FULLBLOOD

Short-form video generation skill — 3-10 second clips for product reveals, motion teasers, ambient loops. Defaults to Seedance 2 but works the same with Kling 3 / 4, Veo 3 or Sora 2. Output is one MP4 saved to the project folder. When the workspace also ships an interactive-video / hyperframes skill, prefer composing several short shots into a single timeline rather than one long monolithic clip.

関連スキル