战国 Mod 开发文档

规则与手册

规则正文怎么写、模型怎么查、哪些规则该进系统提示。

模型查规则用内建工具 player_rules,它不属于任何发行版——引擎直接提供。

player_rules(topic="")   # 空 topic 返回全部规则目录
player_rules(topic="战争")

所以你的模块只要产出规则正文,模型就能查到。

规则正文:一节一主题

from engine.runtime import RuleSection

def rule_sections(self, world=None):
    return (
        RuleSection('军队',
                    f'步兵:征募耗粮 {INFANTRY["food"]}、金 {INFANTRY["gold"]},'
                    f'HP {INFANTRY["hp"]},攻击 {INFANTRY["atk"]}。',
                    keywords=('步兵', '征募', 'infantry', '军队')),
    )

一节写一件事,别把三个主题塞进一节——模型按主题查,塞一起就查不准。

keywords 是模型会搜的词,要把中文说法、英文说法、常见别称都覆盖上:

keywords=('战争', '开战', '宣战', '战争', 'war', '外交')

参数化:别把数字写死

规则正文里的数字要能随发行版参数变。引擎提供 numbers 钩子:

def numbers(self):
    return {'infantry_food': 20, 'infantry_gold': 30, 'infantry_hp': 100}

规则正文里写 {{number:infantry_food}},引擎在装载时把它替换成实际数值。 这样调平衡只改数字,规则正文不用动。

规则正文进系统提示

规则正文默认按需查(模型主动调 player_rules)。 但有些规则必须每回合都提醒模型——比如「必须先有国策才能结束回合」。

给 RuleSection 标 system=True,这一节就会进模型系统提示:

RuleSection('国策与回合',
            'end_turn 结束本国行动;世界结算仍由宿主统一调用。'
            '国策写跨回合的经济、军事、情报与外交战略……',
            keywords=('plan', '国策', 'summary', '小结', '回合', 'end_turn'),
            system=True)

只有确实需要每回合都说的才标 system=True:系统提示是常驻上下文,每多一句都多占预算。

系统提示里的其它文字

发行版自己的提示词放在自己的语言包里,不要写进宿主:

位置放什么
presentation/locales/*.json通用文案(所有发行版共用)
mods/native/tools/locales/*.jsonnative 专属的提示词与回执措辞
mods/<你的发行版>/locales/*.json你的发行版专属文案

发行版的工具层语言包会覆盖基础语言包里的同名键,所以同一个键可以有两种写法: 基础版通用,发行版版专属。

模型客户端本身不写死任何发行版的词汇:系统提示里的工具清单是按实际工具表生成的, 某个发行版没有 query 面板工具,提示里就不会出现 query(panel=…)。

手写文档

大段的手册(基础指南、战争手册、策略手册)不是规则正文——它们是独立文档, 用一个只读工具暴露:

Tool('manual', manual, read_only=True, panel=True,
     description='只读手册:doc 选一本文档(基础指南/战争手册/战略手册),返回全文。'
                 '文档为手写维护,不在规则目录里。')

规则正文是模型会搜的规则,手册是模型会通读的文档。两者别混。

自查

  1. 每个主题都有一节吗?模型搜得到吗?
  2. keywords 覆盖了模型可能用的说法吗?
  3. 数字是写死还是走 numbers?
  4. 必须常驻提醒的规则标了 system=True 吗?