在 Godot 4.5.2 里验收 AI 角色动画
用两个 Meshy GLB 在 Godot 重放待机与二连击,测量根骨位移,并对照抵消骨盆平移前后的低位脚趾骨轨迹。

在 Godot 4.5.2 里播放二连击时,角色的场景原点始终在原地,骨架根骨 Hips 却在结束时离起点约 1.06 米。我们把整个角色往相反方向平移,抵消骨盆的水平移动。左脚趾骨在第一个低位区间的首尾位移从 3.15 厘米增到 55.83 厘米。把动画接进角色控制器前,可以用两个原始 GLB 在干净工程里重放,先判断位移落在哪一层,以及去除位移后脚下发生了什么。
先说结论
- 4.03 秒的待机和 2.87 秒的二连击都导入了 24 根骨骼,唯一的骨架根骨是
Hips。Godot 读到的动画轨道分别为 25 条和 24 条。 - 两个动作的场景原点全程为零。二连击的
Hips水平距离起点最远 109.39 厘米。待机最远 2.25 厘米,结束时几乎回到骨盆起点。 - 抵消骨盆水平位移后,二连击早段左脚趾骨的首尾位移由 3.15 厘米增至 55.83 厘米。右脚趾骨另一段低位区间从 3.95 厘米增至 44.08 厘米。
- 复现包包含两个原始资产、无窗口采样脚本、Godot 原生截图脚本和计算结果,可先重放本文样本,再按自己的骨骼层级调整采样。
把动作编号和返回文件放在一起
复现工程里的两个文件出自一次 Meshy Multi-Animation 实测。送入的是重拓扑后的银色机器人,原始送测网格有 21,833 个三角面。调用的模型接口接收了动作 92 和动作 0,分别对应 Double Combo Attack 二连击、Idle 待机。该次请求使用 meshyrig 骨架模板、关闭手指骨、角色高度参数为 1.7 米,结算为 0.44 美元。这篇复用了当时返回的文件,没有为 Godot 对比重新生成。二连击文件为 7,542,940 字节,待机文件为 7,573,976 字节。两个原始文件的 SHA-256 都在包内。
导入后再核对动作名。本文的 92 号文件提供 Armature|Double_Combo_Attack|baselayer,0 号文件提供 Armature|Idle|baselayer。脚本排除可能出现的内置 RESET 动画,再要求每个样本只剩一条动作。项目如果把多个动作装入同一个动画库,就保存一份明确的动作编号和导入名称映射。这样更新 GLB 时可以发现意外改名,也可以确认运行时播放的确是策划验收过的那条动画。
样本用 Godot 的 GLTFDocument 直接读取两个文件,测量和截图共用同一加载函数。正式项目可以按导入面板设置、重定向配置和继承场景来组织资源。要用于验收时,在最终实例化的节点和动画库上也跑一次,记录是否使用了额外的缩放、方向转换或骨架重映射。
先用固定机位看五个相位
截图脚本暂停播放器,把采样点设在动作的 0%、25%、50%、75% 和 100%。场景用正交机位、间距 20 厘米的地面网格,青色标左侧脚趾骨,橙色标右侧。图中的原生帧来自 Apple 芯片 Mac 上的 Godot Compatibility 渲染器。标记会透过模型绘制以便辨认,因此图上的圆点可能出现在鞋面之前,实际骨骼位置仍以采样坐标为准。

五帧取自原始待机 GLB。手臂和身体姿势有变化,根骨在水平面的移动保持在起点附近。
初次检查时,把角色和地面网格留在同一个固定画面。跟随角色的机位会弱化世界坐标下的移动。对照动画修改前后的表现也要用同一组时间点,这样不会因为两帧姿势相近就把它们当成同一帧。下图二连击的时间显示四舍五入到 0.00、0.72、1.43、2.15、2.87 秒。下排在整个模型这一层应用反向水平平移。原始的四肢姿势、朝向和竖直轨迹仍用于渲染。看最后一帧,两个角色相对网格的位置已经明显分开。

上排来自原始 GLB。下排在相同动作和时间点上,仅给角色整体施加与 Hips 水平位移相反的平移。
分开测量场景原点和根骨
脚本把动画播放器设成手动更新,用 seek(time, true) 应用指定时间的姿势,再调用 force_update_all_bone_transforms() 更新骨架。它同时记录角色节点的全局位置和选定关节的位置。Godot 的 get_bone_global_pose() 返回骨架空间中的姿势。乘上骨架节点的全局变换,再取位置,才能和场景原点或网格放在同一个坐标系比较。如果项目把角色实例放进有旋转、位移或缩放的父节点,验收报告仍应明确采用的是哪套坐标。Skeleton3D 文档已将这个强制更新方法标为弃用,仅供内部使用。本探针把它限定在 4.5.2 复现环境。正式项目应在引擎应用当前动画并完成该帧的骨架更新后读取关节位置。AnimationPlayer 文档 · Skeleton3D 文档
| Godot 实测项 | 待机 | 二连击 |
|---|---|---|
| 导入时长 | 4.033 秒 | 2.867 秒 |
| 骨骼数 / 动画轨道数 | 24 / 25 | 24 / 24 |
| 姿势采样数 | 243 | 173 |
| 场景原点 XZ 首尾距离 | 0 厘米 | 0 厘米 |
| Hips XZ 首尾距离 | 约 0 厘米 | 105.85 厘米 |
| Hips XZ 离起点的最远距离 | 2.25 厘米 | 109.39 厘米 |
| Hips XZ 累计轨迹长度 | 9.26 厘米 | 118.93 厘米 |
采样节奏是每秒 60 次,再取导入动作真正的终点。如果最后一个名义采样点离终点不到约一微秒,脚本用终点替换它,防止重复采到几乎同一个姿势。累计路径把相邻采样点的距离相加。首尾距离只取第一个点和最后一个点。待机的骨盆首尾几乎重合,过程里仍然走出了 9.26 厘米的累计轨迹。如果想测出循环动画的过程变化,就同时关注离起点的最远距离和累计路径。

左侧使用离动作起点的 XZ 距离。右侧比较二连击中两个低位区间的首尾水平位移。
用脚趾骨低位区间找值得检查的片段
先记录每只脚趾骨在整条动作中的最低采样 Y 值。如果一串相邻采样都在该骨自身最低值上方 2 厘米以内,并且区间长度至少 0.15 秒,探针就记录这个区间。两个阈值都在脚本里。脚趾骨是骨架点,可能高于鞋底。绘制用的网格也单独设有高度。低位区间是定位疑似支撑片段的办法,便于回看鞋底、脚踝和膝盖。想判断是否触地,还要把碰撞体和实际物理场景一起测。
二连击左脚趾骨的第一段低位时间从 0.00 秒到 1.28 秒,含 78 个采样点。原动作的首尾距离是 3.15 厘米,累计轨迹是 16.91 厘米。抵消骨盆 XZ 之后,首尾距离变为 55.83 厘米,累计达到 62.88 厘米。右脚趾骨在 1.35 至 2.22 秒这段的首尾距离从 3.95 厘米增至 44.08 厘米。这是右脚三段低位区间中持续最久的一段。待机也有脚趾骨在区间内往返的情况,单看首尾距离容易略过。决定某条动作的使用方式前,可以直接在报告里看完整区间。
如果这条二连击要驱动一次游戏内突进,先把原始画面和专用动画根轨迹一起看,再用实际控制器测试它能走多远、碰墙时怎么处理。若控制器提供位移,就选一条按原地动作制作的参考,使用预期速度回放并观察脚下是否稳定。源骨架的平移和角色控制器的移动可能叠到一起。把转向、斜坡、过渡动画和碰撞分别加回场景,可以判断哪一步改变了最终的位置与节奏。
下载并复现
1. 校验原始文件
安装 Godot 4.5.2 官方版本,用 GODOT_BIN 指向该可执行文件的绝对路径。新建一个可写目录后执行:
curl -fL https://blog.sandbase.ai/examples/godot-character-motion/godot-character-motion-probe.zip -o godot-probe.zip
unzip -q godot-probe.zip -d godot-probe
cd godot-probe
LC_ALL=C shasum -a 256 -c SHA256SUMS
"$GODOT_BIN" --version本文跑出的版本字符串是 4.5.2.stable.official.6ce3de25a。ZIP 大小约 12.73 MB。
2. 在 Godot 里逐帧采样
"$GODOT_BIN" --headless --path "$PWD" --script res://measure.gd这会写出 engine-motion.json,里面有引擎版本、动作名、轨道、每个时间点和所采关节的坐标。Godot 命令行文档列出了脚本执行和无窗口模式参数。
3. 生成汇总并与参考数据比较
python3 summarize-motion.py
diff -u expected/motion-summary.json motion-summary.json参考值来自 Apple 芯片上的 macOS 官方构建。跨平台若看到微小浮点差异,可以先比较本文表格中的舍入距离和精确样本数。
4. 在桌面会话中导出 Godot 原生帧
"$GODOT_BIN" --path "$PWD" --rendering-method gl_compatibility \
--resolution 900x704 --script res://render.gd命令写出 15 张 PNG 和记录时间点的 native-frame-index.json。想把另一份动作放入同一实验时,先保留分辨率、观察机位和地面网格,再调整角色位置以保证比较尺度一致。
5. 用 PNG 和采样结果重新生成比较图
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python make-evidence.py这一步使用 Python 3.11 或更新版本,输出到 evidence/。截图来自上一步,折线和区间数据来自 Godot 的采样文件。
常见问题
场景节点在原地,动作就能当作原地动画吗?
再看骨架根和实际渲染。本文的场景节点始终在同一坐标,二连击的 Hips 却前移超过一米。团队的原地动作验收条件最好写清对应节点或骨骼、坐标系和容许距离。
能把示例中的反向平移拿去锁脚吗?
它适合观察骨盆位移对画面的影响。示例让所有关节和顶点一起水平平移,原本接近支撑位置的脚趾骨可以滑得更远。需要锁脚时,按真实地面、碰撞和角色控制方式实现足部固定约束,并检查转换到下一条动画时是否跳变。
导入有 24 根骨骼,能直接重定向到另一角色吗?
这个数字来自当前样本。另一角色的兼容性还取决于层级、绑定朝向、角色比例和参与动画的关节。先验证映射后的静止姿势,再用一次真实的待机到攻击过渡看手脚有没有偏转、穿插或漂移。
觉得有用?分享给更多人