五分钟上手
装依赖、跑起来、写一个最小模块。
环境
| 项 | 要求 |
|---|---|
| Python | 3.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')