【数据存储】道具堆叠：最大堆叠数与拆分操作

实战应用：用在哪里

药水、矿石、任务材料都会堆叠存放，堆叠规则看似简单，拆分、合并、溢出三个场景最容易出错。传奇引擎的背包是格子制，一格最多堆 999 个，堆叠逻辑写稳了，背包相关的客诉能少一半。

堆叠与合并

local MAX_STACK = 999
function Bag.addItem(plr, itemId, count)
    local def = ITEM_DEF[itemId]
    if not def.stackable then
        return Bag.addUnique(plr, itemId, count)
    end
    for _, slot in pairs(plr.bag) do
        if slot.id == itemId and slot.n < MAX_STACK then
            local take = math.min(MAX_STACK - slot.n, count)
            slot.n = slot.n + take
            count = count - take
            if count == 0 then return true end
        end
    end
    return Bag.newSlots(plr, itemId, count)
end

先填未满的格子再开新格，开新格失败整体回滚。不可堆叠物品每件占一格，批量发放直接按数量找空格。

拆分操作

function Bag.split(plr, slot, n)
    local src = plr.bag[slot]
    if not src or src.n <= n then return false, "数量不足" end
    local free = Bag.findFree(plr)
    if not free then return false, "背包已满" end
    src.n = src.n - n
    plr.bag[free] = { id = src.id, n = n }
    return true
end

拆分要求目标格为空，源格剩余数量大于拆出数量，两个校验缺一不可。交易与寄售挂单时数量校验走同一套堆叠逻辑，读到的数量与扣减的数量必然一致。背包格子用 GUI:GridView 渲染，堆叠数显示在格子右下角，拆分弹窗支持键盘输入与快捷按钮。

踩坑记录

堆叠上限 999 的容量争议在矿工玩家群体里持续了很久，一格 999、八格背包全矿石的存储量撑不过三天产能，大仓库扩展与材料银行两个方案比稿后选了前者。拆分界面的数字输入框曾经允许负数，客户端拦截了但协议层裸奔，服务端校验补上才是真正的防线。堆叠与拆分的状态同步走同一条推送通道，界面与数据的偏差窗口被压到一帧以内。堆叠数据在交易与邮寄场景的校验口径曾有三处实现，某一处的边界写松了导致超堆交易，三处收敛到一个公共函数后才算真正安全。背包格子的扩容道具与堆叠上限是两个独立的容量维度，玩家常常混淆，容量说明页把两者画成一张对照表。堆叠类道具的发放接口统一走同一个入口，任何绕过堆叠逻辑直接写格子的代码都会在代码评审里被打回。堆叠数据在交易与邮寄场景的校验口径曾有三处实现，某一处的边界写松了导致超堆交易，三处收敛到一个公共函数后才算真正安全。背包格子的扩容道具与堆叠上限是两个独立的容量维度，玩家常常混淆，容量说明页把两者画成一张对照表。堆叠类道具的发放接口统一走同一个入口，任何绕过堆叠逻辑直接写格子的代码都会在代码评审里被打回。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。