Communitygithub.com

Bailipa/EZTor_FULLBLOOD - Three.js 动画系统

用于在 Three.js 中播放动画、在动画状态之间交叉淡入淡出,或从 GLTF 加载骨骼动画。可防止忘记每帧调用 mixer.update(delta)、交叉淡入淡出设置错误或缺少 Clock 等常见错误。涵盖 AnimationMixer、AnimationClip、AnimationAction、KeyframeTrack、交叉淡入淡出和混合。

EZTor_FULLBLOOD - Three.js 动画系统 是什么?

该技能为使用 Three.js 动画系统的开发者提供了全面、权威的参考指南。它专注于解决动画实现中的常见陷阱,例如必须每帧调用 `mixer.update(delta)`、使用 `Clock` 进行稳定的帧时间管理、以及正确的交叉淡入淡出设置。技能文档详细解释了 `AnimationMixer`、`AnimationAction`、`AnimationClip`、`KeyframeTrack` 和 `Clock` 等核心组件的工作原理和 API。它提供了从最小化动画设置到角色状态机交叉淡入淡出模式、再到叠加动画混合的完整代码示例,并附带了关键警告列表。该技能支持 Three.js 的所有主流渲染循环模式,并且直接适用于包含动画的 GLTF 模型,是任何 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  (播放控制器:播放、暂停、淡入、交叉淡入淡出)
        └── AnimationMixer (主调度器:每个动画根对象一个)
              └── Clock    (为 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)——它在内部缓存,但查找是不必要的开销。始终将返回的动作存储在变量中。

永远不要每帧都调用 .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将混合器前进 delta 秒——必须每帧调用
.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):

常量行为
THREE.NormalAnimationBlendMode标准混合(默认)
THREE.AdditiveAnimationBlendMode在基础动画之上分层叠加

AnimationAction

控制单个动画剪辑的播放。切勿直接实例化。

属性

属性类型默认值描述
.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)从另一个动作交叉淡入淡出到当前动作
.crossFadeTo(fadeInAction, duration, warp)从当前动作交叉淡入淡出到另一个动作
.stopFading()取消任何活跃的淡入淡出

速度和定时方法

方法描述
.halt(duration)在持续时间内将 timeScale 减速到 0
.warp(startScale, endScale, duration)平滑过渡播放速度
.stopWarping()取消任何活跃的速度过渡
.setDuration(seconds)调整 timeScale,使一次循环恰好花费 seconds 秒
.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旋转(使用 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启动 Clock
.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.

相关技能