引擎 API
运行时、模块基类、工具与阶段、玩家 API。
引擎是发行版之上的通用运行时:装 Mod、跑回合、存档、给模型发工具。
GameMod:模块要实现的东西
mixins 必实现;其余按需覆写。说明取自源码里的行内注释。
| 方法 | 签名 | 说明 |
|---|---|---|
| after_tool | after_tool(self, world, actor, name, result) | 工具执行后的钩子:改写结果或记日志。 |
| apply_state_change | apply_state_change(self, world, key, operation) | 替换状态对象前的钩子;默认检查写入所有权。 |
| before_tool | before_tool(self, world, actor, name, arguments) | 工具执行前的钩子:校验参数、限流、记账。 |
| content_definitions | content_definitions(self) | 返回「内容 ID → 定义」的映射。注册过的内容才有短键与显示名。 |
| initialize_world | initialize_world(self, world) | 建世界对象:把状态挂到 world 上。 |
| load_state | load_state(self, world, state) | 读回本模块的存档状态。 |
| mixins | mixins(self) -> 'tuple[type, ...]' | 必实现。返回混入 World 的类(Mixin);Mixin 的方法会变成世界对象的属性。 |
| needs | needs(self) | 本模块用到的其他能力名;能力名就是「模块ID:能力名」。 |
| numbers | numbers(self) | 本模块提供的数值;规则正文里的 {{number:…}} 从这里取,改参数规则正文就跟着变。 |
| objects | objects(self, world) | 返回「能力名 → 对象」的映射;能力方法就在这些对象上。 |
| optional | optional(self) | 可选依赖能力名:对方不在也不报错。 |
| player_api | player_api(self, world) | 返回玩家 API 对象;工具层通过它调用动作与只读事实。 |
| presentations | presentations(self) | 本模块提供的呈现部件(面板、回执渲染等)。 |
| provides | provides(self) | 本模块提供的能力名。 |
| rule_sections | rule_sections(self, world=None) | 返回规则正文节(RuleSection);模型用 player_rules 按主题查。 |
| save_state | save_state(self, world) | 导出本模块的存档状态。 |
| schema_for_actor | schema_for_actor(self, world, actor, schema) | 按玩家改写工具 schema(比如按权限隐藏参数)。 |
| stages | stages(self) -> 'tuple[Stage, ...]' | 返回结算阶段(Stage);阶段挂在发行版声明的挂点上。 |
| state_keys | state_keys(self) | 本模块独占的状态键;别人要写必须先在本模块的 State.Requests 里申请。 |
| tools | tools(self) -> 'tuple[Tool, ...]' | 返回本模块暴露给模型的工具(Tool)。工具要写清 description:模型只看得见它。 |
Tool:暴露给模型的工具
| 字段 | 类型 | 默认 | 说明 | |
|---|---|---|---|---|
name | str | None | ||
handler | Callable | None | ||
aliases | list | () | ||
description | str | |||
adapter | Callable \ | None | None | adapter 是 Mod 自己的坐标/旧参数转换,不属于通用引擎。 |
normalizers | dict | factory | normalizers 在 adapter 之后、schema 校验之前把显示词汇归一化成动作词汇。 | |
parameters | dict \ | None | None | |
argument_types | dict | factory | ||
read_only | bool | False | ||
hidden | bool | False | 只读面板等内部工具不出现在模型工具表;脚本/规则 AI 不走工具名。 | |
content_parameters | list | () | ||
owner | str \ | None | None | tool 层字段:owner 是提供玩家 API 的能力名;None 表示沿用「哪个模块返回」。 |
api | list | () | ||
covers | tuple[tuple[str, str], ...] | () | 组合工具额外覆盖的其他能力方法(如 foreign 组合 intelligence/diplomacy): 只用于装载期覆盖与读写一致性检查,工具仍由 owner 的上下文执行。 | |
fact | bool | False | ||
panel | bool | False | ||
groups | list | () | ||
schema_for_actor | Callable \ | None | None |
Stage:结算阶段
| 字段 | 类型 | 默认 | 说明 | |
|---|---|---|---|---|
name | str | None | ||
handler | str \ | Callable | None | |
requires | list | () | ||
after | list | () | ||
before | list | () | ||
title | str | |||
description | str | |||
hook | str | |||
needs | list | () | ||
provides | list | () | ||
scope | str | world |
RuleSection:规则正文
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
title | str | None | |
body | str | None | |
keywords | list | () | |
summary | str | ||
player_visible | bool | True | |
system | bool | False | 声明这一节要进模型系统提示:发行版自己说自己的玩法,不写在宿主里。 |
PlayerSession:模型能调的玩家 API
| 方法 | 签名 | 说明 |
|---|---|---|
| actions | actions(self) | |
| api_call | api_call(self, capability, method, arguments=None, *, action=None) | Trusted API call by capability + declared method (no tool name). |
| call_api | call_api(self, capability=None, method=None, arguments=None, action_label=None, **extra) | PlayerSession-level API entry; BoundPlayer adds services and audit. |
| events | events(self, cursor=0) | |
| memory_search | memory_search(self, query, limit=3) | |
| note_step | note_step(self, used, limit) | 客户端每发起一次模型请求上报一次;回执里的调用进度就靠它。 |
| observe | observe(self) | |
| query | query(self, name, arguments=None) | |
| rules | rules(self, topic='') | |
| step_state | step_state(self) | |
| submit | submit(self, action, arguments=None) |
Runtime:运行时
| 方法 | 签名 | 说明 |
|---|---|---|
| action_available | action_available(self, world, actor, name) | |
| activate_actor | activate_actor(self, world, actor, policy_id, **kwargs) | |
| actor_policy | actor_policy(self, world, actor) | |
| actor_prompt | actor_prompt(self, world, actor, default) | |
| actor_schedule | actor_schedule(self, world, declarations, *, seed=None) | |
| api_call | api_call(self, world, actor, capability, method, arguments=None) | Trusted in-process API call: capability + declared method, never a tool name. |
| api_is_write | api_is_write(self, capability, method) | |
| call | call(self, world, actor, name, arguments) | Host/internal dispatch: Tools keep their protocol, actions go to the API. |
| call_action | call_action(self, world, actor, name, arguments) | Execute a tool-layer action spec by name (umbrella / host helper). |
| check_interfaces | check_interfaces(self, world) | Validate every declared `[Interfaces]` method against the built objects. |
| check_save_dependencies | check_save_dependencies(self, manifest) | |
| deactivate_actor | deactivate_actor(self, world, actor) | |
| dependency_manifest | dependency_manifest(self) | 严格匹配 Mod 版本、依赖和阶段契约;实现升级由 Mod 作者提升 Version。 |
| derived | derived(self, world, key, calculate) | |
| enumerate_numbers | enumerate_numbers(self) | |
| find_policy | find_policy(self, policy_id) | |
| in_scope | in_scope(self, world, actor, unit) | |
| initial_actors | initial_actors(self, declarations) | |
| initialize_state | initialize_state(self, world) | |
| load_mod_state | load_mod_state(self, world, states) | |
| manual | manual(self) | |
| number | number(self, key, default=None) | Read a declared numeric constant from its owning module. |
| object_call | object_call(self, world, capability, method, *args, **kwargs) | 调用声明过的对象接口;所有者负责字段变更与校验。 |
| panel | panel(self, world, actor, name, arguments=None) | |
| parameter | parameter(self, world, actor, key, default=None) | |
| participants | participants(self, world, stage) | |
| permits | permits(self, world, actor, capability) | |
| player | player(self, world, actor, *, lock=None, on_write=None, on_fault=None, memory_query=None) | |
| player_api | player_api(self, world, capability) | 返回玩家 API 对象;工具层通过它调用动作与只读事实。 |
| player_facts | player_facts(self) | |
| read_scope | read_scope(self, world) | Share derived reads only within one immutable observation, never across actions. |
| read_state | read_state(self, world, key) | |
| register_content | register_content(self, owner, definitions) | |
| require_tool | require_tool(self, world, actor, name) | |
| rule_sections | rule_sections(self, world=None, *, player=False, actor=None) | 返回规则正文节(RuleSection);模型用 player_rules 按主题查。 |
| rule_text | rule_text(self, body) | Resolve rule-text placeholders against declared numbers. |
| rules | rules(self, world, topic='') | |
| save_mod_state | save_mod_state(self, world) | |
| schemas | schemas(self) | |
| select_rules | select_rules(self, sections, topic) | Longest-keyword match shared by the manual and the player API. |
| settle | settle(self, world) | |
| settlement_table | settlement_table(self) | |
| tool_available | tool_available(self, world, actor, name) | |
| world_class | world_class(self, name='World') | |
| write_state | write_state(self, world, key, operation) |
配置层
配置层(engine/config.py)声明每个字段的类型、取值范围与是否必填:
| 名字 | 说明 |
|---|---|
Field | 一个配置字段:类型元组、choices、minimum/maximum、nullable |
Schema | 一组字段的集合;normalize 会校验并保留未声明的键 |
component | 调用发行版自己声明的归一化函数 |
prepare | 把整份配置按发行版契约归一化 |