状态与存档
状态归谁、怎么存、版本变了怎么办。
状态归谁
每个状态键有唯一主人:在某个模块的 [State].Owns 里声明。
引擎裁决三件事:
- 只有主人能替换这个状态对象。
- 申请过写入权的模块可以在自己的逻辑里改它。
- 存档时按主人分块存,读回时按主人分块读。
所以状态键要短而具体: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() 完全相等才算过——这比「读回来能跑」严格得多,能抓住引用共享、时间戳、 浮点精度之类的问题。