Statecraft: Israel 技术架构解析:C确定性模拟与Unity渲染如何各司其职
Statecraft: Israel 技术架构解析:C#确定性模拟与Unity渲染如何各司其职
Statecraft: Israel 是一款面向开源社区的回合制大战略游戏:玩家扮演 1948 年 5 月 15 日的以色列总理,任命真实部长、分配预算、指挥旅级单位。它最特别的地方在于技术架构——一套纯 C# 确定性模拟负责所有游戏规则,Unity 只负责把结果画出来。本文带你拆解这两部分如何各司其职,以及"存档 = 种子 + 指令列表"背后完整的确定性工程。
先看仓库结构:四大模块各管一摊
整个项目只有四个核心目录,职责边界清晰得近乎苛刻:
| 目录 | 角色 | 一句话说明 |
|---|---|---|
sim/ |
游戏规则(大脑) | 纯 C# 库(netstandard2.1),零 Unity 依赖,含预算、战斗、事件、存档重放 |
unity/ |
渲染与输入(眼睛和手) | 只负责把模拟状态画出来、把玩家点击变回指令,不允许存在任何游戏规则 |
content/ |
数据(事实) | 人物、事件、地图全部是 YAML,每个事实都带 sources: 引用 |
tools/ |
数据管线(脚手架) | Python 工具:地图烘焙、降雨数据、浏览器冒烟检查 |
这条"规则永远住在模拟里,渲染层只是镜子"的铁律,被写进了项目协作规范 AGENTS.md 和 CONTRIBUTING.md,是理解后面一切的关键。
C# 确定性模拟:为什么"同样的选择,永远同样的结果"
策略游戏最怕"随机漂移":存档重放不出同一局面,联机对战就无从谈起。Statecraft 的模拟层为此做了一组非常克制的设计(完整规则见 docs/determinism.md):
- 全局只有一个随机数发生器。 Rng.cs 实现的是 SplitMix64,整个发生器状态就是一个
ulong,存放在GameState.RngState里——随机性被压缩成一个可序列化、可校验的数字。 - 模拟里禁止三角函数。 代码只允许调用
Math.Abs/Math.Min/Math.Max。因为不同平台的 cos/sin 实现可能有最后几位差异。需要几何计算的地方(比如某个定居点属于哪个六角格)由 Python 工具离线预计算成数据,模拟只读结果。 - 状态哈希用规范文本 + SHA-256。
GameState.Hash()把全部状态按固定顺序写成文本(浮点数直接写 IEEE 位模式、-0.0 写成 0.0、文化区格式一律 invariant),保证 .NET、Unity Mono 和 IL2CPP 三个运行时算出一模一样的哈希。
黄金测试(Golden Run):给整局游戏"钉死指纹"
在"确定性"之上,项目还有一套更狠的验收方式——黄金运行:
- GoldenRun.cs 用固定种子
1948加载真实的content/,由"参考玩家"自动下完 44 个月回合,结束时对状态求哈希,结果被钉在 sim/Statecraft.Sim.Tests/golden/manifest.txt 里(例如hash1952、mvp-end)。 - 任何一次改动只要让哈希变了一个字节,测试立刻失败。此时只有两种可能:你改了规则/内容(需在同一个 PR 里重新钉哈希并说明原因),或者你引入了确定性 bug。
- 快照文件 hash1950.txt 等会逐行展示"哪个字段变了、变成多少",改动的每一分钱去向都有据可查。docs/determinism.md 里还维护了一张完整的"重新定基历史表",记录了历次哈希变更的原因。
这套机制让存档系统可以做得极其简单——
存档 = 种子 + 指令列表
看 SaveGame.cs 的注释就知道:一个存档文件就是一行行文本,包含 seed、mode、每一回合的指令(event ID OPTION、map ACTION Q R……),以及最后 end <hex> 记录的终局状态哈希。
读档不是恢复内存快照,而是从头重放:拿同样的种子和指令重跑模拟,只要终局哈希对上,存档就是完好的。"为什么这个月外交分掉了 3 点"(即游戏里的 Why? 面板)也因此可以随时再生——解释文本由哈希后的状态推导而来,不占存档。
模拟与 Unity 如何对接:一条 DLL 桥梁
两个世界之间没有魔法,只有一个脚本:tools/build_sim_for_unity.py。
- 它在
sim/Statecraft.Sim上执行dotnet publish -c Release; - 产物
Statecraft.Sim.dll和YamlDotNet.dll被放到unity/Assets/Plugins/Statecraft; - Unity 侧的 C# 代码直接
using Statecraft.Sim,像调用普通库一样调用Simulation.Step。
因为模拟库目标是 netstandard2.1,Unity 的 Mono 与 IL2CPP 后端都能无差别地加载它。改完 sim/ 下的任何代码,重跑一次 uv run tools/build_sim_for_unity.py 即可(完整构建与本地运行流程见 BUILDING.md,环境安装见 docs/dev-setup.md)。
数据侧则走 content/:人物、事件、六角格地图(content/map/)全部是带来源引用的 YAML/JSON,由模拟库内的 ContentLoader.cs 加载——渲染层只拿到解析好的状态,不直接读原始数据。
Unity 侧:只画画,绝不"算"
unity/Assets/Scripts/ 的代码几乎都能对号入座到"表现"二字:
Map/:地形与地图渲染。地图不是手绘的,而是用真实高程与气候数据烘焙——MapBuilder.cs、HexGrid.cs、HeightmapLoader.cs 负责把高度图、生态区、1949 停火线画成一张可交互的立体地图;tools/terrain_bake.py、tools/land_bake.py 等 Python 脚本在管线上游生成这些资产。UI/+Boot/:界面与启动。UI 用 UI Toolkit 的数据绑定,视图模型在每回合Simulation.Step之后统一刷新一次——模拟每步返回全新的GameState克隆,界面永远不直接绑定可变状态。Boot/GoldenCheck.cs:连桌面/WebGL 播放器里都内置了黄金校验,启动时自动重放黄金运行并核对哈希,确保"玩家机器上的结果和开发者机器上的逐位一致"。
也就是说,Unity 里找不到任何一处"如果兵力大于敌人就扣血"之类的规则——它们全部在 sim/Statecraft.Sim/(战斗在 Combat.cs、回合流程在 TurnResolver.cs)。
跨平台一致性:同一份代码,四处验证
"确定性"不能只在 .NET 上成立才有意义。项目把同一套黄金哈希在四条链路上分别验证(记录见 docs/determinism.md):
- .NET 测试:
dotnet test sim/Statecraft.sln,加载真实content/跑全部模拟测试; - Unity 编辑器(Mono):EditMode 测试
GoldenCheckTests在引擎内重放; - WebGL / IL2CPP(Chrome):tools/web_check.py 打开浏览器构建,带
?golden参数自动跑黄金运行并比对哈希; - macOS IL2CPP 桌面播放器:
-batchmode -golden启动即校验。
浏览器版还有一条 smoke=5 冒烟值:用黄金种子从 UI 按钮点满 5 回合,把"UI 路径 + 模拟"一起钉住——连"事件卡上哪个选项排第一"这种界面细节的改动都会触发重新记录。
新手速查:读懂这份代码的路线图
- 想懂规则:从 GameState.cs(状态长什么样)→ TurnResolver.cs(一回合按什么顺序结算)入手,规则编号(如
R-CTRL-004)在 docs/rules/README.md 有登记; - 想懂数据:翻 content/events/ 里任意一个事件 YAML,对照 docs/WRITING_EVENTS.md;
- 想懂渲染:看 unity/Assets/Scripts/Map/MapScene.cs 和 unity/Assets/Scripts/Boot/GameBoot.cs;
- 想跑起来:按 BUILDING.md 装好 .NET SDK 10 与 Unity 6000.3.25f1,先执行
uv run tools/build_sim_for_unity.py,再打开unity/工程。
一句话总结:Statecraft: Israel 用"netstandard2.1 纯 C# 模拟 + DLL 注入 Unity + 全平台黄金哈希"这套组合,把一个历史大战略游戏做成了可重放、可审计、可跨浏览器运行的工程样本——规则在模拟里逐位确定,画面在 Unity 里随取随画,边界清晰,互不越界。



