战国 Mod 开发文档

引擎 API

运行时、模块基类、工具与阶段、玩家 API。

引擎是发行版之上的通用运行时:装 Mod、跑回合、存档、给模型发工具。

GameMod:模块要实现的东西

mixins 必实现;其余按需覆写。说明取自源码里的行内注释。

方法签名说明
after_toolafter_tool(self, world, actor, name, result)工具执行后的钩子:改写结果或记日志。
apply_state_changeapply_state_change(self, world, key, operation)替换状态对象前的钩子;默认检查写入所有权。
before_toolbefore_tool(self, world, actor, name, arguments)工具执行前的钩子:校验参数、限流、记账。
content_definitionscontent_definitions(self)返回「内容 ID → 定义」的映射。注册过的内容才有短键与显示名。
initialize_worldinitialize_world(self, world)建世界对象:把状态挂到 world 上。
load_stateload_state(self, world, state)读回本模块的存档状态。
mixinsmixins(self) -> 'tuple[type, ...]'必实现。返回混入 World 的类(Mixin);Mixin 的方法会变成世界对象的属性。
needsneeds(self)本模块用到的其他能力名;能力名就是「模块ID:能力名」。
numbersnumbers(self)本模块提供的数值;规则正文里的 {{number:…}} 从这里取,改参数规则正文就跟着变。
objectsobjects(self, world)返回「能力名 → 对象」的映射;能力方法就在这些对象上。
optionaloptional(self)可选依赖能力名:对方不在也不报错。
player_apiplayer_api(self, world)返回玩家 API 对象;工具层通过它调用动作与只读事实。
presentationspresentations(self)本模块提供的呈现部件(面板、回执渲染等)。
providesprovides(self)本模块提供的能力名。
rule_sectionsrule_sections(self, world=None)返回规则正文节(RuleSection);模型用 player_rules 按主题查。
save_statesave_state(self, world)导出本模块的存档状态。
schema_for_actorschema_for_actor(self, world, actor, schema)按玩家改写工具 schema(比如按权限隐藏参数)。
stagesstages(self) -> 'tuple[Stage, ...]'返回结算阶段(Stage);阶段挂在发行版声明的挂点上。
state_keysstate_keys(self)本模块独占的状态键;别人要写必须先在本模块的 State.Requests 里申请。
toolstools(self) -> 'tuple[Tool, ...]'返回本模块暴露给模型的工具(Tool)。工具要写清 description:模型只看得见它。

Tool:暴露给模型的工具

字段类型默认说明
namestrNone
handlerCallableNone
aliaseslist()
descriptionstr
adapterCallable \NoneNoneadapter 是 Mod 自己的坐标/旧参数转换,不属于通用引擎。
normalizersdictfactorynormalizers 在 adapter 之后、schema 校验之前把显示词汇归一化成动作词汇。
parametersdict \NoneNone
argument_typesdictfactory
read_onlyboolFalse
hiddenboolFalse只读面板等内部工具不出现在模型工具表;脚本/规则 AI 不走工具名。
content_parameterslist()
ownerstr \NoneNonetool 层字段:owner 是提供玩家 API 的能力名;None 表示沿用「哪个模块返回」。
apilist()
coverstuple[tuple[str, str], ...]()组合工具额外覆盖的其他能力方法(如 foreign 组合 intelligence/diplomacy): 只用于装载期覆盖与读写一致性检查,工具仍由 owner 的上下文执行。
factboolFalse
panelboolFalse
groupslist()
schema_for_actorCallable \NoneNone

Stage:结算阶段

字段类型默认说明
namestrNone
handlerstr \CallableNone
requireslist()
afterlist()
beforelist()
titlestr
descriptionstr
hookstr
needslist()
provideslist()
scopestrworld

RuleSection:规则正文

字段类型默认说明
titlestrNone
bodystrNone
keywordslist()
summarystr
player_visibleboolTrue
systemboolFalse声明这一节要进模型系统提示:发行版自己说自己的玩法,不写在宿主里。

PlayerSession:模型能调的玩家 API

方法签名说明
actionsactions(self)
api_callapi_call(self, capability, method, arguments=None, *, action=None)Trusted API call by capability + declared method (no tool name).
call_apicall_api(self, capability=None, method=None, arguments=None, action_label=None, **extra)PlayerSession-level API entry; BoundPlayer adds services and audit.
eventsevents(self, cursor=0)
memory_searchmemory_search(self, query, limit=3)
note_stepnote_step(self, used, limit)客户端每发起一次模型请求上报一次;回执里的调用进度就靠它。
observeobserve(self)
queryquery(self, name, arguments=None)
rulesrules(self, topic='')
step_statestep_state(self)
submitsubmit(self, action, arguments=None)

Runtime:运行时

方法签名说明
action_availableaction_available(self, world, actor, name)
activate_actoractivate_actor(self, world, actor, policy_id, **kwargs)
actor_policyactor_policy(self, world, actor)
actor_promptactor_prompt(self, world, actor, default)
actor_scheduleactor_schedule(self, world, declarations, *, seed=None)
api_callapi_call(self, world, actor, capability, method, arguments=None)Trusted in-process API call: capability + declared method, never a tool name.
api_is_writeapi_is_write(self, capability, method)
callcall(self, world, actor, name, arguments)Host/internal dispatch: Tools keep their protocol, actions go to the API.
call_actioncall_action(self, world, actor, name, arguments)Execute a tool-layer action spec by name (umbrella / host helper).
check_interfacescheck_interfaces(self, world)Validate every declared `[Interfaces]` method against the built objects.
check_save_dependenciescheck_save_dependencies(self, manifest)
deactivate_actordeactivate_actor(self, world, actor)
dependency_manifestdependency_manifest(self)严格匹配 Mod 版本、依赖和阶段契约;实现升级由 Mod 作者提升 Version。
derivedderived(self, world, key, calculate)
enumerate_numbersenumerate_numbers(self)
find_policyfind_policy(self, policy_id)
in_scopein_scope(self, world, actor, unit)
initial_actorsinitial_actors(self, declarations)
initialize_stateinitialize_state(self, world)
load_mod_stateload_mod_state(self, world, states)
manualmanual(self)
numbernumber(self, key, default=None)Read a declared numeric constant from its owning module.
object_callobject_call(self, world, capability, method, *args, **kwargs)调用声明过的对象接口;所有者负责字段变更与校验。
panelpanel(self, world, actor, name, arguments=None)
parameterparameter(self, world, actor, key, default=None)
participantsparticipants(self, world, stage)
permitspermits(self, world, actor, capability)
playerplayer(self, world, actor, *, lock=None, on_write=None, on_fault=None, memory_query=None)
player_apiplayer_api(self, world, capability)返回玩家 API 对象;工具层通过它调用动作与只读事实。
player_factsplayer_facts(self)
read_scoperead_scope(self, world)Share derived reads only within one immutable observation, never across actions.
read_stateread_state(self, world, key)
register_contentregister_content(self, owner, definitions)
require_toolrequire_tool(self, world, actor, name)
rule_sectionsrule_sections(self, world=None, *, player=False, actor=None)返回规则正文节(RuleSection);模型用 player_rules 按主题查。
rule_textrule_text(self, body)Resolve rule-text placeholders against declared numbers.
rulesrules(self, world, topic='')
save_mod_statesave_mod_state(self, world)
schemasschemas(self)
select_rulesselect_rules(self, sections, topic)Longest-keyword match shared by the manual and the player API.
settlesettle(self, world)
settlement_tablesettlement_table(self)
tool_availabletool_available(self, world, actor, name)
world_classworld_class(self, name='World')
write_statewrite_state(self, world, key, operation)

配置层

配置层(engine/config.py)声明每个字段的类型、取值范围与是否必填:

名字说明
Field一个配置字段:类型元组、choices、minimum/maximum、nullable
Schema一组字段的集合;normalize 会校验并保留未声明的键
component调用发行版自己声明的归一化函数
prepare把整份配置按发行版契约归一化