【后端接口】sendluamsg：前后端 Lua 消息通道的对接写法

实战应用：用在哪里

sendluamsg 是后端 Lua 直达前端 Lua 的专用通道：服务端算好的数据不经过协议表直接推给客户端脚本，前端用 SL:RegisterLuaNetMsg 注册同号回调收货。这条通道让前后端的联调省掉协议表的中间层，活动界面的实时刷新全靠它。

后端推送

---前后端消息 actor:玩家 msgid:自定义消息ID param1-3:整数参数 sMsg:字符串
function sendluamsg(actor, msgid, param1, param2, param3, sMsg) end

-- 推送BOSS血量变化到前端血条界面
function pushBossHp(actor, percent, bossName)
    sendluamsg(actor, 7001, percent, 0, 0, bossName)
end

msgid 是前后端约定好的频道号（7001 表示 BOSS 血条频道），三个整数参数加一个字符串参数的载荷结构覆盖绝大多数推送场景。BOSS 血量百分比走整数参数，BOSS 名字走字符串，前端拿到的就是渲染需要的全部数据，不需要二次查询。

前端注册与收货

-- 前端：注册同号回调
SL:RegisterLuaNetMsg(7001, function(p1, p2, p3, sMsg)
    local bar = GUI:GetWindow("bossHpBar")
    if bar then
        GUI:LoadingBar_setPercent(bar.hpBar, p1)
        GUI:Text_setString(bar.nameText, sMsg)
    end
end)

前端在界面初始化时用同号注册回调，推送到达即刷新进度条与名字文本。回调的注销（UnRegisterLuaNetMsg）在界面销毁时配对调用，不注销的回调在窗口重建后重复触发是典型的内存泄漏式 Bug。通道的分工：sendluamsg 是定向推送（发给指定玩家），全服广播类的需求走公告体系，通道的带宽留给真正需要点对点的数据。

验证与监控

通道消息的到达率与延迟监控，推送的频次按 msgid 统计，高频推送要考虑前端合帧渲染。

踩坑记录

msgID 的冲突曾经让两个活动的推送互相覆盖，频道号的分配表管理是前后端联调的第一份协议。前端回调里访问已销毁的控件曾经抛错中断后续消息处理，回调体第一行判空窗口有效性是标准写法。整数参数传浮点值被截断，血量百分比先取整再推送。

上线要点

这条通道的载荷上限与频率上限要遵守引擎的约束，大表数据用 JsonEncode 压进字符串参数时注意长度。通道的消息是"最好能有"语义：断线重连期间的消息会丢，界面的完整性靠重连后的全量同步接口兜底而不是依赖推送。前后端的 msgID 常量表建议做成共享文件，两端引用同一份定义。

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