Statecraft: Israel 技术架构解析:C确定性模拟与Unity渲染如何各司其职

原创2026-11-04 19:31:181,976 阅读

Statecraft: Israel 技术架构解析:C#确定性模拟与Unity渲染如何各司其职

Statecraft: Israel 是一款面向开源社区的回合制大战略游戏:玩家扮演 1948 年 5 月 15 日的以色列总理,任命真实部长、分配预算、指挥旅级单位。它最特别的地方在于技术架构——一套纯 C# 确定性模拟负责所有游戏规则,Unity 只负责把结果画出来。本文带你拆解这两部分如何各司其职,以及"存档 = 种子 + 指令列表"背后完整的确定性工程。

Statecraft: Israel 开源大战略游戏的地图微缩景观渲染效果,展示 Unity 侧的地形与城市画面

先看仓库结构:四大模块各管一摊

整个项目只有四个核心目录,职责边界清晰得近乎苛刻:

目录 角色 一句话说明
sim/ 游戏规则(大脑) 纯 C# 库(netstandard2.1),零 Unity 依赖,含预算、战斗、事件、存档重放
unity/ 渲染与输入(眼睛和手) 只负责把模拟状态画出来、把玩家点击变回指令,不允许存在任何游戏规则
content/ 数据(事实) 人物、事件、地图全部是 YAML,每个事实都带 sources: 引用
tools/ 数据管线(脚手架) Python 工具:地图烘焙、降雨数据、浏览器冒烟检查

这条"规则永远住在模拟里,渲染层只是镜子"的铁律,被写进了项目协作规范 AGENTS.md 和 CONTRIBUTING.md,是理解后面一切的关键。

Statecraft: Israel 的 Unity 渲染端真实画面:由高程数据烘焙的 3D 地图、六角格网格与城市建筑

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? 面板)也因此可以随时再生——解释文本由哈希后的状态推导而来,不占存档。

Statecraft: Israel 的 Why 解释面板:确定性模拟把每回合的每个状态变化都归因到具体原因

模拟与 Unity 如何对接:一条 DLL 桥梁

两个世界之间没有魔法,只有一个脚本:tools/build_sim_for_unity.py。

  1. 它在 sim/Statecraft.Sim 上执行 dotnet publish -c Release;
  2. 产物 Statecraft.Sim.dll 和 YamlDotNet.dll 被放到 unity/Assets/Plugins/Statecraft;
  3. 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 加载——渲染层只拿到解析好的状态,不直接读原始数据。

Statecraft: Israel 的 Unity UI 层:内阁界面以半圆座椅展示真实部长的肖像卡片,纯表现层代码

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):

  1. .NET 测试:dotnet test sim/Statecraft.sln,加载真实 content/ 跑全部模拟测试;
  2. Unity 编辑器(Mono):EditMode 测试 GoldenCheckTests 在引擎内重放;
  3. WebGL / IL2CPP(Chrome):tools/web_check.py 打开浏览器构建,带 ?golden 参数自动跑黄金运行并比对哈希;
  4. macOS IL2CPP 桌面播放器:-batchmode -golden 启动即校验。

浏览器版还有一条 smoke=5 冒烟值:用黄金种子从 UI 按钮点满 5 回合,把"UI 路径 + 模拟"一起钉住——连"事件卡上哪个选项排第一"这种界面细节的改动都会触发重新记录。

新手速查:读懂这份代码的路线图

一句话总结:Statecraft: Israel 用"netstandard2.1 纯 C# 模拟 + DLL 注入 Unity + 全平台黄金哈希"这套组合,把一个历史大战略游戏做成了可重放、可审计、可跨浏览器运行的工程样本——规则在模拟里逐位确定,画面在 Unity 里随取随画,边界清晰,互不越界。

登录后查看全文
statecraft-israel