09. 调试与常见坑

枪包不会"编译报错"，只会在游戏里表现异常。所以排查靠顺序 + 二分法，而不是猜。

9.1 排查顺序（照这个来，不要乱试）

① 包加载了吗       → gunpack.meta.json 是否存在、namespace 是否全小写
② 目录层级对吗     → data/<ns>/index/guns/…  与  data/<ns>/data/guns/…（两层 data！）
③ 物品栏能搜到吗   → 能搜到 = index 生效；搜不到 = 上面两步有问题
④ 拿在手里长什么样 → 白模/紫黑 = display 的 model / texture 路径错
⑤ 能动吗           → 没动画 = animations / use_default_animation
⑥ 能开枪吗         → 能开枪但无伤害 = data 里的 ammo / bullet 配置
⑦ 有声音吗         → 没声音 = tacz_sounds 路径或格式
⑧ 多人一致吗       → 单人好、多人坏 = 服务端没装 / 版本不一致

二分法：同时改了很多东西？把枪包减到只剩"一把枪 + 最小文件"，能跑通后再一项项加回来。

9.2 日志怎么看

位置	看什么
logs/latest.log	搜 tacz、搜 gunpack、搜你枪的 id；加载/解析错误会打印在这里
客户端日志	.minecraft/logs/latest.log（单人问题的第一现场）
服务端日志	服务器目录 logs/latest.log

日志里没有报错但枪也不出现，通常是"文件根本没被扫到"——先怀疑目录层级和 zip 结构。

9.3 常见坑总表

现象	原因	解决
整个包不加载	namespace 有大写 / gunpack.meta.json 缺失或格式错	全小写；JSON 不能有注释和尾逗号
枪搜不到	目录少了一层 data（写成 data/<ns>/guns/）	正确是 data/<ns>/index/guns/ 与 data/<ns>/data/guns/
枪搜不到	index 里 data/display 指向的名字与实际文件名不一致	逐字符对照（m4a1_data ↔ m4a1_data.json）
白模 / 紫黑	texture 路径错 / 图片不存在 / 尺寸不是 2 的幂	对照 textures/gun/uv/<id>.png
模型不显示	geo 没导出、format_version 不对、model 路径错	用默认枪的 geo 对比
枪口/弹匣位置怪	骨骼 pivot 不对	照抄默认包骨骼结构
动画不播	动画名/骨骼名不符	先写 use_default_animation 兜底，再逐个替换
音效不响	用了 mp3/wav；display 里带了 .ogg	用 Ogg Vorbis；引用不带扩展名
能开枪没伤害	data 的 ammo id 与弹药索引不一致 / bullet.damage 为 0	对照弹药 id 与字段
换弹卡住	reload.feed/cooldown 数值不合理（如 0 或极大）	对照默认枪数值量级
名字显示成键名	缺 lang 或键不一致	补 lang/zh_cn.json
单人正常多人失效	服务端没放枪包 / 两边版本不同	服务端 tacz/ 同步同一份
装不上配件	没写 tacz_tags 标签	补 allow_attachments/<枪>.json
改完没变化	没重进游戏 / 服务端没重启 / 玩家缓存	重进/重启/清缓存
zip 装了没反应	zip 里多套了一层文件夹	根目录直接放 data/、assets/、meta

9.4 工具

工具	用途
默认枪包 tacz/tacz_default_gun	最好的"格式字典"，任何字段不确定就去看它
第三方 gunpack 校验器	离线检查目录结构、引用路径、命名与数值范围，给出修正建议（改完先跑一遍再进游戏）
VS Code	JSON 高亮/校验，能提前发现尾逗号、漏括号
Blockbench	模型/动画的可视化编辑
ffmpeg	音效转 Ogg：ffmpeg -i a.wav -c:a libvorbis -ac 1 -ar 44100 out.ogg
批量改数值脚本	见 10. 联动与数值平衡

9.5 心态提示

枪包调试 90% 的时间花在"路径"和"名字"上，不是"参数是否合理"。 遇到问题时先问自己三句：目录层级对不对？引用路径对不对？名字大小写对不对？