《MMO 服务器开发》18.1 把玩法系统接进 aegis

// file: internal/gameplay/wire.go
// tier: L1
// verify: go test ./internal/gameplay/
package gameplay

import (
	"encoding/binary"
	"fmt"
	"sort"
)

// Session 是一个在线会话：角色、运行时实体与所在实例。玩法逻辑用它定位玩家实体。
type Session struct {
	PlayerID PlayerID
	Entity   EntityID
	Instance InstanceID
}

// Handler 处理一条已解码的帧，返回应答帧（nil 表示无应答，例如纯通知）。
type Handler func(s *Session, f *Frame) (*Frame, error)

// Registry 是命令号 -> handler 的路由表。卷二把每个玩法命令注册进来，
// 复用卷一「cmd → handler」的分发模型，而不是另起一套。
type Registry struct {
	handlers map[uint16]Handler
}

// NewRegistry 建一张空路由表。
func NewRegistry() *Registry { return &Registry{handlers: make(map[uint16]Handler)} }

// Register 注册一条命令。同一命令号注册两次会返回 ErrDuplicateCommand——
// 这是防「两个玩法抢同一个命令号」的断言。
func (r *Registry) Register(cmd uint16, h Handler) error {
	if _, dup := r.handlers[cmd]; dup {
		return fmt.Errorf("%w: 0x%04X", ErrDuplicateCommand, cmd)
	}
	r.handlers[cmd] = h
	return nil
}

// Commands 返回已注册的命令号（有序）。
func (r *Registry) Commands() []uint16 {
	out := make([]uint16, 0, len(r.handlers))
	for cmd := range r.handlers {
		out = append(out, cmd)
	}
	sort.Slice(out, func(i, j int) bool { return out[i] < out[j] })
	return out
}

// Has 报告某命令号是否已注册。
func (r *Registry) Has(cmd uint16) bool {
	_, ok := r.handlers[cmd]
	return ok
}

// Dispatch 分发一条帧到对应 handler，返回应答帧。未注册则报错。
func (r *Registry) Dispatch(s *Session, f *Frame) (*Frame, error) {
	h, ok := r.handlers[f.Cmd]
	if !ok {
		return nil, fmt.Errorf("gameplay: no handler for cmd 0x%04X", f.Cmd)
	}
	return h(s, f)
}

// respFrame 用请求的 seq 组一条应答帧。
func respFrame(req *Frame, cmd uint16, payload []byte) *Frame {
	return &Frame{Cmd: cmd, Seq: req.Seq, Flags: req.Flags, Payload: payload}
}

// u64 把负载当单个 uint64 读（不足补零）。
func u64(p []byte) uint64 {
	var b [8]byte
	copy(b[:], p)
	return binary.BigEndian.Uint64(b[:])
}

// putU64 把 uint64 编码成 8 字节大端。
func putU64(v uint64) []byte {
	return binary.BigEndian.AppendUint64(nil, v)
}

// putU32 把 uint32 编码成 4 字节大端。
func putU32(v uint32) []byte {
	return binary.BigEndian.AppendUint32(nil, v)
}

// snippet: 卷二新增的玩法域命令号（0x04–0x0C），全卷统一
const (
	CmdSkillCastReq   uint16 = 0x0401 // 战斗
	CmdItemUseReq     uint16 = 0x0501 // 背包
	CmdQuestAcceptReq uint16 = 0x0601 // 任务
	CmdQuestFinishReq uint16 = 0x0603
	CmdPartyInviteReq uint16 = 0x0701 // 组队
	CmdGuildJoinReq   uint16 = 0x0801 // 公会
	CmdRankQueryReq   uint16 = 0x0901 // 排行
	CmdMailListReq    uint16 = 0x0A01 // 邮件
	CmdAuctionBidReq  uint16 = 0x0B02 // 交易
	CmdMatchJoinReq   uint16 = 0x0C01 // 匹配
)

// snippet: Server 把玩法域装成一个「一个进程、一个世界」
type Server struct {
	World     *World      // 场景实例：实体 + 九宫格 AOI
	Combat    *Combat     // 战斗管线：冷却 + 伤害结算
	Loot      *Loot       // 掉落服务：掉落物 + 到期回收
	LootTable *LootTable  // 掉落表
	Reg       *Registry   // 路由表
	byPlay    map[PlayerID]EntityID
	bags      map[PlayerID]*Bag
	quests    map[PlayerID]*QuestLog
	parties   map[PartyID]*Party
}

// Wire 把所有玩法命令注册进路由表。装配完成即端到端可用。
func (s *Server) Wire() error {
	regs := []struct {
		cmd uint16
		h   Handler
	}{
		{CmdSkillCastReq, s.handleSkillCast},
		{CmdItemUseReq, s.handleItemUse},
		{CmdQuestAcceptReq, s.handleQuestAccept},
		{CmdQuestFinishReq, s.handleQuestFinish},
		{CmdPartyInviteReq, s.handlePartyInvite},
	}
	for _, r := range regs {
		if err := s.Reg.Register(r.cmd, r.h); err != nil {
			return err
		}
	}
	return nil
}

// snippet: 击杀落地掉落、拾取入包，副作用都写在 handler 里
func (s *Server) handleSkillCast(sess *Session, f *Frame) (*Frame, error) {
	target := EntityID(u64(f.Payload))
	dmg, killed := s.Combat.Cast(s.skill, sess.Entity, target)
	if killed {
		items := s.LootTable.Roll(sess.PlayerID, s.Combat.tick, 1)
		s.Loot.SpawnDrops(sess.PlayerID, items, 50) // 击杀 -> 落地掉落物
	}
	payload := putU32(uint32(dmg))
	if killed {
		payload = append(payload, 1)
	} else {
		payload = append(payload, 0)
	}
	return respFrame(f, CmdSkillCastResp, payload), nil
}

func (s *Server) handleItemUse(sess *Session, f *Frame) (*Frame, error) {
	item, ok := s.Loot.Pickup(u64(f.Payload)) // 拾取即从掉落表移除，重复拾取失败
	if ok {
		s.Bag(sess.PlayerID).Add(item, 1) // 拾取 -> 入包
	}
	payload := putU32(uint32(item))
	if ok {
		payload = append(payload, 1)
	} else {
		payload = append(payload, 0)
	}
	return respFrame(f, CmdItemUseResp, payload), nil
}

// file: internal/gameplay/frame_test.go
// tier: L1
// verify: go test ./internal/gameplay/
package gameplay

import (
	"bytes"
	"testing"
)

// TestFrameRoundTrip 断言帧的编码 / 解码 / 读取一致：粘包由长度前缀保证。
func TestFrameRoundTrip(t *testing.T) {
	f := &Frame{Cmd: CmdSkillCastReq, Seq: 42, Flags: 1, Payload: putU64(7)}
	var buf bytes.Buffer
	buf.Write(Header{Length: uint32(7 + len(f.Payload)), Cmd: f.Cmd, Seq: f.Seq, Flags: f.Flags}.EncodeInto(nil))
	buf.Write(f.Payload)

	got, err := ReadFrame(&buf)
	if err != nil {
		t.Fatalf("ReadFrame: %v", err)
	}
	if got.Cmd != f.Cmd || got.Seq != f.Seq || got.Flags != f.Flags {
		t.Fatalf("帧头不一致：%+v", got)
	}
	if u64(got.Payload) != 7 {
		t.Fatalf("负载 = %d, 期望 7", u64(got.Payload))
	}
}

$ go test -run 'TestWire|TestRegister|TestDispatch' -v ./internal/gameplay/
=== RUN   TestWireRegistersGameplayCommands
--- PASS: TestWireRegistersGameplayCommands (0.00s)
=== RUN   TestRegisterRejectsDuplicate
--- PASS: TestRegisterRejectsDuplicate (0.00s)
=== RUN   TestDispatchSkillCast
--- PASS: TestDispatchSkillCast (0.00s)
=== RUN   TestDispatchUnknownCommand
--- PASS: TestDispatchUnknownCommand (0.00s)
PASS
ok  	aegis/internal/gameplay	0.198s