三层结构
引擎、模块、发行版各管什么,依赖方向为什么是单向的。
| 层 | 是什么 | 在哪 |
|---|---|---|
| 引擎 | 机制:挂点顺序、依赖解析、状态所有权、能力裁决、工具通道、存档 | engine/ |
| 模块 | 一件事:它拥有的状态、它的工具、它的结算阶段、它的规则正文 | mods/ 下各目录 |
| 发行版 | 清单:装哪些模块、挂点按什么顺序排、给模型看什么 | mods.toml、mods/native/mod.toml |
依赖方向单一
引擎 ← 模块 ← 发行版。
模块不导入发行版,也不互相导入;模块之间只通过声明的能力对话。 这带来两个直接后果:
- 模块可以被单独装载、单独测试,不需要先把整个发行版跑起来。
- 引擎里不出现「建筑」「补给」「市场」这类游戏词汇——它们全在模块里。 换掉一整套规则不需要改引擎。
引擎管什么
引擎只管机制,不懂玩法:
- 装载:读
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 则是另一套完全不同的九模块规则。
换掉一整套规则要改什么
只要两样:
- 发行版清单(
Members换成另一批模块声明) - 实现(新模块的代码)
引擎、模型客户端、观察者、存档格式都不动。mods/examples/minigame 就是这么来的: 它从零写了九个模块,装配成一个完整可玩的发行版,引擎一行没改。