《MMO 服务器开发》6.2 技能与 Buff 建模

// file: internal/combat/skill.go
// tier: L1
// verify: go test ./internal/combat/ -run 'TestSkill' -v

package combat

import "errors"

// Vec2 is the server's floating-point logical coordinate. It is deliberately
// separate from client pixel coordinates; range checks below are in these units.
type Vec2 struct {
	X, Y float64
}

// SkillDef is the immutable config-table view of a skill: in production it is
// an export of a spreadsheet, here a plain struct so a test can build one.
type SkillDef struct {
	ID         uint32
	Name       string
	Range      float64 // max cast distance, logical units
	CastTicks  int     // wind-up before the hit lands
	Cooldown   int     // ticks before this skill may be cast again
	GCD        int     // global cooldown this cast imposes on every skill
	BaseDamage int
}

// CastRequest is a decoded, pre-validation intent.
type CastRequest struct {
	Caster EntityID
	Target EntityID
	Skill  uint32
	Tick   int64
}

// Cast is a validated cast: the hit lands CastTicks after the request tick.
type Cast struct {
	Caster EntityID
	Target EntityID
	Skill  uint32
	LandAt int64
	Damage int
}

// Sentinel errors let the caller map a rejected cast back onto a wire error.
var (
	ErrUnknownSkill = errors.New("combat: unknown skill")
	ErrOutOfRange   = errors.New("combat: target out of range")
	ErrOnCooldown   = errors.New("combat: skill on cooldown")
	ErrGCD          = errors.New("combat: global cooldown")
)

// castState tracks the cooldowns of one entity.
type castState struct {
	lastCast map[uint32]int64
	lastGCD  int64
}

// SkillEngine owns the skill table and every entity's cooldown state. It is not
// safe for concurrent use: it is driven by the single scene loop.
type SkillEngine struct {
	defs  map[uint32]SkillDef
	state map[EntityID]*castState
}

// NewSkillEngine returns an empty engine.
func NewSkillEngine() *SkillEngine {
	return &SkillEngine{
		defs:  make(map[uint32]SkillDef),
		state: make(map[EntityID]*castState),
	}
}

// Add registers a skill definition.
func (e *SkillEngine) Add(def SkillDef) { e.defs[def.ID] = def }

// Def returns the definition for id.
func (e *SkillEngine) Def(id uint32) (SkillDef, bool) {
	d, ok := e.defs[id]
	return d, ok
}

func (e *SkillEngine) stateFor(id EntityID) *castState {
	st := e.state[id]
	if st == nil {
		st = &castState{lastCast: make(map[uint32]int64), lastGCD: -1 << 62}
		e.state[id] = st
	}
	return st
}

func dist2(a, b Vec2) float64 {
	dx, dy := a.X-b.X, a.Y-b.Y
	return dx*dx + dy*dy
}

// CanCast checks range and both cooldowns at req.Tick without mutating state.
// Splitting it out from Cast lets the scene loop reject a bad cast and reply
// with a specific error code, while the state only advances on a real cast.
func (e *SkillEngine) CanCast(req CastRequest, casterPos, targetPos Vec2) error {
	def, ok := e.defs[req.Skill]
	if !ok {
		return ErrUnknownSkill
	}
	if dist2(casterPos, targetPos) > def.Range*def.Range {
		return ErrOutOfRange
	}
	st := e.stateFor(req.Caster)
	if last, ok := st.lastCast[req.Skill]; ok && req.Tick-last < int64(def.Cooldown) {
		return ErrOnCooldown
	}
	if def.GCD > 0 && req.Tick-st.lastGCD < int64(def.GCD) {
		return ErrGCD
	}
	return nil
}

// Cast validates req and, on success, records the cooldowns and returns the
// resolved Cast. The damage is not applied here: it lands CastTicks later, in
// the settlement step, so a moving target can still be out of range by then.
func (e *SkillEngine) Cast(req CastRequest, casterPos, targetPos Vec2) (Cast, error) {
	if err := e.CanCast(req, casterPos, targetPos); err != nil {
		return Cast{}, err
	}
	def := e.defs[req.Skill]
	st := e.stateFor(req.Caster)
	st.lastCast[req.Skill] = req.Tick
	st.lastGCD = req.Tick
	return Cast{
		Caster: req.Caster,
		Target: req.Target,
		Skill:  req.Skill,
		LandAt: req.Tick + int64(def.CastTicks),
		Damage: def.BaseDamage,
	}, nil
}

// snippet: internal/combat/buff.go（节选，完整文件随本节 L1 测试一起编译）

// BuffInst is one live buff: the stack count, the tick it was applied (Start),
// the tick it expires, and the per-stack DoT/HoT copied from the config table.
//
// Apply puts def on the entity at tick. A brand-new buff starts at one stack; a
// repeat follows the policy: Refresh rewinds it to one stack, Stack grows it by
// one up to MaxStacks (MaxStacks <= 1 means a single stack). Either way the
// expiry is pushed to tick+Duration.
func (b *BuffSet) Apply(def BuffDef, tick int64) {
	inst, ok := b.byID[def.ID]
	if !ok {
		inst = &BuffInst{
			Def:        def.ID,
			Stacks:     1,
			DotPerTick: def.DotPerTick,
			HotPerTick: def.HotPerTick,
		}
		b.byID[def.ID] = inst
		b.order = append(b.order, def.ID)
	} else {
		switch def.Policy {
		case Stack:
			if inst.Stacks < max(1, def.MaxStacks) {
				inst.Stacks++
			}
		default: // Refresh
			inst.Stacks = 1
		}
	}
	inst.Start = tick
	inst.Expires = tick + int64(def.Duration)
}

// Tick advances the set across the half-open interval (prev, tick]. It sums the
// periodic damage and healing that fall inside each buff's own lifetime and
// drops the ones whose expiry has passed. Counts are exact: a buff that expires
// mid-interval only pays for the ticks it was actually alive.
func (b *BuffSet) Tick(prev, tick int64) (dmg, heal int) {
	if tick <= prev {
		return 0, 0
	}
	keep := b.order[:0]
	for _, id := range b.order {
		inst := b.byID[id]
		from := max(prev+1, inst.Start+1)
		to := min(tick, inst.Expires)
		if to >= from {
			n := int(to - from + 1)
			dmg += inst.DotPerTick * inst.Stacks * n
			heal += inst.HotPerTick * inst.Stacks * n
		}
		if inst.Expires <= tick {
			delete(b.byID, id)
			continue
		}
		keep = append(keep, id)
	}
	b.order = keep
	return dmg, heal
}

// snippet: internal/combat/skill_test.go（节选）

func TestSkillCooldownAndGCD(t *testing.T) {
	e := testEngine()
	here := Vec2{0, 0}
	near := Vec2{1, 0}

	c1, err := e.Cast(CastRequest{Caster: 7, Target: 9, Skill: 2, Tick: 100}, here, near)
	if err != nil {
		t.Fatalf("first cast: %v", err)
	}
	if c1.LandAt != 100 {
		t.Fatalf("instant skill LandAt = %d, want 100", c1.LandAt)
	}
	// A different skill inside the GCD window must be refused.
	if _, err := e.Cast(CastRequest{Caster: 7, Target: 9, Skill: 1, Tick: 102}, here, near); err != ErrGCD {
		t.Fatalf("cast inside GCD: err = %v, want ErrGCD", err)
	}
	// Same skill before its own cooldown is over is refused too.
	if _, err := e.Cast(CastRequest{Caster: 7, Target: 9, Skill: 2, Tick: 103}, here, near); err != ErrOnCooldown {
		t.Fatalf("cast on cooldown: err = %v, want ErrOnCooldown", err)
	}
	// Past both cooldowns it succeeds again (tick 105 clears the 5-tick GCD).
	if _, err := e.Cast(CastRequest{Caster: 7, Target: 9, Skill: 2, Tick: 105}, here, near); err != nil {
		t.Fatalf("cast after cooldown: %v", err)
	}
}

// snippet: internal/combat/buff_test.go（节选）

func TestBuffStackCap(t *testing.T) {
	b := NewBuffSet()
	for i := 0; i < 10; i++ {
		b.Apply(poison, int64(i))
	}
	if got := b.Stacks(100); got != 5 {
		t.Fatalf("poison stacks = %d, want cap 5", got)
	}
}

func TestBuffDotTicksExact(t *testing.T) {
	b := NewBuffSet()
	b.Apply(poison, 0) // 3 dmg/stack/tick, one stack, expires at 10
	dmg, heal := b.Tick(0, 5)
	if dmg != 15 || heal != 0 {
		t.Fatalf("ticks 1..5: dmg=%d heal=%d, want 15/0", dmg, heal)
	}
	// Ticks 6..10 are the last five; the buff then expires.
	dmg, _ = b.Tick(5, 12)
	if dmg != 15 {
		t.Fatalf("ticks 6..10: dmg=%d, want 15", dmg)
	}
	if b.Has(100) {
		t.Fatal("poison survived past its expiry")
	}
	// After expiry no further damage is produced.
	if dmg, _ := b.Tick(12, 20); dmg != 0 {
		t.Fatalf("damage after expiry = %d, want 0", dmg)
	}
}