【后端接口】addbag：进包触发的拾取绑定与黑名单拦截

实战应用：用在哪里

addbag 在物品进入背包的瞬间触发：拾取绑定、赃物黑名单、背包审计全在这一个点上做。它还有个前置兄弟 addbagbefore，一前一后构成物品入包的两道关卡，后者甚至能改写物品的绑定属性。

进包触发的绑定

---物品进入背包触发 actor:玩家 item:物品对象
function addbag(actor, item)
    local from = item:GetFrom()
    -- 怪物掉落拾取：自动绑定
    if from == "monster" then
        item:SetBind(1)
        sendmsg(actor, 1, item:GetName() .. " 已绑定")
    end
    -- 贵重物品入包全服通告
    if RARE_ITEMS[item:GetName()] then
        QF_Broadcast(actor:GetName() .. " 获得了 " .. item:GetName())
    end
end

触发带 actor 与 item 两个对象：物品从哪来（GetFrom）决定怎么处理，怪物掉落自动绑定、商店购买保持原状、玩家交易维持自由，来源驱动的差异化规则全在入口分发。贵重物品的入包通告用一张稀有品名字典驱动，屠龙入包的瞬间全服都能看到。

黑名单与前置拦截

---物品进包前触发：可拦截
function addbagbefore(actor, item)
    if BLACKLIST[item:GetName()] then
        sendmsg(actor, 1, "该物品已被回收，无法获取")
        return false
    end
    return true
end

addbagbefore 的返回值是裁决权：false 直接阻止物品进包，被盗装备回收后全服的黑名单拦截在这里生效。前置触发还能做改写：某些活动要求进包的特定物品强制绑定，在前置里 SetBind 比入包后再改少一次状态同步。两道触发的分工：before 管准许与改写，addbag 管记录与联动。

验证与监控

入包触发的处理耗时监控，单次超过 5 毫秒即告警，高频触发点的性能就是背包操作的流畅度。

踩坑记录

入包触发的 item 对象在触发瞬间还未最终入格，业务在触发里读格位信息读到的是空，对象级的信息（名字、数量、来源）稳定可用而格位相关的要延后。黑名单曾经按物品 ID 匹配漏掉了改版后 ID 变化的老物品，黑名单的名字与 ID 双索引匹配是加固后的方案。

上线要点

入包触发是全服最高频的触发之一，触发体的每一行都在为全服的拾取操作付出成本，逻辑要克制在 O(1) 的字典查询。批量拾取（一键拾取）会让 addbag 在同一帧内连发多次，触发体的去抖与合并要预留设计。触发的注册同样按函数名路由，addbagbefore 与 addbag 的拼写一个字母都不能差。

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