调试与验证

本课目标

完成标志：你能区分语法、引用、加载顺序和玩法错误，并把失败缩小到一份最小 MOD 与第一条有效日志

验证分成四层

层级	证明什么	工具
JSON 语法	括号、逗号、引号能解析	编辑器、项目格式工具
数据加载	类型、字段、ID 和引用有效	`--check-mods`、`--jsonverify`
游戏行为	对象可生成、配方可做、机制按预期运行	测试世界、调试菜单
兼容与存档	与依赖组合、保存重载和升级正常	最小组合、干净安装、旧存档副本

只通过第一层不代表 MOD 可用；只“启动没报错”也不代表内容实际可达。

1. 使用隔离用户目录

不要让测试 MOD、设置和存档污染日常游戏。CCB 当前命令行支持 --userdir：

./cataclysm-tiles --userdir /tmp/ccb-mod-test

Windows 可把路径换成单独的测试文件夹。首次启动后，把 MOD 放入该用户目录的 mods/。这样可以明确游戏正在扫描哪份 MOD，并能随时删除整个测试环境重来。

2. 检查指定 MOD

CCB 当前 src/main.cpp 提供：

./cataclysm-tiles --check-mods survivor_toolkit

有多个目标时在后面继续列出 MOD ID。若 MOD 位于独立用户目录：

./cataclysm-tiles \
  --userdir /tmp/ccb-mod-test \
  --check-mods survivor_toolkit

--check-mods 的参数是 MOD_INFO.id，不是显示名或目录名。依赖 ID 必须可发现；成功退出后仍要进行游戏内测试。

检查整个 CCB 数据可使用：

./cataclysm-tiles --jsonverify

全量验证更慢，适合准备内置 MOD PR 或修改会影响大量内容的 JSON API。命令含义以当前程序 --help、src/main.cpp 和 doc/cataclysm-tiles.6 为准。

3. 从第一条有效错误开始

加载器常在一个根错误后报告大量连锁错误。按顺序排查：

找最早提到当前 MOD 文件和行号的错误；
检查该对象前一行的逗号、引号与括号；
确认 type 和字段名在当前版本存在；
确认引用 ID 已由核心、依赖或当前 MOD 在正确阶段加载；
修复一处后重新运行，不要同时猜改十处。

常见类别：

错误表现	可能原因
找不到 MOD	路径错误、文件名错误、重复 ID、扫描了另一用户目录
unknown type / member	旧教程字段、拼写或该对象类型不读取此字段
invalid id	被引用对象不存在、依赖缺失或加载顺序错误
duplicate definition	ID 冲突、同一文件被重复打包、复制了核心对象
dependency cycle	MOD 互相依赖，无法形成加载顺序
世界能建但内容找不到	没有加入生成/配方/场景入口，或解锁条件未满足

4. 查看日志

保留当前测试产生的 debug.log；崩溃时同时保留 crash.log。报告问题时附：

CCB 版本或提交；
MOD 版本与 modinfo.json；
完整依赖列表；
执行命令；
第一条相关错误及其前后上下文；
能复现的最小文件。

不要只截最后一个弹窗。日志中的前一条错误通常更接近根因。

5. 游戏内测试

建立只启用核心 dda 与目标 MOD 的世界，然后：

用调试菜单生成新增物品、怪物或 NPC；
检查显示名、描述、数值和交互；
用正常玩法验证生成、解锁、制作、掉落或任务路径；
保存并重载；
离开区域使对象卸载，再返回测试加载期行为；
对时间相关机制推进时间；
记录预期、实际结果和重复次数。

测试怪物修改时重新生成怪物；已经保存的实例可能保留旧状态。地图生成应在未生成区域测试，旧地图块不会自动重建。

6. 最小化问题

出现只在大量 MOD 组合中发生的问题时：

备份世界；
新建测试世界确认不是存档损坏；
只保留核心与目标 MOD；
逐个恢复依赖或用二分法缩小组合；
把触发内容缩成最小 JSON；
判断是依赖声明、mod_interactions、ID 冲突还是核心 API 回归。

不要直接从重要存档删除大型内容 MOD来“试试看”；缺少对象可能使存档进一步损坏。

7. 提交前验证记录

### Test environment
- CCB: <完整版本或提交>
- Platform: <系统与 Tiles/Terminal>
- Mods: dda, survivor_toolkit
- User dir: clean temporary directory

### Automated
- `./cataclysm-tiles --check-mods survivor_toolkit`: passed

### Manual
- New world created
- Item spawned and inspected
- Recipe completed with both component alternatives
- Save/reload passed

下一课：依赖与兼容

验证分成四层​

1. 使用隔离用户目录​

2. 检查指定 MOD​

3. 从第一条有效错误开始​

4. 查看日志​

5. 游戏内测试​

6. 最小化问题​

7. 提交前验证记录​