战国 Mod 开发文档

配方速查

加资源、加阶段、加兵种、替换内容——四种最常见改动的骨架。

四种最常见的改动,各自的骨架。完整版在仓库的 docs/Mod开发指南.md。

配方一:加一种资源

from engine.resource import Resource

class Iron(Resource):
    TYPE_ID = 'example:iron'
    NAME_KEY = 'example.iron'
    ROLES = ('resource',)
    UNIT = '重量'

class ResourcesMod(GameMod):
    def content_definitions(self):
        return {cls.TYPE_ID: cls for cls in (Gold, Food, Wood, Iron)}

    def objects(self, world):
        return {'example:resources': world.accounts}

要动的地方:

  1. 资源类 + content_definitions 注册(注册过才有短键和显示名)。
  2. 资源的产出与消耗:谁产出、谁扣、产多少。
  3. 相关的成本参数(numbers)。
  4. 规则正文:告诉模型这个资源干什么用。
  5. 工具描述:涉及这个资源的动作,描述里要点名。

配方二:插入一个新阶段

from engine.runtime import Stage

def stages(self):
    return (Stage('example:market.clear', self._clear,
                  hook='cycle.end', requires=('production.done',),
                  after=('mini:buildings.produce',),
                  provides=('market.cleared',)),
            )

def _clear(self, context):
    ...   # 改世界
    return {'cleared': 3}

阶段挂点上,顺序由发行版声明的挂点顺序与模块顺序决定; requires / after / before 用来表达阶段之间的先后。

配方三:加一种兵种

class ArchersMod(GameMod):
    def content_definitions(self):
        return {'example:archers': {...}}

    def tools(self):
        return (Tool('recruit_archers', self._recruit, description='…'),)

要动的地方:

  1. 兵种内容注册(短键、显示名、别名)。
  2. 招募工具:位置、材料、耗时。
  3. 战斗结算:兵种参与伤害计算的方式。
  4. 规则正文:兵种属性与克制关系。
  5. 移动/撤退规则:新兵种能不能跟旧兵种同格。

配方四:替换已有内容

在 native 上做减法有三条路:

做法怎么做适合
发行版换成员Members 换成另一批模块声明换掉整个领域
数值覆盖发行版或政体的 Overrides调平衡
能力拿掉模块不提供某个能力砍掉一个系统

三条路都不改引擎,也不改被替换的模块代码。

配方五:写一个客户端

class MyClient:
    kind = 'my-client'
    version = '1'

    def __init__(self, cfg, record=None, services=None):
        self.cfg = cfg
        self.state = record or {}

    def play(self, player, *, max_steps=None, emit=None, head=None,
             on_call=None, on_result=None):
        ...   # 返回回执列表

发行版里声明:

[Distribution.ClientFactories.my]
Entry = "mods.examples.myclient.client:MyClient"

客户端要用什么能力,在 [Distribution.ClientFactories.my] 的 Services 里声明, 宿主会把它们注入 services。

配方六:让发行版接模型

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

然后确认三件事:

  1. 工具的 description 写清楚了;
  2. end_turn 收 summary、回 text;
  3. 该给模型看的事实都写进了 PlayerState。

三条都满足,同一个发行版就能同时接模型和不接模型。

配方七:加一份规则文档

RuleSection('贸易', '……', keywords=('贸易', 'market', '交易'))

大段手册用只读工具暴露(manual),别塞进规则正文。