战国 Mod 开发文档

五分钟上手

装依赖、跑起来、写一个最小模块。

环境

项要求
Python3.13(本机用 3.13.x)
依赖requirements.txt(模型客户端要的 openai);地图 PNG 另需 requirements-vision.txt(Pillow),不装也能跑,只是没有地图图
平台Linux / macOS / Windows 均可(引擎不依赖平台特性)
cd <仓库根>
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt          # 核心
.venv/bin/pip install -r requirements-vision.txt    # 还要地图 PNG 就装这个

游戏本体除模型客户端外是纯标准库。

跑起来

# 离线回归:全仓库的验收测试(数百项,约两分钟)
.venv/bin/python -m unittest discover -s tests

# 只跑示例 Mod 的测试
.venv/bin/python -m unittest tests.test_example_mods -v

# 把所有示例 Mod 跑一遍
.venv/bin/python mods/examples/tour.py

玩一局:最小可玩游戏

mods/examples/minigame 是从零写的一套九模块小规则:三种资源、一个地形、五种建筑、 一个兵种、宣战与议和。离线可跑完整局,不需要任何 API key。

.venv/bin/python mp_run.py --config /tmp/mini.json --new --turns 5

配置形如:

{
  "mods": "mods.minigame.toml",
  "map_size": 12,
  "seed": 3,
  "nations": [
    {"id": "scenario:qin", "name": "秦", "client": "mini", "position": [3, 3]},
    {"id": "scenario:chu", "name": "楚", "client": "mini", "position": [8, 8]}
  ]
}

"client": "mini" 用发行版自带的简易策略驱动,不需要 API key。 换成 "client": "llm" 就交给真实模型玩:同一套规则、同一套工具面, 发行版不需要为模型做任何额外改动——这正是模型面向契约存在的理由。

写你的第一个模块

一个模块 = 两个文件:

mods/examples/hello/
  mod.toml    声明:身份、依赖、状态、能力
  mod.py      实现:继承 GameMod 的类

mod.toml:

[Mod]
Id = "example:hello"
Version = "1.0.0"
Entry = "mods.examples.hello.mod:HelloMod"

[State]
Owns = ["hello"]

[Capabilities]
Provides = ["example:hello"]

mod.py:

from engine.runtime import GameMod, Tool

class HelloMod(GameMod):
    def mixins(self):
        return ()                    # 必填;不给世界挂属性就返回空元组

    def initialize_world(self, world):
        world.hello = {}             # 世界构造完成后调用一次

    def tools(self):
        return (Tool('hello_add', self._add, description='加一个数。'),
                Tool('hello_total', self._total, read_only=True, description='看总数。'))

    @staticmethod
    def _add(world, actor, amount: int):
        world.hello[actor] = world.hello.get(actor, 0) + amount
        return {'actor': actor, 'count': world.hello[actor]}

    @staticmethod
    def _total(world, actor):
        return {'count': sum(world.hello.values())}

Entry 里的包路径按仓库根解析,各层目录不需要 __init__.py(Python 命名空间包)。

两种装载方式:

from engine.runtime import Runtime, Unit
from mods.examples.hello.mod import HelloMod

# ① 进程内,不落文件:适合单模块开发与测试
runtime = Runtime([Unit('example:hello', HelloMod(), version='1.0.0')])
world = runtime.world_class()()
runtime.call(world, 'demo', 'hello_add', {'amount': 3})

# ② 从目录:目录里只有模块声明,没有发行版清单也能跑
runtime = Runtime.load('mods/examples/hello')

下一步