确定性指南
确定性模拟意味着:给定相同的初始种子和输入,无论运行多少次,也无论运行在 macOS、iOS、Windows、Linux、Android 还是 Web 上,都会产生完全相同的状态。确定性让回放、每日种子挑战、存档读档一致性,以及在 nsgotest 下的自动化玩法测试都稳定可靠。
本指南说明在 NSGo 游戏中保持确定性的核心规则,以及如何使用 packages/game/random 编写自动化校验。
1. 只用 game.Loop 的固定步长 dt 推进时间
所有模拟状态的推进都应放在 game.Loop.Update(dt) 中,并只使用固定的 dt(或整数 tick 计数器)。不要在模拟逻辑中读取 time.Now()、time.Since 或显示帧之间的真实时间差。
loop := &game.Loop{
Rate: 60,
Update: func(dt time.Duration) {
sim.Tick++
sim.Step(dt) // dt 始终是 1/60 秒
},
Draw: func(alpha float64) {
// 只做画面插值,绝不修改模拟状态。
render(sim.Prev, sim.Curr, alpha)
},
}
Draw(alpha)按显示器刷新率运行,对游戏逻辑状态必须保持只读。- 冷却时间和计时器应使用整数 tick 或
dt的精确累加,而不是基于系统墙钟时间的截止点。
2. 按用途使用带种子的 random.Stream
不要在模拟代码中调用 Go 全局的 math/rand 或 math/rand/v2。全局生成器会在不同子系统之间共享隐藏的可变状态,而且标准库的辅助方法在不同 Go 版本之间也可能改变实现。
改用 github.com/nsgo-dev/game/packages/game/random:
import "github.com/nsgo-dev/game/packages/game/random"
streams := random.NewStreams(masterSeed)
ai := streams.Stream("ai")
loot := streams.Stream("loot")
particles := streams.Stream("particles")
- 每个
Stream都内置了独立的 SplitMix64 + Xoshiro256** 算法和固定的拒绝采样实现(Intn、IntRange、Float64、Float32、Range、Range32、Bool、Chance、Pick、WeightedIndex、Shuffle)。同一个种子在所有 Go 版本、操作系统和 CPU 架构(32 位、64 位、ARM64、x64 和 WebAssembly)上产生的比特序列完全一致。 - 通过
root.Fork("loot")、root.Fork("level-1").Fork("spawns")或streams.Stream("loot")按用途派生子流时,既不会推进父流,也不会影响兄弟流。新增粒子特效或调整创建顺序,都不会改变敌人 AI 或战利品掉落。 - 把纯表现层的随机性(粒子、镜头震动、音效微调)放在独立的流里,避免视觉改动影响玩法逻辑。
3. 不要依赖 Go map 的遍历顺序
Go 会刻意随机化 for k, v := range m 的遍历顺序。如果在对顺序敏感的游戏逻辑中直接遍历 map——例如结算伤害、处理碰撞、生成波次,或在循环内从 random.Stream 取随机数——就会导致每次运行结果分叉。
- 在
Update需要遍历的数据结构中,优先使用按创建顺序或稳定实体 ID 排列的切片。 - 如果必须遍历 map,先对键排序:
for _, id := range slices.Sorted(maps.Keys(enemies)) {
enemies[id].Update(dt, ai)
}
4. 保持模拟单线程,不依赖 goroutine 调度顺序
所有对模拟状态的修改都应在引擎的 goroutine 上、于 Loop.Update 内按顺序执行。
- 不要让多个 goroutine 并发修改游戏状态或共享同一个
random.Stream。 - 不要用
select监听多个同时就绪的 channel 来做玩法决策,因为 Go 会在就绪分支中伪随机选择。 - 如果后台 goroutine 承担了寻路或区块生成等计算,应在确定的 tick 边界接收结果,并按规范的稳定键排序后再应用,而不要按完成到达顺序应用。
5. 保持浮点数计算顺序一致
IEEE-754 浮点加法和乘法不满足结合律:(a + b) + c 与 a + (b + c) 在最低位上可能不同。经过几百个 tick 后,1 ULP 的微小偏差就可能跨过碰撞或条件分支的阈值,从而放大成明显分叉。
- 累加力、速度、得分等浮点值时,始终按固定、确定的实体顺序执行。
- 避免在不同路径中混用
float32和float64。 - 计数器、计时器、网格坐标和资源数量优先使用整数或定点表示。
6. 存档与回放时保存并恢复 PRNG 状态
Stream 的完整状态(初始种子以及 256 位生成器内部状态)可以通过 State() 导出,并通过 SetState(state) 恢复。State 支持直接使用 encoding/json 序列化,读档后会无缝续接完全相同的后续随机序列:
// 保存
data, err := json.Marshal(streams.States())
// 读取
var saved map[string]random.State
if err := json.Unmarshal(data, &saved); err == nil {
streams.Restore(saved)
}
对于单个流,使用 s.State() 和 s.SetState(state)。回放或重开关卡时,调用 s.Reset() 或 streams.Reset() 即可把流重置回初始种子起点。
7. 在 nsgotest 测试中验证确定性
random 包内置了确定性校验辅助函数,会从头多次运行模拟,并在任意一次运行出现分叉时报错。
用 AssertDeterministic 检查完整运行,包括在 nsgotest 下驱动真实的 game.Loop:
func TestMain(m *testing.M) { nsgotest.Main(m) }
func TestSimulationIsDeterministic(t *testing.T) {
random.AssertDeterministic(t, 4, func() WorldSnapshot {
streams := random.NewStreams(42)
world := NewWorld(streams)
loop := &game.Loop{
Rate: 60,
Update: func(dt time.Duration) { world.Step(dt) },
}
app := nsgotest.Start(t, func(cx *core.Scope) core.Node {
loop.Run(cx)
return core.View{}
})
app.Advance(2 * time.Second)
return world.Snapshot()
})
}
当多步模拟出现分叉时,用 CheckSteps 或 AssertDeterministicSteps 精确定位第一次发生分叉的步骤编号并输出两份状态:
func TestStepByStepDeterminism(t *testing.T) {
random.AssertDeterministicSteps(t, 300, func() func(step int) WorldSnapshot {
world := NewWorld(random.NewStreams(42))
dt := time.Second / 60
return func(step int) WorldSnapshot {
world.Step(dt)
return world.Snapshot()
}
}, nil)
}
运行测试:
go tool nsgo test ./...
如果 AssertDeterministicSteps 失败,它会报告第一个分叉的步数以及 run A、run B 各自的状态,方便直接定位引入非确定性的那一帧逻辑。