Web 图形与 3D / 系统课时

检验 AnimationClip 轨道映射

检验 AnimationClip 轨道映射

模型成功加载、gltf.animations 也有数据,但骨骼或表情仍然不动,常见原因是轨道没有找到正确节点、目标属性不匹配,或剪辑根本没有进入更新循环。这里用一份真实 GLB 打印剪辑及轨道,再对照场景树完成播放验收。

学习目标

  • 读取剪辑名称、时长、轨道路径、关键帧数量和属性维度。
  • 区分位移、旋转、缩放及形变权重的轨道映射。
  • 按目标节点、绑定属性、播放更新的顺序定位“有动作但不动”。

轨道如何找到模型属性

gltf.animations 是 AnimationClip 数组;一个 Clip 含多条 KeyframeTrack,每条轨道用 name 标识待修改的节点与属性。播放时,AnimationMixer 根据轨道路径在所选根对象内查找目标,由 PropertyBinding 将关键帧值写入属性。仅加载 Clip 不会自动播放。

AnimationClip、轨道路径与骨骼及形变目标属性的映射

例如 Hips.position 指向名为 Hips 的节点的位置;UpperArm.quaternion 指向骨骼旋转。Face.morphTargetInfluences 指向网格的一组形变权重,而 Face.morphTargetInfluences[Smile] 可指向其中一个具名权重。名称必须以实际导入的轨道为准,不能用 Blender 中看到的名称直接猜测。

用真实 GLB 打印轨道

在 Node.js 与 Vite 可运行的环境中,依次执行 npm create vite@latest clip-audit -- --template vanilla、cd clip-audit、npm install、npm install three。将含动画的 GLB 放到 public/models/character.glb,再把 src/main.js 替换为以下完整入口,运行 npm run dev 并查看浏览器控制台。

js
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

document.body.style.margin = '0';
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf7f9fa);
const camera = new THREE.PerspectiveCamera(
  50, window.innerWidth / window.innerHeight, 0.1, 1000
);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
scene.add(new THREE.HemisphereLight(0xffffff, 0x556677, 2.5));

let mixer = null;
const clock = new THREE.Clock();
const loader = new GLTFLoader();

loader.load('/models/character.glb', (gltf) => {
  scene.add(gltf.scene);
  const clips = gltf.animations;
  console.log(`clips=${clips.length}`);

  // 分别检查轨道格式和名称能否在当前场景根节点下找到对象
  for (const clip of clips) {
    console.log(
      `clip=${clip.name} duration=${clip.duration.toFixed(2)}s ` +
      `tracks=${clip.tracks.length} valid=${clip.validate()}`
    );
    for (const track of clip.tracks) {
      const path = THREE.PropertyBinding.parseTrackName(track.name);
      const node = THREE.PropertyBinding.findNode(gltf.scene, path.nodeName);
      const nodeName = node ? (node.name || '(root)') : '(missing)';
      console.log(
        `  path=${track.name} node=${nodeName} property=${path.propertyName} ` +
        `keys=${track.times.length} size=${track.getValueSize()}`
      );
    }
  }

  // 只播放一个剪辑,避免多段动作同时混合掩盖问题
  if (clips.length > 0) {
    mixer = new THREE.AnimationMixer(gltf.scene);
    mixer.clipAction(clips[0]).play();
  }

  const bounds = new THREE.Box3().setFromObject(gltf.scene);
  if (!bounds.isEmpty()) {
    const center = bounds.getCenter(new THREE.Vector3());
    const span = Math.max(bounds.getSize(new THREE.Vector3()).length(), 0.5);
    camera.position.copy(center).add(
      new THREE.Vector3(span, span * 0.6, span * 1.6)
    );
    camera.lookAt(center);
  }
}, undefined, (error) => console.error('GLB 加载失败', error));

renderer.setAnimationLoop(() => {
  const delta = clock.getDelta();
  if (mixer) mixer.update(delta);
  renderer.render(scene, camera);
});

window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

预期结果:浏览器显示加载的模型并尝试循环播放第一个剪辑;控制台按以下格式输出,尖括号占位符由 GLB 实际数据决定。

text
clips=<CLIP_COUNT>
clip=<CLIP_NAME> duration=<SECONDS>s tracks=<TRACK_COUNT> valid=<true|false>
  path=<TRACK_PATH> node=<NODE_NAME_OR_MISSING> property=<PROPERTY> keys=<KEY_COUNT> size=<VALUE_SIZE>

clip.validate() 只检查关键帧数据的基本有效性,不验证场景节点是否匹配;node=(missing) 是需要追查的信号,node 存在也不等于目标属性一定可绑定。若出现加载错误,先确认开发服务器上的 /models/character.glb 可访问,并检查文件是否使用尚未配置解码器的压缩扩展。

对照四类轨道与属性

glTF 动画通道 Three.js 轨道属性 正常目标与检查点
translation .position 节点的 Vector3,通常每帧 3 个分量
rotation .quaternion 骨骼或节点的四元数,通常每帧 4 个分量
scale .scale 节点的 Vector3,通常每帧 3 个分量
weights .morphTargetInfluences Mesh 的权重数组;核对数组长度及 morphTargetDictionary

形变轨道可能针对整个权重数组,也可能使用 [Smile] 或 [0] 这样的索引;不能假定每条形变轨道只控制一个目标。还要看 track.times 是否有关键帧、track.values 是否真正变化:首尾相同的循环动画仍可能在中间帧运动。插值或切线数据的打包方式也会影响 values 的排列,不要仅凭数组长度推断形变目标数。

排查存在剪辑却没有视觉变化

  1. 若 clips=0,回到 Blender 检查 Action 是否实际导出到 GLB;代码端无法播放不存在的 Clip。
  2. 若轨道显示 node=(missing),核对 track.name、导入后实际的 Object3D.name 和 Mixer 根节点。不要随意改动节点名,也不要把 Mixer 绑定到不包含目标骨骼的局部网格。
  3. 若节点存在却不动,检查对应属性是否可绑定:.quaternion 应落在可旋转节点;形变需确认 Mesh.morphTargetInfluences 存在且索引或名字能在 morphTargetDictionary 中找到。留意控制台的 PropertyBinding 警告。
  4. 若路径和数据均正常,确认调用过 mixer.clipAction(clip).play()、每帧执行 mixer.update(delta),且 Action 未暂停、有效权重与时间缩放不为 0。
  5. 若属性确实变化但画面静止,检查骨骼是否正确蒙皮、形变目标是否包含有效顶点位移,以及相机是否看得到受影响部位。

验收时逐段只播放一个 Clip:记录剪辑名、时长、至少一条目标轨道、目标节点是否存在及实际画面变化。必要时将 clips[0] 换为目标剪辑在数组中的索引重试;不要把“控制台能列出轨道”当成动画已经正确绑定的证明。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

检验 AnimationClip 轨道映射

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通