战国 Mod 开发文档

开发流程总览

从「想加个东西」到「能上线」要走完的九步。

加一个东西,完整走九步。每一步都有对应的参考页。

1. 先判断:这是模块还是发行版

  • 只是加一条规则、加一个资源、加一种建筑 → 写模块。
  • 要换掉整套规则(另一套资源、另一个时代、另一个胜利条件) → 写发行版。
  • 只是改模型的提示词、上下文策略 → 改发行版的语言包或客户端,不动模块。

判据:你的改动能不能独立成一个目录 + 一个 mod.toml?能,就是模块。

2. 划边界:这个模块拥有什么

先写下三行字,再动手写代码:

这个模块拥有:<状态键>
这个模块提供:<能力名>.<方法名>
这个模块需要:<别人的能力>.<方法名>

这三行直接对应 mod.toml 的 [State]、[Capabilities]、[Interfaces]。 先定接口,再写实现——否则写到一半会发现要改别人的状态,或者能力名和别人的撞了。

命名规矩:

  • 能力名一律 模块ID:能力名,模块 ID 用自己的命名空间(example:hello)。
  • 状态键短而具体(accounts、territory),不要跟别人重名。
  • 方法名用动词短语(exchange、owner、transfer)。

3. 写声明:mod.toml

[Mod]
Id = "example:hello"
Version = "1.0.0"
Entry = "mods.examples.hello.mod:HelloMod"
Requires = []                 # 必须存在的依赖模块
After = []                    # 结算顺序:我在这些模块之后
Before = []

[State]
Owns = ["hello"]              # 只有我能写
Requests = []                 # 我要写别人的状态时在这里申请

[Capabilities]
Provides = ["example:hello"]
Needs = []                    # 我要用的能力
Optional = []                 # 可选依赖

[Interfaces]
"example:other" = ["method"]  # 我要调对方哪些方法

字段全表见 模块声明。

4. 写实现:GameMod 子类

最少要实现 mixins;常用的是 initialize_world、objects、tools、stages、rule_sections。 方法清单见 引擎 API。

5. 暴露给模型:工具与事实

模型只看得见工具和事实。这一步决定模型能不能玩你的内容。

  • 动作 → 一个 Tool,read_only=False,写清 description。
  • 只读查询 → 一个 Tool,read_only=True;写进发行版的 PlayerState 就会每回合自动发给模型。
  • 规则的完整正文 → rule_sections,模型用 player_rules 按主题查。
  • 结束回合 → end_turn 必须收 summary 并在回执里回 text。

细节见 暴露给模型。

6. 让模型看得懂

模型的判断力取决于它看到的东西写没写清楚:

  • 工具的 description 写清参数、约束、失败原因——模型只看得见它。
  • 资源、建筑、兵种注册成内容,模型就能用短键值和中文名两种写法。
  • 规则正文分主题写,关键词要覆盖模型可能搜的词。

细节见 规则与手册。

7. 跨模块协作

需要别人的数据时,走能力接口,不要直接 import 别的模块:

  • 在 Capabilities.Needs 声明要谁的能力。
  • 在 Interfaces 写明调对方哪些方法。
  • 在 owner / needs / optional 里声明依赖,引擎替你解析顺序。

需要写别人的状态时,在 [State].Requests 申请,写入由引擎裁决。

细节见 跨模块协作。

8. 存档

模块要能存进档、读回档:

  • save_state 返回可序列化的状态。
  • load_state 读回。
  • 版本变了要改 Mod.Version;发行版装载时严格核对,依赖不一致直接拒绝装载,不做静默迁移。

细节见 状态与存档。

9. 验收

  • 离线回归全绿:.venv/bin/python -m unittest discover -s tests
  • 自己的模块有测试:至少覆盖声明、行为、存档、错误路径、跨模块五项。
  • 跑一遍真实对局,看模型是不是真的用上了你的内容。

细节见 测试与验收。

一张表看完

步骤产出参考
1 判断模块 or 发行版三层结构
2 划边界三行接口定义跨模块协作
3 写声明mod.toml模块声明
4 写实现GameMod 子类引擎 API
5 暴露给模型工具、事实暴露给模型
6 让模型看得懂描述、内容、规则规则与手册
7 跨模块能力接口跨模块协作
8 存档save_state / load_state状态与存档
9 验收测试与对局测试与验收