战国 Mod 开发文档

报错速查

装载期与运行期的常见错误,按症状查原因。

装载期:发行版装不起来

报错原因怎么办
重复的 Mod ID两个模块用了同一个 Mod.Id改 ID,或用命名空间前缀
同时加载多个发行版一次装了两个发行版一个进程只装一个发行版
玩家状态必须声明唯一的只读工具PlayerState 里有不存在或不是只读的工具核对工具名与 read_only
玩家事件必须引用只读工具PlayerEvents 指的工具不存在或不是只读同上
ReadOnlyPanel must reference a registered read-only toolReadOnlyPanel 里的面板没注册用已注册的只读工具名
行动门声明缺少公共能力或方法ActionGate 写的能力/方法不存在核对 Capability 与 Method
玩家时钟必须引用公共能力和方法PlayerClock 写错核对能力与方法名
发行版须声明 PlayerClock 或实现 clock()发行版没声明时钟加 PlayerClock 或实现 clock()
发行版须实现定时登场策略或采用 GridSession发行版缺登场策略用 GridSession 或自己实现
Session.Observer 必须引用公共能力观察者能力写错核对 Observer 里的能力
Session.Observer.Records 必须返回包含 events / messages 的对象观察者的 to_save 返回值形状不对返回 {'events': [...], 'messages': [...]}
场景必须是本发行版声明的场景 id 不在发行版声明里在发行版 Scenarios 里声明
模块工具不能占用玩家 API 保留名称工具名撞了 player_state / player_rules / player_events / memory_search改工具名
对象接口不能调用私有方法通过能力调了 _ 开头的方法暴露成公开方法

装载期:模块装不起来

报错原因
依赖模块缺失Requires 指向的模块没装
能力名冲突两个模块 Provides 同一个能力名
状态键重复拥有两个模块 Owns 同一个键
工具名重复两个工具同名
未声明的能力self._call 调了没在 Capabilities.Needs 声明的能力
方法未在接口清单中调了对方没在 Interfaces 声明的方法

运行期:模型或玩家提交动作

报错原因怎么办
该国当前不能行动:已亡国,或不在行动阶段该回合已经交过动作每个回合一次行动
仅行动阶段可以提交动作不在行动阶段检查回合流程
该动作不属于行动者的作用域工具对该行动者不可见作用域或权限声明问题
该工具不属于行动者的作用域同上检查 PlayerState / 作用域声明
未知内容键值:…模型传了没注册的内容 id注册内容或加 register_aliases
键值冲突,请指定命名空间短键在多个内容里重名用带命名空间的 id
工具参数须为对象 / 参数必须是一个对象参数不是 dict检查工具函数签名
query 只能查已注册的只读动作拿只读工具去 submit 了只读用 query,动作用 submit
topic 必须是字符串player_rules 传了非字符串传字符串
内容键值须为字符串内容 id 不是字符串检查 content_definitions

存档

报错原因怎么办
存档 Mod 依赖/版本/工具契约与当前加载环境不相同,拒绝加载存档与当前发行版不匹配用匹配的版本,或走迁移脚本
存档 Mod 状态清单与当前环境不相同模块的状态键变了升版本并迁移
Unsupported session format存档格式号不认识检查 zhanguo.session/5
Save only at an action boundary在回合中间存档在行动边界存
Scenario differs from saved scenario存档的场景与当前配置不同用同样的场景配置

排查顺序

  1. 先看报错类型:装载期 → 声明问题;运行期 → 作用域/参数/内容问题;存档 → 版本问题。
  2. 再看是不是声明没写全:八成的问题出在 mod.toml 与实现不一致。
  3. 最小复现:用 Runtime.load('你的模块目录') 单独装它,别拉上整个发行版。
  4. 还是不行:跑 python3 scripts/api_doc.py --check 看参考页与代码是否同步, 再对照 API 参考 核字段。