【后端接口】playlevelup：升级触发的经验回收与成长钩子

实战应用：用在哪里

playlevelup 是人物升级的引擎触发：升级广播、属性奖励、解锁公告全从这进入。触发器函数以事件名命名、玩家对象作首参，这是 996 引擎触发体系的统一签名，升级触发是理解这套体系的最佳起点。

触发签名与升级钩子

---人物升级触发 actor:玩家对象
function playlevelup(actor, oldLevel, newLevel)
    sendmsg(actor, 1, "恭喜升到 " .. newLevel .. " 级")
    if newLevel == 28 then
        sendmsg(actor, 1, "已可前往沃玛寺庙三层")
    end
    if newLevel % 10 == 0 then
        giveitem(actor, "回城卷轴", 5, 1, "整级奖励")
        sendcentermsg(actor, 250, 0, actor:GetName() .. " 达到 " .. newLevel .. " 级", 0, 5, "")
    end
end

触发函数的参数按引擎事件表定义：actor 之外还带升级前后的等级，等级差的计算、跳级的判断都从这两个值来。升级钩子的三大件：通知（sendmsg）、发放（giveitem）、公告（sendcentermsg），10 的整数倍等级触发全服公告与礼包，普通等级静默推进，通知的密度按等级跨度分级。

升级解锁的统一入口

function playlevelup(actor, oldLevel, newLevel)
    -- 技能解锁：28 级学烈火剑法
    if newLevel >= 28 and not hasSkillFlag(actor) then
        addskill(actor, "烈火剑法", 1)
        sendmsg(actor, 1, "习得新技能：烈火剑法")
    end
    -- 地图解锁公告
    local unlockMap = LEVEL_MAP_UNLOCK[newLevel]
    if unlockMap then
        sendmsg(actor, 1, "新地图已开放：" .. unlockMap)
    end
end

等级解锁的散点逻辑全部收敛到升级触发里统一分发：技能、地图、玩法功能的解锁用一张等级配置表驱动，新增解锁项加表不动触发体。升级触发的执行频率等于全服的升级频率，钩子体的耗时控制是性能要求：重逻辑异步化，触发体内只做轻量的通知与发放。

验证与监控

升级触发的执行耗时监控，钩子体内的数据库同步调用是耗时的主要来源。

踩坑记录

升级触发的参数曾经想当然写成 (actor, level) 双参，引擎实际给的是三参（含旧等级），参数表的对照手册是触发器开发的第一参考资料。批量升等级的活动（直升丹）会连续触发多次 playlevelup，触发体内的发放逻辑要做合并判断，一次直升 10 级不该发 10 份整级奖励。

上线要点

升级触发的注册不需要显式绑定，引擎按函数名自动路由，函数名写错（大小写敏感）等于没写，触发的存在性自检（启动时遍历期望的触发函数表）能兜住这种静默失误。触发体里的广播类调用要做对象校验，actor 在极端时序下可能已失效，判空是第一行代码。

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