《MMO 服务器开发》8.1 物品与堆叠模型

// file: internal/inventory/item.go
// tier: L1
// verify: go test ./internal/inventory/
// Package inventory 实现 aegis 单服《晨曦大陆》的背包与道具系统：
// 物品堆叠模型、并发事务化修改、装备与强化。
package inventory

import "errors"

// ItemID 是配置表物品 ID（不是实例 ID）；同一件「小血瓶」全服共用一个 ItemID。
type ItemID uint32

// ItemInstID 是背包内物品实例 ID。同种物品的每个堆叠各有独立实例号，
// 强化等级、绑定状态这类「个体差异」都挂在实例上。
type ItemInstID uint64

// ItemType 物品大类。
type ItemType uint8

const (
	TypeMaterial   ItemType = iota // 材料：可堆叠，不直接使用
	TypeConsumable                 // 消耗品：可堆叠，使用后减少数量
	TypeEquipment                  // 装备：不可堆叠，每件占一格
)

// EquipSlot 装备位。
type EquipSlot uint8

const (
	SlotNone   EquipSlot = iota
	SlotWeapon           // 武器
	SlotHelmet           // 头盔
	SlotArmor            // 护甲
	SlotBoots            // 靴子
)

// ItemDef 是配置表里一条物品定义，进程内只读、被所有角色共享。
type ItemDef struct {
	ID       ItemID
	Name     string
	Type     ItemType
	MaxStack int       // 每格最大堆叠数；装备固定为 1
	Slot     EquipSlot // 可穿戴槽位；非装备为 SlotNone
}

// Stackable 表示该物品能否堆叠。
func (d ItemDef) Stackable() bool { return d.MaxStack > 1 }

// ItemStack 是背包里的一格：一个物品实例。
type ItemStack struct {
	Inst    ItemInstID // 实例 ID
	ID      ItemID     // 配置表 ID
	Count   int        // 本格数量
	Bound   bool       // 绑定后不可交易
	Enhance int        // 强化等级（0 表示未强化）
}

// Catalog 是只读的物品配置表。
type Catalog struct{ defs map[ItemID]ItemDef }

// NewCatalog 用给定定义构造配置表。
func NewCatalog(defs ...ItemDef) *Catalog {
	m := make(map[ItemID]ItemDef, len(defs))
	for _, d := range defs {
		m[d.ID] = d
	}
	return &Catalog{defs: m}
}

// Get 取一条定义。
func (c *Catalog) Get(id ItemID) (ItemDef, bool) { d, ok := c.defs[id]; return d, ok }

// 背包与道具相关的错误。调用方据错误值分流，不靠字符串匹配。
var (
	ErrUnknown    = errors.New("inventory: unknown item id")
	ErrNoSpace    = errors.New("inventory: bag has no space")
	ErrNotEnough  = errors.New("inventory: not enough items")
	ErrNotEquip   = errors.New("inventory: item is not equipment")
	ErrNotInBag   = errors.New("inventory: instance not in bag")
	ErrMaxEnhance = errors.New("inventory: already at max enhance level")
)

// bagState 是背包的全部可变状态。事务通过整体替换它获得原子性：
// 改动发生在副本上，提交时一次性换指针，失败则丢弃副本。
type bagState struct {
	slots    []*ItemStack             // 定长背包槽位，nil 为空格
	equip    map[EquipSlot]*ItemStack // 已穿戴装备
	index    map[ItemInstID]int       // 背包内实例 ID → 槽位下标
	nextInst ItemInstID               // 下一个可分配的实例号
}

func newBagState(slots int) *bagState {
	return &bagState{
		slots: make([]*ItemStack, slots),
		equip: make(map[EquipSlot]*ItemStack),
		index: make(map[ItemInstID]int),
	}
}

// add 把 count 个 id 放进背包：可堆叠的先补已有堆叠，再开新格；
// 不可堆叠的每件占一格。先做容量预检，放不下就整体不动并返回 ErrNoSpace。
func (s *bagState) add(cat *Catalog, id ItemID, count int) error {
	def, ok := cat.Get(id)
	if !ok {
		return ErrUnknown
	}
	if count <= 0 {
		return nil
	}
	// 预检：先算已有堆叠能补多少，再算要开几格。
	room := 0
	if def.Stackable() {
		for _, st := range s.slots {
			if st != nil && st.ID == id && !st.Bound && st.Count < def.MaxStack {
				room += def.MaxStack - st.Count
			}
		}
	}
	if need := count - room; need > 0 {
		per := 1
		if def.Stackable() {
			per = def.MaxStack
		}
		if needSlots := (need + per - 1) / per; needSlots > s.emptyCount() {
			return ErrNoSpace
		}
	}
	// 预检通过才落盘：先补已有堆叠，从低槽位开始，保证结果可预期。
	if def.Stackable() {
		for _, st := range s.slots {
			if count == 0 {
				break
			}
			if st != nil && st.ID == id && !st.Bound && st.Count < def.MaxStack {
				n := min(def.MaxStack-st.Count, count)
				st.Count += n
				count -= n
			}
		}
	}
	for count > 0 {
		slot := s.firstEmpty()
		n := 1
		if def.Stackable() {
			n = min(def.MaxStack, count)
		}
		s.put(slot, def, n)
		count -= n
	}
	return nil
}

// remove 按配置表 ID 扣减 count 个。数量不足时先返回错误、不做任何改动。
func (s *bagState) remove(cat *Catalog, id ItemID, count int) error {
	if count <= 0 {
		return nil
	}
	if s.Count(id) < count {
		return ErrNotEnough
	}
	for i, st := range s.slots {
		if count == 0 {
			break
		}
		if st == nil || st.ID != id {
			continue
		}
		if st.Count <= count {
			count -= st.Count
			s.clearSlot(i)
		} else {
			st.Count -= count
			count = 0
		}
	}
	return nil
}

// Count 返回背包内某配置表物品的总数量（不含已穿戴装备）。
func (s *bagState) Count(id ItemID) int {
	n := 0
	for _, st := range s.slots {
		if st != nil && st.ID == id {
			n += st.Count
		}
	}
	return n
}

// Snapshot 返回背包槽位的值拷贝，供只读展示使用。
func (s *bagState) Snapshot() []ItemStack {
	out := make([]ItemStack, 0, len(s.slots))
	for _, st := range s.slots {
		if st != nil {
			out = append(out, *st)
		}
	}
	return out
}

func (s *bagState) clearSlot(i int) {
	if st := s.slots[i]; st != nil {
		delete(s.index, st.Inst)
		s.slots[i] = nil
	}
}

func (s *bagState) firstEmpty() int {
	for i, st := range s.slots {
		if st == nil {
			return i
		}
	}
	return -1
}

func (s *bagState) emptyCount() int {
	n := 0
	for _, st := range s.slots {
		if st == nil {
			n++
		}
	}
	return n
}

func (s *bagState) put(slot int, def ItemDef, count int) {
	s.nextInst++
	s.slots[slot] = &ItemStack{Inst: s.nextInst, ID: def.ID, Count: count}
	s.index[s.nextInst] = slot
}