《MMO 服务器开发》7.1 掉落表服务

// file: internal/loot/table.go
// tier: L1
// verify: go test ./internal/loot/
package loot

import (
	"errors"
	"math/rand/v2"
	"sort"
)

// ItemID 是配置表里的物品 ID（不是背包内的实例 ID）。
type ItemID uint32

// Entry 是掉落表里的一行：一个候选物品加它被抽中的权重与数量区间。
type Entry struct {
	ItemID ItemID
	Weight uint32 // 相对权重，越大越容易被抽中
	Min    uint32 // 掉落数量下限（含）
	Max    uint32 // 掉落数量上限（含）
}

// Table 是一张掉落表：一组候选条目，每次抽取命中其中一个。
//
// total 是权重总和，在 Build 时算好，Roll 时不再重复求和。
type Table struct {
	ID      string
	Entries []Entry
	total   uint32
}

// Build 校验配置并预计算权重总和。
//
// 掉落表是策划直接编辑的数据，最脏的输入都在这里进来，所以宁可启动时
// 报错，也不要在线上抽出一个权重为 0 或数量倒挂的条目。
func (t *Table) Build() error {
	if len(t.Entries) == 0 {
		return errors.New("loot: 掉落表为空")
	}
	var sum uint32
	for i := range t.Entries {
		e := &t.Entries[i]
		if e.Weight == 0 {
			return errors.New("loot: 条目权重不能为 0")
		}
		if e.Max < e.Min {
			return errors.New("loot: 数量上限小于下限")
		}
		sum += e.Weight
	}
	t.total = sum
	return nil
}

// Total 返回预计算好的权重总和。
func (t *Table) Total() uint32 { return t.total }

// Pick 按权重抽一个条目。
//
// r 必须是该实体自己的 PRNG（见 7.2），不能是全局 rand——同一次掉落
// 要在任意时刻、任意机器上重放出相同结果。
func (t *Table) Pick(r *rand.Rand) (Entry, bool) {
	if t.total == 0 {
		return Entry{}, false
	}
	roll := r.Uint32N(t.total) // [0, total)
	var acc uint32
	for i := range t.Entries {
		acc += t.Entries[i].Weight
		if roll < acc {
			return t.Entries[i], true
		}
	}
	// roll < total 恒成立，正常不可达；兜底返回最后一项。
	return t.Entries[len(t.Entries)-1], true
}

// Count 在该条目的 [Min, Max] 区间内取一个掉落数量。
func (e Entry) Count(r *rand.Rand) uint32 {
	if e.Max <= e.Min {
		return e.Min
	}
	return e.Min + r.Uint32N(e.Max-e.Min+1)
}

// Drop 是一次掉落结算后的结果行：某个物品掉了多少个。
type Drop struct {
	ItemID ItemID
	Count  uint32
}

// Roll 抽 n 次，把同一物品的数量合并成一行，并按 ItemID 升序输出。
//
// 合并与排序是为了让「同样一组抽取」永远产出同样顺序的结果，
// 否则 7.3 的审计指纹会随 map 遍历顺序抖动。
func (t *Table) Roll(r *rand.Rand, n int) []Drop {
	if n <= 0 {
		return nil
	}
	agg := make(map[ItemID]uint32, len(t.Entries))
	order := make([]ItemID, 0, n)
	for i := 0; i < n; i++ {
		e, ok := t.Pick(r)
		if !ok {
			break
		}
		if _, seen := agg[e.ItemID]; !seen {
			order = append(order, e.ItemID)
		}
		agg[e.ItemID] += e.Count(r)
	}
	sort.Slice(order, func(i, j int) bool { return order[i] < order[j] })
	out := make([]Drop, 0, len(order))
	for _, id := range order {
		out = append(out, Drop{ItemID: id, Count: agg[id]})
	}
	return out
}

// file: internal/loot/table_test.go
// tier: L1
// verify: go test ./internal/loot/
package loot

import (
	"math/rand/v2"
	"testing"
)

func testTable() *Table {
	return &Table{
		ID: "boss_wolf_common",
		Entries: []Entry{
			{ItemID: 1001, Weight: 60, Min: 1, Max: 3}, // 铜币
			{ItemID: 1002, Weight: 30, Min: 1, Max: 1}, // 兽皮
			{ItemID: 1003, Weight: 10, Min: 1, Max: 1}, // 狼牙
		},
	}
}

func TestBuildRejectsBadConfig(t *testing.T) {
	empty := &Table{}
	if err := empty.Build(); err == nil {
		t.Fatal("空表应当报错")
	}
	zero := &Table{Entries: []Entry{{ItemID: 1, Weight: 0, Min: 1, Max: 1}}}
	if err := zero.Build(); err == nil {
		t.Fatal("权重为 0 应当报错")
	}
	inv := &Table{Entries: []Entry{{ItemID: 1, Weight: 1, Min: 5, Max: 2}}}
	if err := inv.Build(); err == nil {
		t.Fatal("数量倒挂应当报错")
	}
}

func TestPickFrequencyMatchesWeight(t *testing.T) {
	tb := testTable()
	if err := tb.Build(); err != nil {
		t.Fatalf("Build: %v", err)
	}
	if tb.Total() != 100 {
		t.Fatalf("权重总和 = %d, 期望 100", tb.Total())
	}
	r := rand.New(rand.NewPCG(1, 2))
	const n = 200000
	hit := map[ItemID]int{}
	for i := 0; i < n; i++ {
		e, ok := tb.Pick(r)
		if !ok {
			t.Fatal("Pick 返回空")
		}
		hit[e.ItemID]++
	}
	// 60/30/10 的权重，允许 ±2% 的统计抖动。
	want := map[ItemID]float64{1001: 0.60, 1002: 0.30, 1003: 0.10}
	for id, w := range want {
		got := float64(hit[id]) / n
		if diff := got - w; diff > 0.02 || diff < -0.02 {
			t.Fatalf("物品 %d 频率 = %.3f, 期望 %.2f", id, got, w)
		}
	}
}

func TestCountWithinRange(t *testing.T) {
	r := rand.New(rand.NewPCG(7, 8))
	e := Entry{ItemID: 1001, Weight: 1, Min: 1, Max: 3}
	seen := map[uint32]bool{}
	for i := 0; i < 1000; i++ {
		c := e.Count(r)
		if c < 1 || c > 3 {
			t.Fatalf("数量 %d 越界", c)
		}
		seen[c] = true
	}
	if len(seen) != 3 {
		t.Fatalf("1..3 三个值应都出现过，实得 %d 个", len(seen))
	}
}

func TestRollAggregatesAndSorts(t *testing.T) {
	tb := testTable()
	if err := tb.Build(); err != nil {
		t.Fatalf("Build: %v", err)
	}
	r := rand.New(rand.NewPCG(3, 4))
	drops := tb.Roll(r, 20)
	if len(drops) == 0 {
		t.Fatal("20 次抽取不该为空")
	}
	var total uint32
	for i, d := range drops {
		total += d.Count
		if i > 0 && drops[i-1].ItemID > d.ItemID {
			t.Fatalf("结果未按 ItemID 升序：%d 在 %d 之后", drops[i-1].ItemID, d.ItemID)
		}
	}
	// 每次抽取数量至少为 1，所以总件数不会少于抽取次数。
	if total < 20 {
		t.Fatalf("总件数 %d 少于抽取次数 20", total)
	}
}