《MMO 服务器开发》2.1 entity runtime 与句柄

// file: internal/entity/id.go
// tier: L1
// verify: go test ./internal/entity/
package entity

// EntityID 的位布局：高 16 位是场景/实例号，低 48 位是实例内自增序号。
//
//	63            48 47                              0
//	+---------------+---------------------------------+
//	|   scene (16)  |            seq (48)             |
//	+---------------+---------------------------------+
//
// 高 16 位放场景号，是为了让「这个实体属于哪个场景」不用查表：
// 拿到 ID 直接右移 48 位就知道。低 48 位是场景内的自增序号，
// 2^48 ≈ 2.8e14，按每场景每秒生成 100 万个实体算也要 8 年才回绕。
type EntityID uint64

// PlayerID 是全服唯一角色 ID，与 EntityID 不是一回事：
// 玩家离线时角色没有实体，但 PlayerID 始终存在。
type PlayerID uint64

// EntityKind 区分实体的玩法类型，决定它挂哪些组件。
type EntityKind uint8

const (
	KindPlayer EntityKind = iota + 1
	KindMonster
	KindNPC
	KindDrop
	KindProjectile
)

const (
	// seqBits 是序号占用的位数。
	seqBits = 48
	// seqMask 是取低 48 位的掩码。
	seqMask = uint64(1)<<seqBits - 1
	// sceneBits 是场景号占用的位数。
	sceneBits = 16
)

// MakeEntityID 把场景号与场景内序号打包成一个 EntityID。
// 序号超过 48 位会被截断，调用方要保证不会发生。
func MakeEntityID(scene uint16, seq uint64) EntityID {
	return EntityID(uint64(scene)<<seqBits | seq&seqMask)
}

// Scene 返回高 16 位的场景号。
func (id EntityID) Scene() uint16 { return uint16(uint64(id) >> seqBits) }

// Seq 返回低 48 位的场景内序号。
func (id EntityID) Seq() uint64 { return uint64(id) & seqMask }

t0   Spawn      →  序号 42 被玩家 A 占用
t1   技能释放    →  记下目标 = 42，300ms 后结算
t2   A 死亡      →  42 被回收，放回空闲栈
t3   刷怪        →  一只怪 Spawn，复用了序号 42
t4   技能结算    →  按 42 查表 → 查到的是怪，不是 A

// file: internal/entity/handle.go
// tier: L1
// verify: go test ./internal/entity/
package entity

import "strconv"

// Handle 是对 EntityID 的「带代际」引用。
//
// 只用 EntityID 引用实体有一个经典 bug：实体 A 被销毁、它占用的
// 序号被新实体 B 复用，此时任何还握着旧 EntityID 的地方（一个延迟
// 触发的技能、一个还没处理完的网络包）都会误伤 B。这就是 ABA 问题。
//
// 解决办法是给每个序号配一个代际计数 Gen：每复用一次 +1。引用方
// 拿着 (ID, Gen)，运行时查找时同时比对两者，代际不符即判为过期引用。
type Handle struct {
	ID  EntityID
	Gen uint32
}

// String 便于日志与测试输出，形如 "1:42/gen3"。
func (h Handle) String() string {
	return strconv.FormatUint(uint64(h.ID.Scene()), 10) + ":" +
		strconv.FormatUint(h.ID.Seq(), 10) + "/gen" +
		strconv.FormatUint(uint64(h.Gen), 10)
}

// file: internal/entity/runtime.go
// tier: L1
// verify: go test ./internal/entity/
package entity

import (
	"errors"
	"sync"
)

var (
	// ErrStaleHandle 表示句柄的代际与槽位当前代际不符（引用已过期）。
	ErrStaleHandle = errors.New("entity: stale handle")
	// ErrNotFound 表示句柄指向的槽位当前没有活实体。
	ErrNotFound = errors.New("entity: not found")
	// ErrBadScene 表示 EntityID 的场景号与运行时不一致。
	ErrBadScene = errors.New("entity: scene mismatch")
)

// Entity 是实体的最小状态。真实项目里这里会是属性、位置、组件表，
// 本节只保留能验证句柄语义所必需的字段。
type Entity struct {
	Handle Handle
	Kind   EntityKind
	Player PlayerID // 只有玩家实体非 0
	HP     int32
}

// slot 是运行时里的一格。所有实体按序号索引到 slots，复用同一格。
type slot struct {
	gen   uint32 // 代际，每次这格被重新分配就 +1
	alive bool   // 这一格当前是否有活实体
	kind  EntityKind
	ent   *Entity
}

// Runtime 是单场景内的实体表：把 EntityID 映射到实体，并用代际
// 识破过期句柄。所有方法都可并发调用。
type Runtime struct {
	scene uint16

	mu    sync.RWMutex
	slots []slot
	free  []uint64 // 空闲序号栈，复用时从尾部取
	next  uint64   // 从未分配过的下一个序号
	live  int

	alloc   func() *Entity // 载荷分配钩子，nil 表示直接 new；2.2 接对象池
	release func(*Entity)  // 载荷回收钩子，nil 表示交给 GC
}

// NewRuntime 创建一个属于 scene 的实体运行时。
func NewRuntime(scene uint16) *Runtime {
	return &Runtime{scene: scene}
}

// Spawn 分配一个新实体。序号优先复用 free 里的（LIFO），
// 没有可复用的就向后增长。
func (r *Runtime) Spawn(kind EntityKind, player PlayerID) Handle {
	r.mu.Lock()
	defer r.mu.Unlock()

	var seq uint64
	if n := len(r.free); n > 0 {
		seq = r.free[n-1]
		r.free = r.free[:n-1]
	} else {
		seq = r.next
		r.next++
		if seq >= uint64(len(r.slots)) {
			r.slots = append(r.slots, slot{})
		}
	}

	s := &r.slots[seq]
	if s.alive {
		panic("entity: slot reused while alive")
	}
	// 复用时代际 +1；首次分配时 gen 从 0 变 1，这样「零值句柄」
	// 永远不可能是合法的。
	s.gen++
	s.alive = true
	s.kind = kind

	h := Handle{ID: MakeEntityID(r.scene, seq), Gen: s.gen}
	ent := new(Entity)
	if r.alloc != nil {
		ent = r.alloc()
	}
	*ent = Entity{Handle: h, Kind: kind, Player: player}
	s.ent = ent
	r.live++
	return h
}

// Lookup 校验句柄并返回实体。代际不符返回 ErrStaleHandle，
// 槽位空闲返回 ErrNotFound。
func (r *Runtime) Lookup(h Handle) (*Entity, error) {
	if h.ID.Scene() != r.scene {
		return nil, ErrBadScene
	}
	seq := h.ID.Seq()
	r.mu.RLock()
	defer r.mu.RUnlock()
	if seq >= uint64(len(r.slots)) {
		return nil, ErrNotFound
	}
	s := &r.slots[seq]
	if !s.alive {
		return nil, ErrNotFound
	}
	if s.gen != h.Gen {
		return nil, ErrStaleHandle
	}
	return s.ent, nil
}

// Despawn 立即回收实体并把它占用的序号放回 free。代际在此刻不动，
// 等下一次 Spawn 复用这格时再 +1——这样「销毁后、复用前」的
// 过期句柄命中 ErrNotFound，复用后命中 ErrStaleHandle。
func (r *Runtime) Despawn(h Handle) error {
	if h.ID.Scene() != r.scene {
		return ErrBadScene
	}
	seq := h.ID.Seq()
	r.mu.Lock()
	defer r.mu.Unlock()
	if seq >= uint64(len(r.slots)) {
		return ErrNotFound
	}
	s := &r.slots[seq]
	if !s.alive {
		return ErrNotFound
	}
	if s.gen != h.Gen {
		return ErrStaleHandle
	}
	s.alive = false
	ent := s.ent
	s.ent = nil
	r.free = append(r.free, seq)
	r.live--
	if r.release != nil {
		r.release(ent)
	}
	return nil
}

// Len 返回当前活实体数量。
func (r *Runtime) Len() int {
	r.mu.RLock()
	defer r.mu.RUnlock()
	return r.live
}

// Cap 返回已分配的槽位数（含空闲），等于历史最大并发实体数。
func (r *Runtime) Cap() int {
	r.mu.RLock()
	defer r.mu.RUnlock()
	return len(r.slots)
}

=== RUN   TestSpawnLookup
--- PASS: TestSpawnLookup (0.00s)
=== RUN   TestStaleHandleAfterReuse
--- PASS: TestStaleHandleAfterReuse (0.00s)
=== RUN   TestNotFoundAfterDespawn
--- PASS: TestNotFoundAfterDespawn (0.00s)
=== RUN   TestFreeListReuse
--- PASS: TestFreeListReuse (0.00s)
PASS
ok  	aegis/internal/entity	0.220s