《MMO 服务器开发》12.2 快照与增量编码

// file: internal/sync/snapshot.go
// tier: L1
// verify: go test ./internal/sync/ -run 'TestFullVersusDeltaBytes|TestBaselineMismatchFallsBackToFull' -v

package sync

// FieldMask marks which fields of an entity differ from the baseline.
type FieldMask uint8

const (
	FieldPos FieldMask = 1 << iota
	FieldVel
	FieldHP
	FieldKind
)

// Snapshot is the full authoritative view at a tick.
type Snapshot struct {
	Tick     uint32
	Entities []EntityState
}

// Delta carries only the entities whose fields changed since Baseline.
type Delta struct {
	Tick     uint32
	Baseline uint32
	Entries  []DeltaEntry
}

// DeltaEntry is one entity's changed fields.
type DeltaEntry struct {
	ID   uint32
	Mask FieldMask
	St   EntityState
}

// Diff computes the delta between two full snapshots. A field is dirty when its
// wire bytes differ; nothing is inferred from "the entity moved a bit".
func Diff(base, cur Snapshot) Delta {
	prev := make(map[uint32]EntityState, len(base.Entities))
	for _, e := range base.Entities {
		prev[e.ID] = e
	}
	d := Delta{Tick: cur.Tick, Baseline: base.Tick}
	for _, e := range cur.Entities {
		old, ok := prev[e.ID]
		var mask FieldMask
		if !ok {
			mask = FieldPos | FieldVel | FieldHP | FieldKind // newly visible: full entry
		} else {
			if e.Pos != old.Pos {
				mask |= FieldPos
			}
			if e.Vel != old.Vel {
				mask |= FieldVel
			}
			if e.HP != old.HP {
				mask |= FieldHP
			}
			if e.Kind != old.Kind {
				mask |= FieldKind
			}
		}
		if mask != 0 {
			d.Entries = append(d.Entries, DeltaEntry{ID: e.ID, Mask: mask, St: e})
		}
	}
	return d
}

// file: internal/sync/encode.go
// tier: L1
// verify: go test ./internal/sync/ -run 'TestFullVersusDeltaBytes|TestBaselineMismatchFallsBackToFull' -v

package sync

import (
	"encoding/binary"
	"math"
)

// CmdAttrSync is the world-module command used to push entity state, taken from
// the volume-wide protocol table (world module 0x01, command 0x03).
const CmdAttrSync uint16 = 0x0103

// HeaderSize is the shared frame header: length(4) | cmd(2) | seq(4) | flags(1).
const HeaderSize = 11

// putHeader writes the shared 11-byte frame header. n is the payload length.
func putHeader(dst []byte, cmd uint16, seq uint32, n int) {
	binary.BigEndian.PutUint32(dst[0:], uint32(7+n))
	binary.BigEndian.PutUint16(dst[4:], cmd)
	binary.BigEndian.PutUint32(dst[6:], seq)
	dst[10] = 0
}

// entityStateSize is the fixed cost of one entity in a full snapshot:
// id(4) + pos(8) + vel(8) + hp(2) + kind(1).
const entityStateSize = 23

// EncodeFull renders a full snapshot: header, tick, count, then every entity.
func EncodeFull(s Snapshot, seq uint32) []byte {
	payload := 4 + 2 + len(s.Entities)*entityStateSize
	buf := make([]byte, HeaderSize+payload)
	putHeader(buf, CmdAttrSync, seq, payload)
	off := HeaderSize
	binary.BigEndian.PutUint32(buf[off:], s.Tick)
	off += 4
	binary.BigEndian.PutUint16(buf[off:], uint16(len(s.Entities)))
	off += 2
	for _, e := range s.Entities {
		off = putEntity(buf, off, e)
	}
	return buf
}

func putEntity(dst []byte, off int, e EntityState) int {
	binary.BigEndian.PutUint32(dst[off:], e.ID)
	off += 4
	binary.BigEndian.PutUint32(dst[off:], math.Float32bits(e.Pos.X))
	off += 4
	binary.BigEndian.PutUint32(dst[off:], math.Float32bits(e.Pos.Y))
	off += 4
	binary.BigEndian.PutUint32(dst[off:], math.Float32bits(e.Vel.X))
	off += 4
	binary.BigEndian.PutUint32(dst[off:], math.Float32bits(e.Vel.Y))
	off += 4
	binary.BigEndian.PutUint16(dst[off:], uint16(e.HP))
	off += 2
	dst[off] = e.Kind
	off++
	return off
}

// EncodeDelta renders only the changed fields of only the changed entities.
func EncodeDelta(d Delta, seq uint32) []byte {
	payload := 4 + 4 + 2
	for _, e := range d.Entries {
		payload += 5 + fieldBytes(e.Mask)
	}
	buf := make([]byte, HeaderSize+payload)
	putHeader(buf, CmdAttrSync, seq, payload)
	off := HeaderSize
	binary.BigEndian.PutUint32(buf[off:], d.Tick)
	off += 4
	binary.BigEndian.PutUint32(buf[off:], d.Baseline)
	off += 4
	binary.BigEndian.PutUint16(buf[off:], uint16(len(d.Entries)))
	off += 2
	for _, e := range d.Entries {
		binary.BigEndian.PutUint32(buf[off:], e.ID)
		off += 4
		buf[off] = byte(e.Mask)
		off++
		if e.Mask&FieldPos != 0 {
			binary.BigEndian.PutUint32(buf[off:], math.Float32bits(e.St.Pos.X))
			off += 4
			binary.BigEndian.PutUint32(buf[off:], math.Float32bits(e.St.Pos.Y))
			off += 4
		}
		if e.Mask&FieldVel != 0 {
			binary.BigEndian.PutUint32(buf[off:], math.Float32bits(e.St.Vel.X))
			off += 4
			binary.BigEndian.PutUint32(buf[off:], math.Float32bits(e.St.Vel.Y))
			off += 4
		}
		if e.Mask&FieldHP != 0 {
			binary.BigEndian.PutUint16(buf[off:], uint16(e.St.HP))
			off += 2
		}
		if e.Mask&FieldKind != 0 {
			buf[off] = e.St.Kind
			off++
		}
	}
	return buf
}

// fieldBytes is the payload size of one entity's dirty fields.
func fieldBytes(m FieldMask) int {
	n := 0
	if m&FieldPos != 0 {
		n += 8
	}
	if m&FieldVel != 0 {
		n += 8
	}
	if m&FieldHP != 0 {
		n += 2
	}
	if m&FieldKind != 0 {
		n++
	}
	return n
}

// snippet: internal/sync/replicator.go（节选）

// FrameFor returns the next frame for one client and whether it was a delta.
// The second return value is the honest answer to "did this client pay full
// price this tick?" and is what the bandwidth budget in 12.3 counts.
func (r *Replicator) FrameFor(clientID uint32, seq uint32) ([]byte, bool) {
	if !r.ready {
		return nil, false
	}
	if r.acked[clientID] == r.prev.Tick {
		return EncodeDelta(Diff(r.prev, r.cur), seq), true
	}
	return EncodeFull(r.cur, seq), false
}