《MMO 服务器开发》15.2 移动与战斗合法性校验

// file: internal/authority/move.go
// tier: L1
// verify: go test ./internal/authority/ -run 'TestValidateMove|TestCooldown|TestPathBlocked'

package authority

import (
	"math"
	"time"
)

// Vec3 is a world-space position. Y is the up axis.
type Vec3 struct{ X, Y, Z float64 }

// Sub returns v - o.
func (v Vec3) Sub(o Vec3) Vec3 { return Vec3{v.X - o.X, v.Y - o.Y, v.Z - o.Z} }

// Len returns the Euclidean length of v.
func (v Vec3) Len() float64 { return math.Sqrt(v.X*v.X + v.Y*v.Y + v.Z*v.Z) }

// MoveProposal is what the client claims it did between two server ticks. Note
// that "From" is the server's last acknowledged position, not whatever the
// client says it was: the server seeds it, the client only supplies To.
type MoveProposal struct {
	From    Vec3
	To      Vec3
	Elapsed time.Duration
	// Speed is the entity's server-known maximum speed in units per second.
	Speed float64
}

// MoveVerdict is the server's decision for one proposal.
type MoveVerdict struct {
	Allowed bool
	Reason  string
	// SpeedRatio is observed speed / allowed speed. It is the single number
	// 15.3 feeds into the anomaly accumulator.
	SpeedRatio float64
}

// MoveConfig carries the two knobs that matter: a slack multiplier to absorb
// float rounding and scheduling jitter, and a hard displacement ceiling above
// which a single tick is treated as a teleport.
type MoveConfig struct {
	Tolerance         float64
	TeleportThreshold float64
}

func (c MoveConfig) withDefaults() MoveConfig {
	if c.Tolerance <= 0 {
		c.Tolerance = 1.1
	}
	if c.TeleportThreshold <= 0 {
		c.TeleportThreshold = 40
	}
	return c
}

// ValidateMove adjudicates one movement proposal. It is deliberately pure: same
// inputs, same verdict, no clock, no I/O. That is what makes it cheap enough to
// run on every move packet and trivial to unit-test.
func ValidateMove(p MoveProposal, cfg MoveConfig) MoveVerdict {
	cfg = cfg.withDefaults()

	dist := p.To.Sub(p.From).Len()
	if dist > cfg.TeleportThreshold {
		return MoveVerdict{Reason: "teleport: single-tick displacement over threshold"}
	}
	if p.Elapsed <= 0 {
		return MoveVerdict{Reason: "non-positive elapsed time"}
	}
	if p.Speed <= 0 {
		return MoveVerdict{Reason: "no server-known speed for entity"}
	}

	observed := dist / p.Elapsed.Seconds()
	ratio := observed / p.Speed
	if ratio > cfg.Tolerance {
		return MoveVerdict{Reason: "overspeed", SpeedRatio: ratio}
	}
	return MoveVerdict{Allowed: true, SpeedRatio: ratio}
}

// SkillUse is a client's claim that it cast a skill at a given time. The client
// supplies the skill id; the server supplies "now".
type SkillUse struct {
	SkillID uint16
	Caster  uint64
	Now     time.Time
}

// CooldownTracker enforces skill cooldowns on the server. The client UI greys a
// button out, but that is cosmetic: the authoritative "ready at" lives here, so
// a modified client that ignores its own UI gains nothing.
type CooldownTracker struct {
	dur     map[uint16]time.Duration
	readyAt map[uint32]time.Time
}

// NewCooldownTracker builds a tracker from the skill -> duration table.
func NewCooldownTracker(durations map[uint16]time.Duration) *CooldownTracker {
	return &CooldownTracker{
		dur:     durations,
		readyAt: make(map[uint32]time.Time),
	}
}

func cooldownKey(caster uint64, skill uint16) uint32 {
	return uint32(skill)<<16 | uint32(caster&0xffff)
}

// TryUse records a use if the skill is off cooldown. When the skill is still on
// cooldown it returns the remaining time and false, and does not mutate state.
// An unknown skill id is rejected as not-ready.
func (t *CooldownTracker) TryUse(caster uint64, skill uint16, now time.Time) (time.Duration, bool) {
	d, known := t.dur[skill]
	if !known {
		return 0, false
	}
	k := cooldownKey(caster, skill)
	if ready, ok := t.readyAt[k]; ok && now.Before(ready) {
		return ready.Sub(now), false
	}
	t.readyAt[k] = now.Add(d)
	return 0, true
}

// SolidFunc reports whether the grid cell containing (x, z) blocks movement.
type SolidFunc func(x, z int) bool

// PathBlocked samples the segment from -> to on a 1-unit grid and reports
// whether any sampled cell is solid. It is a coarse but cheap conservative
// check. Sampling finer than the wall thickness is what catches a client that
// tries to clip through a thin wall by reporting a straight line across it.
func PathBlocked(from, to Vec3, step float64, solid SolidFunc) bool {
	if step <= 0 {
		step = 1
	}
	d := to.Sub(from)
	dist := d.Len()
	if dist == 0 {
		return solid(int(math.Floor(from.X)), int(math.Floor(from.Z)))
	}
	n := int(dist/step) + 1
	for i := 0; i <= n; i++ {
		f := float64(i) / float64(n)
		x := from.X + d.X*f
		z := from.Z + d.Z*f
		if solid(int(math.Floor(x)), int(math.Floor(z))) {
			return true
		}
	}
	return false
}

// snippet: internal/authority/move_test.go（节选）

// 以最大速度行走、以及容差内的抖动，都必须放行。
{name: "walking at exactly max speed", to: Vec3{6, 0, 0}, elapsed: time.Second, wantOK: true},
{name: "jitter within tolerance", to: Vec3{6.3, 0, 0}, elapsed: time.Second, wantOK: true},
// 3 倍移速、跨图瞬移、零时间，都必须拒绝。
{name: "sprint cheat", to: Vec3{18, 0, 0}, elapsed: time.Second, wantOK: false, wantCause: "overspeed"},
{name: "teleport", to: Vec3{100, 0, 0}, elapsed: time.Second, wantOK: false, wantCause: "teleport"},

// 一条穿过实心墙的直线必须被判为 blocked。
if !PathBlocked(Vec3{0, 0, 0}, Vec3{10, 0, 0}, 0.25, wall) {
	t.Fatal("straight line through the wall must be blocked")
}