模型

动画系统的“模型”只认 BlockBench 的 .bbmodel。模型里必须包含：

• 骨骼结构（Bones / Outliner）
• 动画（Animations）
• 内嵌纹理（Base64 贴图）

说明：模型只在客户端加载，服务端仅保存配置与绑定关系。

1. 资源路径规则（非常重要）

服务端配置里写 asset，系统会自动映射到客户端资源路径：

• asset: "builtin/default"
  • 实际读取：animation/models/builtin/default.bbmodel
• asset: "npc/knight"
  • 实际读取：animation/models/npc/knight.bbmodel

路径处理规则：

• 会自动剥离 behemiron/、animation/、models/ 前缀。
• 会自动补齐 animation/models/ 目录。
• 会自动补 .bbmodel 扩展名（如果未写）。

客户端资源包目录：

• resourcepacks/Behemiron/animation/models/<你的路径>.bbmodel

2. 官方默认模板

系统内置默认模板：

• builtin/default

这是 唯一官方模板入口。如果你只是想快速起步，直接用它即可。

3. 纹理规则（必须内嵌）

• 纹理必须放在 .bbmodel 里（Base64 内嵌）。
• 不支持外部 png/纹理目录。

这样做是为了统一资源入口，避免路径散落导致加载失败。

4. 动画/骨骼命名约定

动画图（Graph）里的 clip 名称必须 严格匹配 .bbmodel 的动画名称。

推荐的骨骼命名（便于 IK/脚步修正自动识别）：

• root / hips
• foot_l / foot_r
• leg_l / leg_r

如果你的骨骼名不同，请在 vars.ik 中显式填写对应骨骼。

5. 碰撞箱（collider）

模型/衣柜都可以内联 collider：

• width / height 单位：方块
• 写入后会覆盖实体碰撞箱
• 若不设置，则使用原版默认尺寸

6. Wardrobe 与 Model 的关系

• Model：主模型（骨骼 + 动画）。
• Wardrobe：挂载模型（武器/披风/背包）。

Wardrobe 模型同样是 .bbmodel，与主模型无冲突。 通过 attach: bone:xxx 或 attach: locator:xxx 绑定到主骨骼。

7. 最小配置示例

project/runtime-spigot/src/main/resources/animation/models/default.yml

"example:humanoid":
  asset: "builtin/default"
  collider:
    width: 0.6
    height: 1.8

8. 常见问题

• 看不到模型：路径写错 / 资源包没放 / 文件不是 .bbmodel。
• 动画不动：Graph 的 clip 名称与模型动画不匹配。
• 贴图缺失：纹理未内嵌到 .bbmodel。