重载、调试、性能与发布

重载与调试

可选模块参数警告

挂饰物理、激光等已接入统一解析的字符串数值和布尔字段，在缺失或留空时保留各自默认值。非法数值（包括 NaN、Infinity）、整数溢出和非法布尔值会使用默认值，并产生 Invalid module setting 警告；同一字段、类型的后续警告会被抑制，单次运行最多记录 128 类。

看到警告应修正对应字段，不要靠默认值掩盖错误。各字段自己的有效范围仍由对应功能处理。这一规则不适用于所有配置字段；换弹等必填机制参数仍可能直接报错。

定义热重载

拥有 2 级权限时执行：

/gwo reload

它重新扫描外部枪械和弹药定义，并在聊天栏报告数量或错误。它不会重建已经上传到 GPU 的模型与材质缓存，因此不适合验证镜片透明度、贴图、模型或动画二进制的修改。

资源重载

模型、贴图、声音、动画、transparent_nodes 和其他渲染材质变更后使用 Minecraft 的资源重载（通常为 F3 + T）。涉及动画库、复杂模型缓存或渲染状态时，最可靠的验证方式仍是完全退出并重启游戏。

给予测试物品

/gwo give firearm "example:example_rifle"
/gwo give melee "example:example_knife"
/gwo give ammo "example:example_ammo"

升级到分类枪械物品 ID 的版本前，请先备份世界并处理旧 gwo:gun 物品；新版本没有自动存档迁移。内容包的枪械定义 ID 保持不变，命令仍使用定义 ID，详见枪械分类与迁移。

ZIP 打包与分发

开发和调试阶段建议直接使用普通文件夹。需要分发时，将内容包压缩为 ZIP；ZIP 根目录必须直接包含 pack.mcmeta、逻辑目录和 assets，不能额外套一层同名文件夹。

同一个内容包不要同时以文件夹和 ZIP 两种形式放在 gwo 目录，否则会产生重复 ID，后加载者可能覆盖前加载者，导致调试结果混乱。

性能制作规范

建议遵守以下性能制作规范：

• 删除永远不可见的内部面和重复面。
• 合理合并同材质网格，但保留需要独立透明、隐藏或动画控制的节点。
• 一套枪及默认部件尽量共享图集，减少材质和纹理切换。
• 不要给完全静止的骨骼烘焙每帧相同关键帧。
• 不要让每个动作携带几十个无用静态骨骼通道。
• 透明网格只保留真实需要透明的部分。
• 贴图分辨率按可见尺寸选择，不是所有小配件都需要 4096×4096。
• 控制骨骼数量、透明层数量、枪口粒子数量和长时间烟雾数量。
• 第三人称和物品图标不应运行完整第一人称动画图。

常见故障对照

现象	首要检查
内容包完全不出现	放置目录、ZIP 根层级、JSON 语法、日志中的扫描错误
只有机匣，默认配件都不见	modules、default_installed、配件路径与 anchor_node
配件反向或大小不一致	GLB 参考空间、对象变换、挂点轴向、gltf_scale
配件不跟动画	挂点通道没导出、挂点属于错误 Armature、动画库缺节点
模型黑紫	资源路径错误、缺基础贴图、缺物品模型 JSON
光影下部件消失	透明节点错误、镜片与镜框合并、贴图 sidecar/材质不完整
非光影没有自发光	emissive 路径、Alpha 遮罩、emissive_strength
手臂与 Blender 不一致	绑定姿态、独立手臂参考空间、重复父变换、错误层混合
动画结束闪回 idle	尾帧与基准姿态不一致、keep_last_frame/交接层、时长错误
换弹声音不同步	更换动画后未更新 animation_commands 帧
换弹完成但弹量没变	reload_phases.commit 与逻辑提交时机错误
管式上弹第一发不显示	reload_loop 的插入/提交事件和手中弹模型可见性
子弹/弹托数量不对	j_ammo_*、bullet_additive/shell_additive_* 与容量
抛壳位置错误	tag_brass 不存在、轴向错误或第三人称使用相机姿态
激光不跟枪	配件安装点与配件内部 tag_laser 混淆
镜内准心变形	准心节点、投影/倍率模式、焦平面和镜片模板配置错误
动画加载警告跨 skin	多骨架导出所有权错误，不能靠运行时兜底修复
修改后看不到变化	重复内容包覆盖、未 /gwo reload、未资源重载或缓存需重启

发布前完整验收清单

文件与加载

• 根目录有正确 pack.mcmeta。
• 所有 JSON 能被严格解析。
• 没有重复 id。
• 文件夹和 ZIP 只保留一种。
• /gwo reload 无报错。

枪械逻辑

• 单发、连发、点射按配置工作。
• 单人和局域网射速一致。
• 弹量、备弹、弹种与服务器同步。
• 普通换弹、空仓换弹和打断规则正确。
• 霰弹枪逐发装填和 rechamber 正确。
• 栓动枪切枪回来后能恢复待完成的 rechamber。
• 生存/创造模式规则正确。

动画

• draw、holster、idle、aim、fire、reload、inspect、sprint 全部检查。
• 瞄准动作使用正确 aim 变体。
• 左右手在动画全程稳定贴合武器。
• 动画首尾不闪回、不停留错误尾帧。
• 第 0 帧事件正常。
• 动画时长、事件帧、提交帧全部同步。

模型和配件

• 所有默认部件挂点正确。
• 改装界面预览和第一人称一致。
• 第三人称、背负、掉落物和展示框位置正确。
• 装/卸瞄具后机瞄可见性正确。
• 激光、挂饰和物理碰撞正确。
• 弹匣内子弹、膛内弹和弹托随弹量变化。

渲染

• 不开光影时基础色、法线材质、自发光和透明件正确。
• 开光影时模型不消失、玻璃不黑、镜内世界正确。
• 普通瞄具、增倍镜、双用瞄具和可变倍率逐一检查。
• Weapon Sway 在普通瞄具和倍镜下都正确。
• 枪口火焰、烟雾、尾迹、激光和抛壳来自正确节点。

声音和 UI

• 枪声不重复叠加或被意外截断。
• 换弹、检视、拉机柄、近战、空击声音逐帧匹配。
• 物理声效模组能处理枪声和动作声。
• 物品图标、HUD 图标、显示名和分类正确。
• 不同分辨率下改装界面文字仍清晰且不被模型遮挡。

当前命令参数按普通字符串读取，资源 ID（含命名空间）请放在双引号中。只复制命令本身，不要复制 Markdown 代码围栏。