运行时流程与调试

动画系统是服务端绑定 + 客户端执行的架构：

1. 服务端做什么

解析 animation/models/graphs/wardrobe/bindings/*.yml
根据 selector 绑定实体
将绑定写入 CPDC
RootMotion 由服务端权威执行

2. 客户端做什么

读取 CPDC（model / graph / wardrobe / vars / flags）
从资源包加载 .bbmodel
在客户端执行 Molang 条件与动画混合
叠加 IK / 脚步修正

3. 关键运行数据

CPDC 里主要包含：

model：模型 id
graph：动画图 id
wardrobe：衣柜 id（可选）
vars：变量（Molang v.）
flags：标记（开关/RootMotion 参数）
collider：碰撞箱 width/height

4. 调试清单（从高频到低频）

模型加载失败

asset 路径写错
.bbmodel 未放在 resourcepacks/Behemiron/animation/models/

动画不动

Graph 中 clip 名称与 .bbmodel 动画不一致
状态机没有进入目标 state（条件不满足）

RootMotion 无效

flags.applyRootMotion 未开启
clip 未配置 length
rootMotion 模式为 disabled

IK/脚步修正没反应

footIk 未开启
脚骨骼名不对（请显式填写 leftFoot/rightFoot）

5. 热重载说明

客户端会监听 resourcepacks/Behemiron/animation/models/ 下的 .bbmodel 文件变动并自动清理缓存。
服务端配置变更后，请确保触发重载或重启，让绑定重新下发。

6. FAQ / 排障表（生产环境常见问题）

现象	可能原因	解决方式
模型不显示	`asset` 路径错误 / 资源包未放到 `resourcepacks/Behemiron/animation/models/`	校验路径、确认 `.bbmodel` 存在
动画不播放	Graph `clip` 名称与 `.bbmodel` 动画不一致	统一动画命名
转场不触发	Molang 条件为 false / 变量未写入	检查 `vars/flags` 是否下发
RootMotion 无位移	`applyRootMotion=false` / clip 缺少 `length` / `rootMotion` 关闭	打开 `applyRootMotion` 并补齐 `length`
位移过快/过慢	`velocity` / `scaleVar` / `speedVar` 配置错误	根据实际速度调参
脚步不贴地	脚骨骼名不匹配 / `footIk` 未开启	配置 `leftFoot/rightFoot`
脚抖动	IK 强度太高 / 淡入淡出太短	降低 `lockStrength`，调大 `lockFadeIn/Out`
远距离卡顿	RootMotion/IK 未做 LOD	配置 `rootMotionLodNear/Mid/Far` 与 IK `lod`
大量实体无动画	selector 未命中	检查 `bindings` 规则与 `priority`