战国 Mod 开发文档

三层结构

引擎、模块、发行版各管什么,依赖方向为什么是单向的。

层是什么在哪
引擎机制:挂点顺序、依赖解析、状态所有权、能力裁决、工具通道、存档engine/
模块一件事:它拥有的状态、它的工具、它的结算阶段、它的规则正文mods/ 下各目录
发行版清单:装哪些模块、挂点按什么顺序排、给模型看什么mods.toml、mods/native/mod.toml

依赖方向单一

引擎 ← 模块 ← 发行版。

模块不导入发行版,也不互相导入;模块之间只通过声明的能力对话。 这带来两个直接后果:

  1. 模块可以被单独装载、单独测试,不需要先把整个发行版跑起来。
  2. 引擎里不出现「建筑」「补给」「市场」这类游戏词汇——它们全在模块里。 换掉一整套规则不需要改引擎。

引擎管什么

引擎只管机制,不懂玩法:

  • 装载:读 mod.toml,解析依赖,算出模块顺序,检查声明与实现是否一致。
  • 裁决:谁能写哪个状态、谁能调用哪个能力的方法、某个工具对某个行动者是否可用。
  • 调度:按挂点顺序跑结算阶段,阶段之间用 context 传数据。
  • 通道:把工具变成模型能调用的 JSON Schema,把回执变成可读的文本。
  • 存档:按发行版声明严格核对,依赖清单不一致就拒绝装载。

引擎的接口清单见 引擎 API。

模块管什么

一个模块负责一个领域,并且显式声明它和别人的关系:

  • 它拥有哪些状态键(只有它能写)
  • 它提供哪些能力(别人可以调它的方法)
  • 它需要哪些能力、可以调对方哪些方法
  • 它提供哪些工具给模型、哪些事实每回合自动发给模型
  • 它在哪些挂点上跑结算阶段
  • 它的规则正文是什么(模型用 player_rules 查)

模块内部怎么组织是自由的:一个模块可以只有一个文件(minigame 的九个模块写在同一个 game.py 里), 也可以拆成领域目录(native 的做法)。

发行版管什么

发行版是装配清单,不是代码:

[Load]
Packages = ["mods/native"]        # 入口文件:装哪些模块目录
[Distribution]                      # 清单文件:装好了怎么玩
Id = "native"
Version = "4.9.0"
Members = ["mods/resources.toml", "mods/army.toml", ...]
RequiredState = ["resources", "territory", ...]
PlayerState = ["government", "land", "army", ...]

发行版决定:

  • 装哪些模块、按什么顺序
  • 结算挂点有哪些、按什么顺序
  • 每回合自动发给模型哪些事实
  • 提供哪些客户端(模型客户端、规则客户端、自定义客户端)
  • 场景、剧本、管理 API 挂在哪

同一套模块可以装出不同的游戏。 mods.native.toml 与 mods.experimental.toml 装的是同一批 native 模块, 区别只在挂点与客户端;mods.minigame.toml 则是另一套完全不同的九模块规则。

换掉一整套规则要改什么

只要两样:

  1. 发行版清单(Members 换成另一批模块声明)
  2. 实现(新模块的代码)

引擎、模型客户端、观察者、存档格式都不动。mods/examples/minigame 就是这么来的: 它从零写了九个模块,装配成一个完整可玩的发行版,引擎一行没改。