Communitygithub.com

Army161/OpenMontage

Three.js 動畫系統:關鍵幀動畫、骨骼動畫、變形目標、動畫混合。用於為物體添加動畫、播放 GLTF 動畫、創建程序化運動或混合不同動畫。

OpenMontage 是什麼?

這是一個專注於 Three.js 動畫系統的完整技能指南,涵蓋從基礎關鍵幀到進階動畫混合的全面知識。它詳細介紹了 Three.js 動畫系統的三個核心組件:AnimationClip(儲存關鍵幀數據)、AnimationMixer(在根物件上播放動畫)和 AnimationAction(控制剪輯播放)。技能提供多種 KeyframeTrack 類型(數值、向量、四元數、顏色、布林、字串),並說明如何設定內插模式(線性、平滑、離散)。同時深入探討 GLTF 模型動畫載入、骨骼動畫(含程序化骨骼操控與物件附加)、變形目標(Morph Targets)、動畫混合(包含 Additive Blending)以及多種程序化動畫模式(平滑阻尼、彈簧物理、震盪)。最後提供效能優化建議,如共享剪輯、優化關鍵幀、離螢幕暫停動畫、LOD 技術和限制活躍 Mixer 數量。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Army161/OpenMontage/tree/HEAD/.agents/skills/threejs-animation

在你喜歡的 AI 中提問

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

說明文件

Three.js 動畫系統

快速開始

import * as THREE from "three";

// 簡單的程序化動畫
const clock = new THREE.Clock();

function animate() {
  const delta = clock.getDelta();
  const elapsed = clock.getElapsedTime();

  mesh.rotation.y += delta;
  mesh.position.y = Math.sin(elapsed) * 0.5;

  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();

動畫系統概覽

Three.js 動畫系統包含三個主要組件:

  1. AnimationClip - 儲存關鍵幀資料的容器
  2. AnimationMixer - 在根物件上播放動畫
  3. AnimationAction - 控制剪輯的播放

AnimationClip

儲存關鍵幀動畫資料。

// 建立動畫剪輯
const times = [0, 1, 2]; // 關鍵幀時間(秒)
const values = [0, 1, 0]; // 每個關鍵幀的值

const track = new THREE.NumberKeyframeTrack(
  ".position[y]", // 屬性路徑
  times,
  values,
);

const clip = new THREE.AnimationClip("bounce", 2, [track]);

KeyframeTrack 類型

// 數值軌跡(單一值)
new THREE.NumberKeyframeTrack(".opacity", times, [1, 0]);
new THREE.NumberKeyframeTrack(".material.opacity", times, [1, 0]);

// 向量軌跡(位置、縮放)
new THREE.VectorKeyframeTrack(".position", times, [
  0,
  0,
  0, // t=0
  1,
  2,
  0, // t=1
  0,
  0,
  0, // t=2
]);

// 四元數軌跡(旋轉)
const q1 = new THREE.Quaternion().setFromEuler(new THREE.Euler(0, 0, 0));
const q2 = new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI, 0));
new THREE.QuaternionKeyframeTrack(
  ".quaternion",
  [0, 1],
  [q1.x, q1.y, q1.z, q1.w, q2.x, q2.y, q2.z, q2.w],
);

// 顏色軌跡
new THREE.ColorKeyframeTrack(".material.color", times, [
  1,
  0,
  0, // 紅色
  0,
  1,
  0, // 綠色
  0,
  0,
  1, // 藍色
]);

// 布林軌跡
new THREE.BooleanKeyframeTrack(".visible", [0, 0.5, 1], [true, false, true]);

// 字串軌跡(用於變形目標)
new THREE.StringKeyframeTrack(
  ".morphTargetInfluences[smile]",
  [0, 1],
  ["0", "1"],
);

內插模式

const track = new THREE.VectorKeyframeTrack(".position", times, values);

// 內插
const track = new THREE.VectorKeyframeTrack(".position", times, values);

// 內插模式
track.setInterpolation(THREE.InterpolateLinear); // 預設
track.setInterpolation(THREE.InterpolateSmooth); // 三次樣條
track.setInterpolation(THREE.InterpolateDiscrete); // 階躍函數

AnimationMixer

在物件及其子孫上播放動畫。

const mixer = new THREE.AnimationMixer(model);

// 從剪輯建立動作
const action = mixer.clipAction(clip);
action.play();

// 在動畫循環中更新
function animate() {
  const delta = clock.getDelta();
  mixer.update(delta); // 必要!

  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}

Mixer 事件

mixer.addEventListener("finished", (e) => {
  console.log("動畫完成:", e.action.getClip().name);
});

mixer.addEventListener("loop", (e) => {
  console.log("動畫循環:", e.action.getClip().name);
});

AnimationAction

控制動畫剪輯的播放。

const action = mixer.clipAction(clip);

// 播放控制
action.play();
action.stop();
action.reset();
action.halt(fadeOutDuration);

// 播放狀態
action.isRunning();
action.isScheduled();

// 時間控制
action.time = 0.5; // 當前時間
action.timeScale = 1; // 播放速度(負值 = 倒播)
action.paused = false;

// 權重(用於混合)
action.weight = 1; // 0-1,對最終姿勢的貢獻
action.setEffectiveWeight(1);

// 循環模式
action.loop = THREE.LoopRepeat; // 預設:永遠循環
action.loop = THREE.LoopOnce; // 播放一次後停止
action.loop = THREE.LoopPingPong; // 前後交替播放
action.repetitions = 3; // 循環次數(預設 Infinity)

// 夾止
action.clampWhenFinished = true; // 完成時保持最後一幀

// 混合
action.blendMode = THREE.NormalAnimationBlendMode;
action.blendMode = THREE.AdditiveAnimationBlendMode;

淡入/淡出

// 淡入
action.reset().fadeIn(0.5).play();

// 淡出
action.fadeOut(0.5);

// 動畫交叉淡變
const action1 = mixer.clipAction(clip1);
const action2 = mixer.clipAction(clip2);

action1.play();

// 稍後,交叉淡變到 action2
action1.crossFadeTo(action2, 0.5, true);
action2.play();

載入 GLTF 動畫

最常見的骨骼動畫來源。

import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";

const loader = new GLTFLoader();
loader.load("model.glb", (gltf) => {
  const model = gltf.scene;
  scene.add(model);

  // 建立混合器
  const mixer = new THREE.AnimationMixer(model);

  // 取得所有剪輯
  const clips = gltf.animations;
  console.log(
    "可用動畫:",
    clips.map((c) => c.name),
  );

  // 播放第一個動畫
  if (clips.length > 0) {
    const action = mixer.clipAction(clips[0]);
    action.play();
  }

  // 依名稱播放特定動畫
  const walkClip = THREE.AnimationClip.findByName(clips, "Walk");
  if (walkClip) {
    mixer.clipAction(walkClip).play();
  }

  // 儲存混合器供更新迴圈使用
  window.mixer = mixer;
});

// 動畫循環
function animate() {
  const delta = clock.getDelta();
  if (window.mixer) window.mixer.update(delta);

  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}

骨骼動畫

骨架與骨骼

// 從蒙皮網格存取骨架
const skinnedMesh = model.getObjectByProperty("type", "SkinnedMesh");
const skeleton = skinnedMesh.skeleton;

// 存取骨骼
skeleton.bones.forEach((bone) => {
  console.log(bone.name, bone.position, bone.rotation);
});

// 依名稱尋找特定骨骼
const headBone = skeleton.bones.find((b) => b.name === "Head");
if (headBone) headBone.rotation.y = Math.PI / 4; // 轉頭

// 骨架輔助器
const helper = new THREE.SkeletonHelper(model);
scene.add(helper);

程序化骨骼動畫

function animate() {
  const time = clock.getElapsedTime();

  // 動畫骨骼
  const headBone = skeleton.bones.find((b) => b.name === "Head");
  if (headBone) {
    headBone.rotation.y = Math.sin(time) * 0.3;
  }

  // 如果同時播放剪輯,更新混合器
  mixer.update(clock.getDelta());
}

骨骼附加物件

// 將物件附加到骨骼
const weapon = new THREE.Mesh(weaponGeometry, weaponMaterial);
const handBone = skeleton.bones.find((b) => b.name === "RightHand");
if (handBone) handBone.add(weapon);

// 偏移附加位置
weapon.position.set(0, 0, 0.5);
weapon.rotation.set(0, Math.PI / 2, 0);

變形目標 (Morph Targets)

在不同網格形狀之間混合。

// 變形目標儲存在幾何體中
const geometry = mesh.geometry;
console.log("變形屬性:", Object.keys(geometry.morphAttributes));

// 存取變形目標影響量
mesh.morphTargetInfluences; // 權重陣列
mesh.morphTargetDictionary; // 名稱 -> 索引對應

// 依索引設定變形目標
mesh.morphTargetInfluences[0] = 0.5;

// 依名稱設定
const smileIndex = mesh.morphTargetDictionary["smile"];
mesh.morphTargetInfluences[smileIndex] = 1;

動畫變形目標

// 程序化
function animate() {
  const t = clock.getElapsedTime();
  mesh.morphTargetInfluences[0] = (Math.sin(t) + 1) / 2;
}

// 使用關鍵幀動畫
const track = new THREE.NumberKeyframeTrack(
  ".morphTargetInfluences[smile]",
  [0, 0.5, 1],
  [0, 1, 0],
);
const clip = new THREE.AnimationClip("smile", 1, [track]);
mixer.clipAction(clip).play();

動畫混合

將多個動畫混合在一起。

// 設定動作
const idleAction = mixer.clipAction(idleClip);
const walkAction = mixer.clipAction(walkClip);
const runAction = mixer.clipAction(runClip);

// 以不同權重播放所有動畫
idleAction.play();
walkAction.play();
runAction.play();

// 設定初始權重
idleAction.setEffectiveWeight(1);
walkAction.setEffectiveWeight(0);
runAction.setEffectiveWeight(0);

// 根據速度混合
function updateAnimations(speed) {
  if (speed < 0.1) {
    idleAction.setEffectiveWeight(1);
    walkAction.setEffectiveWeight(0);
    runAction.setEffectiveWeight(0);
  } else if (speed < 5) {
    const t = speed / 5;
    idleAction.setEffectiveWeight(1 - t);
    walkAction.setEffectiveWeight(t);
    runAction.setEffectiveWeight(0);
  } else {
    const t = Math.min((speed - 5) / 5, 1);
    idleAction.setEffectiveWeight(0);
    walkAction.setEffectiveWeight(1 - t);
    runAction.setEffectiveWeight(t);
  }
}

疊加混合 (Additive Blending)

// 基礎姿勢
const baseAction = mixer.clipAction(baseClip);
baseAction.play();

// 疊加層(例如呼吸)
const additiveAction = mixer.clipAction(additiveClip);
additiveAction.blendMode = THREE.AdditiveAnimationBlendMode;
additiveAction.play();

// 將剪輯轉換為疊加模式
THREE.AnimationUtils.makeClipAdditive(additiveClip);

動畫工具函數

import * as THREE from "three";

// 依名稱尋找剪輯
const clip = THREE.AnimationClip.findByName(clips, "Walk");

// 建立子剪輯
const subclip = THREE.AnimationUtils.subclip(clip, "subclip", 0, 30, 30);

// 轉換為疊加
THREE.AnimationUtils.makeClipAdditive(clip);
THREE.AnimationUtils.makeClipAdditive(clip, 0, referenceClip);

// 複製剪輯
const clone = clip.clone();

// 取得剪輯時長
clip.duration;

// 最佳化剪輯(移除冗餘關鍵幀)
clip.optimize();

// 重置剪輯到第一幀
clip.resetDuration();

程序化動畫模式

平滑阻尼

// 平滑跟隨 / 線性內插
const target = new THREE.Vector3();
const current = new THREE.Vector3();
const velocity = new THREE.Vector3();

function smoothDamp(current, target, velocity, smoothTime, deltaTime) {
  const omega = 2 / smoothTime;
  const x = omega * deltaTime;
  const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x);
  const change = current.clone().sub(target);
  const temp = velocity
    .clone()
    .add(change.clone().multiplyScalar(omega))
    .multiplyScalar(deltaTime);
  velocity.sub(temp.clone().multiplyScalar(omega)).multiplyScalar(exp);
  return target.clone().add(change.add(temp).multiplyScalar(exp));
}

function animate() {
  current.copy(smoothDamp(current, target, velocity, 0.3, delta));
  mesh.position.copy(current);
}

彈簧物理

class Spring {
  constructor(stiffness = 100, damping = 10) {
    this.stiffness = stiffness;
    this.damping = damping;
    this.position = 0;
    this.velocity = 0;
    this.target = 0;
  }

  update(dt) {
    const force = -this.stiffness * (this.position - this.target);
    const dampingForce = -this.damping * this.velocity;
    this.velocity += (force + dampingForce) * dt;
    this.position += this.velocity * dt;
    return this.position;
  }
}

const spring = new Spring(100, 10);
spring.target = 1;

function animate() {
  mesh.position.y = spring.update(delta);
}

震盪

function animate() {
  const t = clock.getElapsedTime();

  // 正弦波
  mesh.position.y = Math.sin(t * 2) * 0.5;

  // 彈跳
  mesh.position.y = Math.abs(Math.sin(t * 3)) * 2;

  // 圓周運動
  mesh.position.x = Math.cos(t) * 2;
  mesh.position.z = Math.sin(t) * 2;

  // 8 字形
  mesh.position.x = Math.sin(t) * 2;
  mesh.position.z = Math.sin(t * 2) * 1;
}

效能提示

  1. 共享剪輯:同一個 AnimationClip 可用於多個混合器
  2. 最佳化剪輯:呼叫 clip.optimize() 移除冗餘關鍵幀
  3. 離開畫面時停用:停止對不可見物體的混合器更新
  4. 對動畫使用 LOD:遠處角色使用較簡單的骨架
  5. 限制活躍混合器數量:每次 mixer.update() 都有成本
// 當不可見時暫停動畫
mesh.onBeforeRender = () => {
  action.paused = false;
};

mesh.onAfterRender = () => {
  // 檢查下一幀是否可視
  if (!isInFrustum(mesh)) {
    action.paused = true;
  }
};

// 快取剪輯
const clipCache = new Map();
function getClip(name) {
  if (!clipCache.has(name)) {
    clipCache.set(name, loadClip(name));
  }
  return clipCache.get(name);
}

參考資料

  • threejs-loaders - 載入帶有動畫的 GLTF 模型
  • threejs-fundamentals - Clock 與動畫循環
  • threejs-shaders - 著色器中的頂點動畫

Individual skills in this repo

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

Army161/OpenMontage

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax). Supports two gateways: HeyGen API and fal.ai API.

Army161/OpenMontage

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Army161/OpenMontage

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

Army161/OpenMontage

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

Army161/OpenMontage

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

Army161/OpenMontage

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Army161/OpenMontage

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Army161/OpenMontage

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

Army161/OpenMontage

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

Army161/OpenMontage

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

Army161/OpenMontage

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Army161/OpenMontage

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

Army161/OpenMontage

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

Army161/OpenMontage

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

Army161/OpenMontage

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

Army161/OpenMontage

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

Army161/OpenMontage

Best practices for Remotion - Video creation in React

Army161/OpenMontage

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

Army161/OpenMontage

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

Army161/OpenMontage

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

相關技能