战国 Mod 开发文档

跨模块协作

模块之间怎么说话:能力接口、状态写入、数值覆盖、政体。

模块之间不互相 import。要别人的数据,走能力;要写别人的状态,走申请。

调别人的能力

三步:

# ① 声明要谁的能力
[Capabilities]
Needs = ["mini:territory", "mini:resource-exchange"]

# ② 写明调对方哪些方法
[Interfaces]
"mini:territory" = ["owner", "transfer"]
"mini:resource-exchange" = ["exchange"]

# ③ 自己提供这个能力
[Capabilities]
Provides = ["mini:army"]

调用:

self._call('mini:territory', 'owner', x, y)
self._call('mini:resource-exchange', 'exchange', owner, {GOLD: 10}, {})

self._call 是模块内部调能力的正规入口:它会检查调用方是不是声明过这个能力、 方法在不在 Interfaces 清单里、有没有权限。

依赖顺序

[Mod]
Requires = ["mini:resources"]     # 必须存在:缺了直接拒绝装载
After = ["mini:territory"]         # 结算顺序:我在这之后
Before = []
  • Requires:装配期检查,模块必须在那儿。
  • After / Before:结算期顺序,引擎据此排出稳定的模块顺序。

能力依赖(Capabilities.Needs)是运行期的:对方不在就调不到,但不影响装载。 硬依赖用 Requires,软依赖用 Needs。

可选依赖:

[Capabilities]
Optional = ["example:extra"]

对方在就用,不在就跳过。

写别人的状态

默认不行——每个状态键有唯一的主人。

[State]
Owns = ["accounts"]         # 我写的
Requests = ["territory"]    # 我要写别人的

Requests 是申请,不是占有:引擎仍然保证一次只有一个模块在写,但申请之后 你可以在自己的逻辑里改它。写之前引擎会检查你的状态写入所有权。

数值覆盖

发行版可以给模块的数值打补丁,用来调平衡而不改模块代码:

[Policy]
Overrides = {"infantry_food": 25}

或者用模块自己的数值覆盖表(每个模块自己定,字段名自定)。

政体

政体是换掉一部分模块的机制:政体声明自己禁用哪些能力、覆盖哪些数值。

[Policy]
Rejection = "政体禁用该能力"
Overrides = {"horses_bonus": 0.2}

政体模块可以声明它要替换掉的模块(Aliases 让政体能被不同 ID 找到), 这样同一套模块能装出不同的玩法变体。

常见错误

现象原因
ModError: 未声明的能力self._call 调了没在 Capabilities.Needs 里声明的能力
ModError: 方法未在接口清单中调了对方没在 Interfaces 里声明的方法
装载期 ModError 提到依赖Requires 指向的模块没装
结算顺序不对用 After / Before 声明,不要靠文件名顺序

具体报错见 报错速查。