Communitygithub.com

Bailipa/EZTor_FULLBLOOD

用於在 Three.js 中播放動畫、動畫狀態交叉淡入淡出或從 GLTF 載入骨骼動畫。避免忘記每幀呼叫 mixer.update(delta)、錯誤的交叉淡入淡出設定或遺漏 Clock 的常見錯誤。涵蓋 AnimationMixer、AnimationClip、AnimationAction、KeyframeTrack、交叉淡入淡出、混合。

EZTor_FULLBLOOD 是什麼?

此技能提供在 Three.js 中處理動畫的完整指南,特別針對 GLTF 模型中的骨骼動畫與動畫狀態機。它強制要求為每個動畫根物件建立唯一的 AnimationMixer,並在任何動畫情境下都必須在渲染迴圈中呼叫 mixer.update(delta)。技能文件中詳細列出了 AnimationMixer、AnimationAction、AnimationClip、KeyframeTrack 與 Clock 的屬性、方法、事件及最佳實踐,並提供可複製的最小化設置程式碼。此外,它涵蓋交叉淡入淡出(crossfade)與附加式混合(additive blending)的標準模式,以及常見錯誤的預防(例如不應在渲染迴圈中重複呼叫 clipAction、應在重播前呼叫 reset 等)。支援的環境包括任何使用 Three.js r152 以上版本的專案(如網頁應用、React Three Fiber 或前端框架),且假設透過 CDN 或 npm 匯入 Three.js。

相容平台✓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 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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

屬性

屬性型別預設值說明
.timenumber0全域混合器時間(秒)
.timeScalenumber1全域速度倍數;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 的播放。絕對不要直接實例化。

屬性

屬性型別預設值說明
.blendModenumberNormalAnimationBlendMode混合策略
.clampWhenFinishedbooleanfalse完成時停留在最後一幀
.enabledbooleantrue停用但不重設
.loopnumberLoopRepeat循環模式
.pausedbooleanfalse凍結播放
.repetitionsnumberInfinity循環次數
.timenumber0本地時間(秒)
.timeScalenumber1速度:0 暫停,負值倒轉
.weightnumber1混合影響程度 [0, 1]
.zeroSlopeAtEndbooleantrue循環結束時平滑插值
.zeroSlopeAtStartbooleantrue循環開始時平滑插值

循環模式

常數行為
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 型別

軌道型別值型別使用案例
VectorKeyframeTrackVector3位置、縮放
QuaternionKeyframeTrackQuaternion旋轉(使用 slerp)
NumberKeyframeTracknumber不透明度、強度
BooleanKeyframeTrackboolean可見性切換
ColorKeyframeTrackColor顏色動畫
StringKeyframeTrackstring離散字串值

插值模式

常數行為
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();

參考連結

官方來源

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.

相關技能