实体(entities)
面向 NSGo 游戏的小型、零反射实体组件系统(ECS):代际实体句柄、强类型稀疏集合组件、零分配查询、拓扑排序系统调度、预制体,以及与 game/save 集成的 JSON 世界快照。
import "github.com/nsgo-dev/game/packages/game/entities"
架构决策
在实现 entities(#136)之前,我们对比了三种用于表达游戏对象的架构方案:
- 小型、零反射、代际索引的稀疏集合 ECS(采用)。
- 面向对象场景树:堆分配节点加虚方法更新。
- 基于反射的原型(Archetype)ECS:动态组件表与运行时查询规划器。
选择方案(1)基于以下五点原因:
- 可预测的零分配热路径:实体是 64 位代际句柄(32 位槽位索引 + 32 位代数),通过空闲列表复用槽位;每种组件存放在连续的强类型稀疏集合(
Store[T])中。稳态下创建和销毁 10 万个实体、读写组件以及遍历查询均为 0 堆分配。 - 零反射:通过 Go 泛型和零大小类型标签区分组件存储,所有组件访问、查询迭代和预制体构造都在编译期静态类型检查,不引入
reflect。 - 安全的句柄生命周期:销毁实体时会递增对应槽位的代数再放回空闲列表,因此陈旧的
Entity句柄永远不会误指复用了同一槽位的新实体。 - 显式且确定的执行顺序:系统通过
Before和After声明顺序约束,由 Kahn 拓扑排序结合注册顺序决胜规则一次性解析;循环依赖与未知目标会明确报错,Order()便于调试叠层打印执行顺序。 - 清晰的序列化边界:只有通过
RegisterCodec[T]注册的组件才会写入确定性的WorldSnapshotJSON 并交由game/save持久化,从而将精灵、音频声道等临时运行态排除在存档之外,同时完整保留实体 ID 与跨实体引用。
实体与 World
Entity 是一个 uint64,低 32 位为槽位索引,高 32 位为代数(entities.Zero 是无效句柄,永远不会存活)。World 拥有全部实体及其组件存储。
NewWorld()返回一个新的空世界(World的零值也立即可用)。Spawn()、Destroy(e)、Alive(e)和Count()管理实体生命周期并复用已释放槽位。Clear()清除所有实体和组件,递增代数使旧句柄失效,同时保留切片容量以实现零分配复用;Reset()释放底层存储。Attach(cx)将世界绑定到 NSGo 的*core.Scope,在作用域销毁时自动调用Dispose()。
world := entities.NewWorld()
world.Attach(cx)
hero := world.Spawn()
world.Alive(hero) // true
world.Destroy(hero)
world.Alive(hero) // false,即使槽位被复用后仍为 false
组件与查询
每种组件类型 T 保存在独立的强类型稀疏集合 *Store[T] 中。顶层泛型函数直接操作 *World,也可以通过 Component[T](w) 获取 *Store[T] 在紧密循环中直接访问。
Set[T](w, e, v)、Get[T](w, e)、Has[T](w, e)和Remove[T](w, e)以 O(1) 复杂度添加、读取、判断和移除组件。Each1[A]、Each2[A, B]和Each3[A, B, C]从最小的稀疏集合出发,在其余集合中做 O(1) 成员检查,按确定顺序访问精确匹配的实体,零反射且零堆分配。回调返回false即可提前结束遍历。
type Position struct{ X, Y float64 }
type Velocity struct{ DX, DY float64 }
entities.Set(world, hero, Position{X: 10, Y: 20})
entities.Set(world, hero, Velocity{DX: 60, DY: 0})
entities.Each2[Position, Velocity](world, func(e entities.Entity, p *Position, v *Velocity) bool {
p.X += v.DX * dt.Seconds()
p.Y += v.DY * dt.Seconds()
return true
})
系统与更新顺序
Scheduler 在每个 game.Loop 固定步长上按确定的拓扑顺序执行具名系统。
AddSystem(name, fn, opts...)注册系统并附带可选的Before(other)与After(other)约束,目标系统可以先引用后注册。Build()校验约束并通过 Kahn 算法解析顺序,无约束冲突时按注册顺序决胜;引用不存在的目标返回ErrUnknownSystem,存在环路返回ErrSystemCycle。Order()返回解析后的系统名称列表,String()将其格式化为"a -> b -> c",便于调试叠层显示。Step(w, dt)在必要时完成解析并按顺序执行所有系统,稳态运行零分配。
sched := entities.NewScheduler()
_ = sched.AddSystem("input", readInput)
_ = sched.AddSystem("physics", stepPhysics, entities.After("input"))
_ = sched.AddSystem("render", syncSprites, entities.After("physics"))
loop := &game.Loop{
Rate: 60,
Update: func(dt time.Duration) {
_ = sched.Step(world, dt)
},
}
预制体(Prefab)
Prefab 是带名称的实体模板,每次生成时为新实体批量附着预设组件。
NewPrefab(name)创建模板,Clone(name)可派生变体而不修改原模板。With[T](p, v)附加按值复制的组件模板。WithFunc[T](p, make)在每次Spawn时调用make(),确保包含切片、映射或指针的组件在各实体之间完全独立。Spawn(w)和SpawnN(w, n)按模板生成状态互不干扰的实体。
goblin := entities.NewPrefab("goblin")
entities.With(goblin, Position{X: 10, Y: 20})
entities.WithFunc(goblin, func() Inventory {
return Inventory{Items: []string{"dagger"}}
})
squad := goblin.SpawnN(world, 5)
世界存档与加载
世界可序列化为确定性的 WorldSnapshot JSON 结构,并直接与 game/save 协同工作。
RegisterCodec[T](w, typeName)为组件类型T注册 JSON 编解码器;未注册的组件不会写入快照。w.Snapshot()按槽位索引升序输出存活实体、按编解码器名称升序输出组件,完整保留索引与代数,使组件中保存的Entity引用在恢复后依然有效。w.Restore(snap)先解码到临时世界再原子提交;若缺少编解码器或数据损坏,原世界保持完好。SaveWorld(store, slot, w)与LoadWorld(store, slot, w)通过save.Store(同时支持save.NewStorageStore和save.NewFileStore,以及存档版本和迁移)保存和恢复世界。
_ = entities.RegisterCodec[Position](world, "position")
_ = entities.RegisterCodec[Velocity](world, "velocity")
store := save.NewStorageStore(cx.Storage(), "game")
if err := entities.SaveWorld(store, "slot1", world); err != nil {
return err
}
fresh := entities.NewWorld()
_ = entities.RegisterCodec[Position](fresh, "position")
_ = entities.RegisterCodec[Velocity](fresh, "velocity")
if err := entities.LoadWorld(store, "slot1", fresh); err != nil {
return err
}