战国 Mod 开发文档

状态与存档

状态归谁、怎么存、版本变了怎么办。

状态归谁

每个状态键有唯一主人:在某个模块的 [State].Owns 里声明。

引擎裁决三件事:

  1. 只有主人能替换这个状态对象。
  2. 申请过写入权的模块可以在自己的逻辑里改它。
  3. 存档时按主人分块存,读回时按主人分块读。

所以状态键要短而具体:accounts、territory、buildings、military。 不要起 data、state 这种大名字——迟早和别人的撞。

存取

def save_state(self, world):
    return {'rows': {owner: {key: row.amount for key, row in rows.items()}
                     for owner, rows in world.accounts.rows().items()}}

def load_state(self, world, state):
    world.accounts.restore(state)

规矩:

  • save_state 返回可序列化的纯数据(dict / list / 标量)。
  • 别返回对象引用、生成器、dataclass 实例——存下去再读出来就不是同一个东西了。
  • load_state 要能把 save_state 的输出原样读回:这是存档往返测试的判据。

版本

  • 模块版本写在 Mod.Version。
  • 发行版版本写在 Distribution.Version。
  • 存档里记着当时的模块版本与依赖清单。

装载时严格核对:存档依赖清单与当前发行版不一致,直接拒绝装载,不做静默迁移。

SaveFormatError: 存档依赖与当前发行版不一致

这是刻意的:1.0 之前不承诺旧档兼容,宁可拒绝也不要加载出一个半对半错的世界。

版本变了怎么办

确要改存档时,走迁移脚本,不要在 load_state 里偷偷兼容:

python3 scripts/upgrade_save_manifest.py <旧存档> <新存档>

load_state 里做兼容会让「同一份存档在不同版本里读出不同结果」,很难排查。

存档格式

项值
格式号zhanguo.session/5
内容世界状态 + 审计记录 + 模块版本 + 依赖清单 + 事件游标
审计记录每一步动作与回执都在档里,可以回看模型做了什么

往返测试

任何带状态的模块都要有这一条:

def test_state_round_trip(self):
    host = self.host()
    host.cycle()
    path = tmpfile()
    host.save(path)
    self.assertEqual(GameHost.load(path, self.cfg()).to_save(), host.to_save())

to_save() 完全相等才算过——这比「读回来能跑」严格得多,能抓住引用共享、时间戳、 浮点精度之类的问题。