战国 Mod 开发文档

制作发行版

清单怎么写、挂点怎么排、客户端工厂怎么接模型。

发行版是装配清单,不写业务逻辑。

两层文件

mods/native/               模块目录(实现)
  mod.toml                 发行版清单
  resources/               一个模块一个目录
  army/
  ...
mods.toml                  仓库根的入口:装哪个发行版
# mods.toml
[Load]
Packages = ["mods/native"]
# mods/native/mod.toml
[Distribution]
Id = "native"
Version = "4.9.0"
Members = ["mods/resources.toml", "mods/territory.toml", "mods/army.toml", ...]
RequiredState = ["resources", "territory", "army", ...]
ActorCollection = "nation_actors"
ActionGate = {Capability = "native:government", Method = "can_act"}
PlayerClock = {Capability = "native:government", Method = "period"}
PlayerEvents = "news"
PlayerState = ["government", "land", "army", ...]

[Distribution.Tools]
Entry = "mods.native.tools:build"

[Distribution.Session]
Entry = "mods.native.session:NativeSession"

字段全表见 发行版清单。

挂点

挂点是发行版定义的结算时机:

[[Hooks]]
Id = "cycle.start"

[[Hooks]]
Id = "cycle.end"

模块的结算阶段挂到这些点上:

def stages(self):
    return (Stage('mini:buildings.produce', self._produce, hook='cycle.start',
                  provides=('production.done',)),)

引擎按挂点顺序、模块顺序跑阶段。挂点顺序由发行版声明的先后决定。

客户端工厂

发行版决定「谁来替玩家行动」:

[Distribution.ClientFactories.llm]
Entry = "clients.llm:LLMClient"
Configuration = "clients.config:normalize"

[Distribution.ClientFactories.mini]
Entry = "mods.examples.minigame.client:MinigameClient"
  • Entry:客户端类,按 模块:类名 解析。
  • Configuration:这个客户端的配置归一化函数(模型客户端要 api_key、model 等字段)。
  • 客户端类要接受宿主的工厂契约:__init__(self, cfg, record=None, services=None)。

配置里 "client": "llm" 的国家就交给模型客户端,"client": "mini" 交给简易策略。

同一个发行版可以同时接模型和不接模型——发行版与模型客户端之间没有耦合, 耦合在「工具面与事实形状」这份契约上,见 模型面向契约。

场景与剧本

[Distribution.Scenarios]
Entry = "scenarios.eight_nations:build"

剧本声明开局国家、地图尺寸、种子,以及可选的胜负条件。

管理 API

发行版可以挂管理 API(发消息、暂停、改配置):

[Distribution.Session]
Entry = "mods.native.session:NativeSession"
Observer = {Capability = "native:intelligence", Records = "to_save", Announce = "announce", Send = "send"}

Observer 声明观察者能力:记哪份记录、怎么公告、怎么送信。

发布一个发行版

  1. 目录结构:模块目录 + mod.toml。
  2. 根目录加一个入口 mods.<名字>.toml。
  3. 配置里 "mods": "mods.<名字>.toml"。
  4. 写测试:装配成功、跑几回合、存档往返、模型客户端能驱动。
  5. 在 docs/site/content/附录/01-示例索引.md 里登记。

换掉整套规则要改什么

只要两样:发行版清单(Members 换成另一批模块声明)与实现(新模块的代码)。 引擎、模型客户端、观察者、存档格式都不动。