《游戏服务端架构·品类、状态与拓扑》7.2 FPS 的专用服、命中判定与延迟补偿

// file: internal/lagcomp/world.go
// tier: L1
// verify: go test ./internal/lagcomp/
package lagcomp

import (
	"errors"
	"fmt"
	"math"
	"time"
)

var (
	ErrEmptyWorld   = errors.New("lagcomp: no snapshots recorded")
	ErrTooOld       = errors.New("lagcomp: shot timestamp outside rewind window")
	ErrFuture       = errors.New("lagcomp: shot timestamp ahead of newest snapshot")
	ErrNonMonotonic = errors.New("lagcomp: snapshot time is not increasing")
	ErrBadShot      = errors.New("lagcomp: zero direction or non-positive range")
	ErrNoHit        = errors.New("lagcomp: no target on the rewound ray")
)

// Vec3 is a world-space position in meters. The book keeps it plain so the
// rewind logic stays independent of any engine math library.
type Vec3 struct{ X, Y, Z float64 }

func (v Vec3) Add(o Vec3) Vec3      { return Vec3{v.X + o.X, v.Y + o.Y, v.Z + o.Z} }
func (v Vec3) Sub(o Vec3) Vec3      { return Vec3{v.X - o.X, v.Y - o.Y, v.Z - o.Z} }
func (v Vec3) Scale(s float64) Vec3 { return Vec3{v.X * s, v.Y * s, v.Z * s} }
func (v Vec3) Dot(o Vec3) float64   { return v.X*o.X + v.Y*o.Y + v.Z*o.Z }
func (v Vec3) Len() float64         { return math.Sqrt(v.Dot(v)) }

// PlayerState is the minimum server-authoritative data needed for hitscan:
// position at a timestamp plus the target's collision radius.
type PlayerState struct {
	ID     uint32
	Pos    Vec3
	Radius float64
}

// Snapshot is the world at one server time. Time is measured from match start,
// not wall clock, so replay and audit do not depend on the machine's clock.
type Snapshot struct {
	At      time.Duration
	Players []PlayerState
}

// World is a fixed-size ring of snapshots. Capacity is the number of snapshots
// retained; Window is the gameplay rule for how far back a shot may rewind.
// They are separate because storage may outlive the rule, but a shot must not.
type World struct {
	window time.Duration
	ring   []Snapshot
	head   int
	count  int
}

// New builds a world that keeps up to capacity snapshots and permits rewinds
// no older than window.
func New(window time.Duration, capacity int) *World {
	if window < 0 {
		window = 0
	}
	if capacity < 1 {
		capacity = 1
	}
	return &World{window: window, ring: make([]Snapshot, capacity)}
}

// Record appends a snapshot. Times must increase; a duplicate or backwards
// timestamp is a writer bug, not a network reorder, and is rejected.
func (w *World) Record(at time.Duration, players []PlayerState) error {
	if w.count > 0 && at <= w.at(w.count-1).At {
		return fmt.Errorf("%w: %s after %s", ErrNonMonotonic, at, w.at(w.count-1).At)
	}
	snap := Snapshot{At: at, Players: append([]PlayerState(nil), players...)}
	if w.count == len(w.ring) {
		w.ring[w.head] = snap
		w.head = (w.head + 1) % len(w.ring)
		return nil
	}
	w.ring[(w.head+w.count)%len(w.ring)] = snap
	w.count++
	return nil
}

func (w *World) at(i int) Snapshot {
	return w.ring[(w.head+i)%len(w.ring)]
}

// Rewind returns the newest snapshot at or before at. The snapshot is copied
// so a caller cannot mutate history while resolving a shot.
func (w *World) Rewind(at time.Duration) (Snapshot, error) {
	if w.count == 0 {
		return Snapshot{}, ErrEmptyWorld
	}
	newest := w.at(w.count - 1)
	if at > newest.At {
		return Snapshot{}, fmt.Errorf("%w: shot=%s newest=%s", ErrFuture, at, newest.At)
	}
	if newest.At-at > w.window {
		return Snapshot{}, fmt.Errorf("%w: age=%s window=%s", ErrTooOld, newest.At-at, w.window)
	}
	var best Snapshot
	found := false
	for i := 0; i < w.count; i++ {
		s := w.at(i)
		if s.At > at {
			break
		}
		best, found = s, true
	}
	if !found {
		return Snapshot{}, fmt.Errorf("%w: shot=%s oldest=%s", ErrTooOld, at, w.at(0).At)
	}
	return Snapshot{At: best.At, Players: append([]PlayerState(nil), best.Players...)}, nil
}

// Shot is a client-reported hitscan. At is the client's view of when the shot
// happened; the server rewinds targets to that instant. Origin and Dir are in
// the same world space as PlayerState.Pos.
type Shot struct {
	Shooter  uint32
	Origin   Vec3
	Dir      Vec3
	MaxRange float64
	At       time.Duration
}

// Hit reports the nearest target along the ray after rewinding.
type Hit struct {
	Target    uint32
	Point     Vec3
	Distance  float64
	RewoundTo time.Duration
}

// Hitscan rewinds the world to the shot time and intersects the ray against
// every other player's collision sphere. The nearest target along the ray wins;
// this is the server's authority, not the client's claim.
func (w *World) Hitscan(shot Shot) (Hit, error) {
	if shot.MaxRange <= 0 || shot.Dir.Len() == 0 {
		return Hit{}, ErrBadShot
	}
	dir := shot.Dir.Scale(1 / shot.Dir.Len())
	snap, err := w.Rewind(shot.At)
	if err != nil {
		return Hit{}, err
	}
	var best Hit
	found := false
	for _, p := range snap.Players {
		if p.ID == shot.Shooter {
			continue
		}
		t := p.Pos.Sub(shot.Origin).Dot(dir)
		if t < 0 {
			t = 0
		} else if t > shot.MaxRange {
			t = shot.MaxRange
		}
		point := shot.Origin.Add(dir.Scale(t))
		if point.Sub(p.Pos).Len() > p.Radius {
			continue
		}
		if !found || t < best.Distance {
			best = Hit{Target: p.ID, Point: point, Distance: t, RewoundTo: snap.At}
			found = true
		}
	}
	if !found {
		return Hit{}, ErrNoHit
	}
	return best, nil
}

// Bounds exposes the retained time range for metrics and for rejecting shots
// before the expensive loop.
func (w *World) Bounds() (oldest, newest time.Duration, ok bool) {
	if w.count == 0 {
		return 0, 0, false
	}
	return w.at(0).At, w.at(w.count - 1).At, true
}