05. 模型与动画（Blockbench 工作流）

枪的外观由两个文件决定：几何模型（geo_models/gun/<id>_geo.json）和动画（animations/<id>.animation.json），两者都是基岩版（Bedrock）格式。

5.1 为什么要用基岩格式

TaCZ 借用了基岩版的"几何模型 + 动画"体系（和 GeckoLib 生态一致）：

• 模型：format_version: "1.10.0"，由 bones（骨骼）+ 每根骨骼的 cubes（方块）组成；
• 动画：format_version: "1.8.0"，按骨骼名做旋转/位移的关键帧。

Blockbench 从零开始太慢。最省事的路线是：

1. 打开默认枪包的某个 geo 文件（或下载别人的枪包）；
2. 在 Blockbench 里导入它 → 你就得到了骨架 + UV 布局；
3. 改骨骼里的方块（cubes）形状 → 外形变了；
4. 导出覆盖自己的 <id>_geo.json。

5.2 Blockbench 操作清单

步骤	操作
装插件	Blockbench → 文件 → 插件 → 搜索 Bedrock Model（多数版本已内置）
新建/导入	新建时选 Bedrock Model；或 文件 → 导入 → Bedrock 几何模型 导入默认枪的 geo
骨骼（Bone）	每个可动部件一根骨骼：slide（枪机）、magazine（弹匣）、bolt、trigger、muzzle（枪口）
方块（Cube）	挂在骨骼下；用 pivot（轴心）决定旋转中心——弹匣的 pivot 必须在枪身上，不在弹匣上，否则旋转时位置会飞
UV	用 UV 编辑器分配贴图区域，避免两块几何抢同一片 UV（会互相染色）
贴图	文件 → 新建贴图，尺寸用 2 的幂（512/1024），命名 <id>.png
导出	文件 → 导出 → Bedrock 几何模型 → 得到 <id>_geo.json

⚠️ 导航坐标别自己发明：导入默认枪的 geo，看它的骨骼朝向和 pivot 是怎么摆的，照抄结构最稳。

5.3 动画文件长什么样

{
  "format_version": "1.8.0",
  "animations": {
    "animation.m4a1.idle": {
      "loop": true,
      "bones": {
        "root": { "rotation": { "0.0": [0, 0, 0] } }
      }
    },
    "animation.m4a1.shoot": {
      "loop": false,
      "bones": {
        "slide": {
          "position": {
            "0.0": [0, 0, 0],
            "0.05": [0, 0, -1.5],
            "0.15": [0, 0, 0]
          }
        }
      }
    }
  }
}

• 键是"时间点"（秒，字符串），值是 [x, y, z]；
• loop: true 用于待机/行走这类循环动画；
• 位移用 position，旋转用 rotation，缩放用 scale；
• 一根骨骼只能被同一个动画里的一段关键帧驱动。

5.4 常见动画名（硬约定）

TaCZ 按名字去找对应时机的动画，名字对不上 = 动画不播：

动画名（常见）	触发时机
idle / static_idle	手持待机（static_idle 通常是不动状态）
shoot	开火
reload_tactical / reload_empty	战术换弹 / 空仓换弹
mag_standard / mag_ext / mag_ext_2、mag_ext_3	装弹匣动作（普通 / 扩容各档）
draw / put_away	切出 / 收起
inspect	检视武器
walk / sprint / aim	行走 / 冲刺 / 开镜姿态
melee_*	近战（刺刀等）
bolt / slide	拉栓/上膛类动作

⚠️ 不同版本/不同枪种的模板不完全一样。以默认枪包（tacz/tacz_default_gun）里的动画文件为准，把它当字典用。

5.5 新枪"没动画"时的救急写法

如果你还没做动画，先在 display 里写：

"use_default_animation": "rifle"

TaCZ 就会用本体步枪的动画模板兜底——先让枪"有动作"，再逐步替换成自己的动画。

5.6 模型/动画常见坑

现象	原因	解决
模型完全看不到	geo 没导出 / format_version 不是 1.10.0 / 路径错	检查 geo_models/gun/<id>_geo.json 与 display 的 model
模型在手里"错位"	pivot 位置不对	对照默认枪的 pivot 重新摆
枪口位置不对	muzzle 骨骼位置不对	枪口骨骼要放在枪管末端
动画不播	动画名/骨骼名对不上	抄默认枪命名；先用 use_default_animation 验证
动画播了但穿模	关键帧位移过大 / 轴心不对	减小区间、修正 pivot
贴图花/串色	两个 cube 抢同一片 UV	UV 编辑器里重新分配
第三人称看着不对	third_person_animation / transform.scale.thirdperson	单独调这两项
改完没变化	没重进游戏 / 缓存	重进游戏或重启服务端

💡 调试顺序：先"有模型"（哪怕是个方块）→ 再"位置对"（不穿手、枪口对）→ 再"有动画"（默认模板兜底）→ 最后"换成自己的动画"。一次只解决一件事。