Statecraft: Israel 确定性模拟原理:单一SplitMix64随机数与黄金哈希如何保证结果一致
Statecraft: Israel 确定性模拟原理:单一SplitMix64随机数与黄金哈希如何保证结果一致
Statecraft: Israel 是一款以 1948 年 5 月 15 日以色列建国为起点的文明类策略游戏,其核心是一个确定性模拟层:整局游戏只使用一个 SplitMix64 随机数生成器,并用黄金哈希(Golden Hash)为每个关键节点"盖章",保证存档、回放和"为什么发生这件事"报告在 .NET、Unity Mono 与 IL2CPP 上逐位一致。下面拆解这套机制的完整链路。
为什么策略游戏必须"逐位一致"
Statecraft: Israel 有三类功能天然依赖确定性:
- 存档与回放:读档后重放操作序列,必须得到一模一样的状态;
- "Why did this happen?" 报告:把状态变化归因到具体指令与规则;
- 跨平台校验:同一份模拟代码要跑在 .NET 测试机、Unity 编辑器(Mono)、macOS 玩家(IL2CPP)和浏览器 WebGL(IL2CPP)四种环境里。
项目规范写得很直白:模拟必须产出逐位相同的状态(见 docs/determinism.md)。为此,开发者在随机数、数学函数、字符串格式化三个最常见的"平台差异源"上做了系统性设计。
🎲 单一 SplitMix64:随机数状态只有一个 ulong
整个模拟里只有一个随机数生成器——SplitMix64,实现为 Rng.cs 中的一个值类型 Rng。它的全部状态就是一个 64 位整数 State,存放在 GameState.cs 的 RngState 字段里:
public ulong NextULong()
{
ulong z = State += 0x9E3779B97F4A7C15UL;
z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL;
z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL;
return z ^ (z >> 31);
}
这带来两个好处:
- 可存档:随机数状态是游戏状态的一部分,随存档一起保存,读档后"骰子"从断点继续,而不是重新掷;
- 可对照:生成器的输出被与 Sebastiano Vigna 的参考 C 实现逐值比对。测试 SplitMix64MatchesTheReferenceVectors 用种子
0和1234567校验前三个输出——期望值来自独立编译运行的参考实现,而不是从这份 C# 代码抄来的,因此即使 C# 实现有错也会被当场抓住。
模拟中随机抽取有严格的次序约定:玩家的战斗在指令阶段抽取,敌方在结算第 2 步按攻击者 id 升序抽取;而占领、占领计时、Deport 等路径明确不抽随机数(文档以 R-CTRL-004 等规则编号锁死)。抽取次数和时机固定,是结果一致的一半保证。
🧊 黄金哈希:给整局游戏拍一张"指纹照"
随机数保证过程可复现,哈希则验证结果真的复现了。GameState.Hash() 对状态做一次 SHA-256,输入是一段精心设计的"规范化文本"(CanonicalText),针对平台差异逐条设防:
| 易变因素 | 对策 |
|---|---|
| 字典遍历顺序 | 所有键按 ordinal 序排序后写入 |
| 浮点数的字符串表示(-0.0 vs 0.0、不同 runtime 拼写不同) | double 一律写成 IEEE 754 位模式的 16 位十六进制,-0.0 归一为 0.0 |
| 本地化(culture)影响数字与日期格式 | 全部使用 CultureInfo.InvariantCulture |
| 未初始化/空字段的表示 | 空章节整体省略,格式保持稳定 |
Hash() 和人类可读的 Describe() 共用同一个 writer,所以两者永远列出相同的字段。当黄金测试失败时,hash1950.txt 这类快照会按 [ind]、[pol]、[bud] 等分节 diff,每个数字旁边同时显示普通值与 IEEE 位,一眼定位是哪一格变了。
几条黄金跑图的哈希被钉死在 manifest.txt(常量同步在 GoldenRun.cs,供 Unity 端比对):
| 跑图 | 结束点 | 固定 SHA-256(前 16 位) |
|---|---|---|
hash1950 |
1950-01-15(第 20 回合) | 74fbe989d84a9877 |
hash1952 / mvp-end |
1952-01-15(第 44 回合,游戏终点) | d74296940a6a6c83 |
smoke5 |
1948-10-15(浏览器 5 回合冒烟) | 9255f2bcda06ed50 |
黄金跑图本身也是确定性的:固定种子 1948(GoldenRun.Seed)、Historical 模式、由参考玩家 ReferencePlayer 按既定策略下达指令,不是游戏 AI。此外 scenarios/ 目录下还有 cautious、reckless、mvp-defeat 等"另一条历史路径"脚本跑图,同样各有一个固定哈希。
🗺️ 避开平台差异:模拟层禁止三角函数
跨平台确定性最大的隐形杀手是数学库。不同 runtime 的 Math.Sin/Math.Cos 末位可能不同,所以 Statecraft: Israel 定了一条硬规则:模拟代码只允许调用 Math.Abs、Math.Min、Math.Max。
需要几何计算的地方(定居点属于哪个六角格、部队出生锚点在哪个格)全部离线预计算:由 tools/settlement_hexes.py 和 tools/unit_anchor_hexes.py 烘焙成内容文件(如 content/map/settlement_hexes.yaml、content/map/unit_anchor_hexes.yaml),模拟运行时直接读取,不做任何浮点三角运算。
🔁 当规则真的改了:黄金哈希如何"重新钉住"
规范里有一句铁律:任何黄金哈希的移动,必须是刻意的规则或内容变更。否则一律视为确定性 bug。流程如下:
- 测试失败时,diff 快照文件按分节展示变化,判断是否属于本次 PR 的预期改动;
- 确认合理后运行
STATECRAFT_UPDATE_GOLDEN=1 dotnet test sim/Statecraft.sln,一次性重写 manifest.txt、各golden/*.txt快照和GoldenRun.cs常量; - 该次运行仍会按旧值故意失败,需要再跑一次普通测试确认新值稳定——测试绝不在没有该环境变量时从运行结果里取哈希;
- 手动更新 docs/determinism.md 与
tools/web_check.py中的引用,在"Rebaseline history"表格里加一行说明为什么变(GoldenManifestTests 会揪出所有还印着旧哈希的地方)。
docs/determinism.md 里那张长长的重标定历史表就是活教材:从"移民预算线划归总理"到"4.4km 六角格重烘焙导致第 7 旅伤亡变化",每一次哈希变动都有任务号、原因和前后值对照。
另有两个精巧的补充机制:
- 不变量检查:invariants.yaml 声明"哈希可以变,但某些值必须在合理区间内",比如 1952 年末的外汇储备
fx必须 ≤ 0; - 原因文本不入哈希:"为什么发生"的叙述文本由哈希过的状态派生计算,改文案不会动哈希,重载存档却能复现同样的 Cause 行——文案自由与状态一致两不误。
🌍 四套环境逐一验证
这套机制不止在 .NET 上通过:文档记录了在 Unity 编辑器 Mono(EditMode 的 GoldenCheckTests 逐条枚举 manifest)、macOS IL2CPP 玩家(-batchmode -nographics -golden,打印 GOLDEN OK 行)和 WebGL IL2CPP(浏览器里跑 ?golden&smoke=5,由 tools/web_check.py 比对全部期望值)上的完整通过记录。内容变更与状态变更也被区分开:例如只是给定居点改回 1948 年历史名,内容哈希变了而黄金哈希不动,旧存档加载时显示"different game content"警告并重放回相同状态。
相关文件导读
| 路径 | 作用 |
|---|---|
| docs/determinism.md | 确定性总规范:规则、固定哈希、重标定历史 |
| sim/Statecraft.Sim/Rng.cs | SplitMix64 实现(全项目唯一 RNG) |
| sim/Statecraft.Sim/GameState.cs | 状态哈希与规范化文本 writer |
| sim/Statecraft.Sim/GoldenRun.cs | 黄金跑图循环与固定哈希常量 |
| sim/Statecraft.Sim.Tests/DeterminismTests.cs | 参考向量与黄金哈希测试 |
| sim/Statecraft.Sim.Tests/golden/manifest.txt | 全部固定哈希清单 |
| tools/settlement_hexes.py、tools/unit_anchor_hexes.py | 离线几何预计算,替代模拟层三角函数 |
一句话总结:Statecraft: Israel 用"一个可存档的 SplitMix64 + 一份防平台差异的规范化文本 + 一张逐位比对的哈希清单",把策略游戏最难的跨平台一致性,变成了每次提交都能自动验证的普通测试。



