《游戏服务端编程实践》9.1.1 物品与堆叠模型

// file: ch09/bag/item.go
// tier: L1
// verify: go test ./ch09/bag/

package bag

import (
	"errors"
	"fmt"
	"time"
)

// ItemDef 是物品定义：所有同类物品共享，不随实例变化。
// MaxStack 为 1 表示不可堆叠；Expire 为 0 表示永久。
type ItemDef struct {
	ID       string
	Name     string
	MaxStack int
	Bind     bool
	Expire   time.Duration
}

// Item 是物品实例：instanceID 唯一，itemID 指向定义。
type Item struct {
	InstanceID uint64
	ItemID     string
	Count      int
	Bound      bool
	ExpireAt   time.Time
}

var (
	ErrUnknownItem  = errors.New("bag: unknown item")
	ErrBadCount     = errors.New("bag: bad item count")
	ErrNoSpace      = errors.New("bag: not enough space")
	ErrBadSlot      = errors.New("bag: slot out of range")
	ErrEmptySlot    = errors.New("bag: slot is empty")
	ErrBadCapacity  = errors.New("bag: capacity must be positive")
	ErrNotMergeable = errors.New("bag: items cannot merge")
)

// Bag 是有序槽位背包。槽位索引稳定：删除物品不会移动其他槽位，
// 这样客户端可以用槽位号引用物品而不会错位。
type Bag struct {
	defs   map[string]ItemDef
	slots  []*Item
	nextID uint64
}

func NewBag(defs []ItemDef, capacity int) (*Bag, error) {
	if capacity <= 0 {
		return nil, ErrBadCapacity
	}
	byID := make(map[string]ItemDef, len(defs))
	for _, d := range defs {
		if d.MaxStack <= 0 {
			d.MaxStack = 1
		}
		byID[d.ID] = d
	}
	return &Bag{defs: byID, slots: make([]*Item, capacity)}, nil
}

func (b *Bag) Capacity() int { return len(b.slots) }

func (b *Bag) At(slot int) (Item, bool) {
	if slot < 0 || slot >= len(b.slots) || b.slots[slot] == nil {
		return Item{}, false
	}
	return *b.slots[slot], true
}

func (b *Bag) allocID() uint64 {
	b.nextID++
	return b.nextID
}

// fillable 判断已有堆能否继续容纳：物品相同、绑定状态相同、
// 到期时间相同且未达上限。绑定物品不与未绑定物品混堆。
func fillable(it *Item, itemID string, bound bool, expire time.Time, max int) bool {
	return it != nil && it.ItemID == itemID && it.Bound == bound &&
		it.Count < max && it.ExpireAt.Equal(expire)
}

// Add 以事务方式加入物品：放不下时返回 ErrNoSpace 且背包不变。
// 先填已有堆，再占用空槽，返回实际使用的槽位。
func (b *Bag) Add(itemID string, count int, bound bool, now time.Time) ([]int, error) {
	if count <= 0 {
		return nil, ErrBadCount
	}
	def, ok := b.defs[itemID]
	if !ok {
		return nil, fmt.Errorf("%w: %s", ErrUnknownItem, itemID)
	}
	bound = bound || def.Bind
	var expire time.Time
	if def.Expire > 0 {
		expire = now.Add(def.Expire)
	}

	free := 0
	for _, it := range b.slots {
		switch {
		case it == nil:
			free += def.MaxStack
		case fillable(it, itemID, bound, expire, def.MaxStack):
			free += def.MaxStack - it.Count
		}
	}
	if free < count {
		return nil, fmt.Errorf("%w: need %d, free %d", ErrNoSpace, count, free)
	}

	remaining := count
	var used []int
	for i, it := range b.slots {
		if remaining == 0 {
			break
		}
		if !fillable(it, itemID, bound, expire, def.MaxStack) {
			continue
		}
		n := min(def.MaxStack-it.Count, remaining)
		it.Count += n
		remaining -= n
		used = append(used, i)
	}
	for i, it := range b.slots {
		if remaining == 0 {
			break
		}
		if it != nil {
			continue
		}
		n := min(def.MaxStack, remaining)
		b.slots[i] = &Item{
			InstanceID: b.allocID(),
			ItemID:     itemID,
			Count:      n,
			Bound:      bound,
			ExpireAt:   expire,
		}
		remaining -= n
		used = append(used, i)
	}
	return used, nil
}

// Remove 从指定槽位取走 count 个，返回被取走的实例快照。
// 取空后槽位置空，其他槽位索引保持不变。
func (b *Bag) Remove(slot, count int) (Item, error) {
	if slot < 0 || slot >= len(b.slots) {
		return Item{}, ErrBadSlot
	}
	it := b.slots[slot]
	if it == nil {
		return Item{}, ErrEmptySlot
	}
	if count <= 0 || count > it.Count {
		return Item{}, ErrBadCount
	}
	removed := *it
	removed.Count = count
	it.Count -= count
	if it.Count == 0 {
		b.slots[slot] = nil
	}
	return removed, nil
}

// Split 从槽位拆出 count 个到第一个空槽，返回新槽位号。
// 拆分数必须小于原堆数量，避免产生空堆。
func (b *Bag) Split(slot, count int) (int, error) {
	if slot < 0 || slot >= len(b.slots) {
		return -1, ErrBadSlot
	}
	it := b.slots[slot]
	if it == nil {
		return -1, ErrEmptySlot
	}
	if count <= 0 || count >= it.Count {
		return -1, ErrBadCount
	}
	target := b.firstEmpty()
	if target < 0 {
		return -1, ErrNoSpace
	}
	moved := *it
	moved.InstanceID = b.allocID()
	moved.Count = count
	it.Count -= count
	b.slots[target] = &moved
	return target, nil
}

// Merge 把 from 槽合并进 to 槽，允许部分合并；from 为空后置空。
// 只有 itemID、绑定状态、到期时间都一致才允许合并。
func (b *Bag) Merge(from, to int) error {
	if from == to || from < 0 || to < 0 || from >= len(b.slots) || to >= len(b.slots) {
		return ErrBadSlot
	}
	src, dst := b.slots[from], b.slots[to]
	if src == nil || dst == nil {
		return ErrEmptySlot
	}
	def, ok := b.defs[src.ItemID]
	if !ok || src.ItemID != dst.ItemID || src.Bound != dst.Bound ||
		!src.ExpireAt.Equal(dst.ExpireAt) {
		return ErrNotMergeable
	}
	room := def.MaxStack - dst.Count
	if room <= 0 {
		return ErrNotMergeable
	}
	n := min(room, src.Count)
	dst.Count += n
	src.Count -= n
	if src.Count == 0 {
		b.slots[from] = nil
	}
	return nil
}

func (b *Bag) firstEmpty() int {
	for i, it := range b.slots {
		if it == nil {
			return i
		}
	}
	return -1
}