【前端接口】SL:RegisterLuaNetMsg：接收服务端 Lua 推送的收货台

实战应用：用在哪里

服务端 sendluamsg 推出的数据要有人在客户端接：SL:RegisterLuaNetMsg 就是那个收货台。按消息号注册回调，服务端的每次推送都会唤起对应的处理函数，BOSS 血条、活动倒计时、队列提醒的实时刷新全走这条通道。

注册与处理

-- 注册 7001 号消息：BOSS 血量推送
SL:RegisterLuaNetMsg(7001, function(p1, p2, p3, sMsg)
    local win = GUI:GetWindow("bossHpBar")
    if not win then return end
    local bar = GUI:LoadingBar_Create(win, "hpBar", 20, 15, "hp_bar.png", 0)
    GUI:LoadingBar_setPercent(bar, p1)
    local nameText = GUI:Text_Create(win, "bossName", 95, 4, 12, "#FFD700", sMsg)
end)

注册的两个要素：消息号与服务端 sendluamsg 的 msgid 一致、回调的参数顺序对应服务端的 param1 到 param3 加 sMsg。回调体里先判窗口有效性再操作控件，窗口已经关闭的推送直接丢弃，判空是回调的第一行。回调内的控件创建是懒加载思路：第一次推送时创建血条，后续推送只刷新数据。

注销与生命周期

-- 窗口销毁时注销回调
local function onCloseWin(win)
    SL:UnRegisterLuaNetMsg(7001)
end

注销接口与注册配对：界面销毁、玩家切换场景时把不再需要的消息号注销，泄漏的回调会在窗口重建后造成重复触发。回调的注册时机在窗口打开之后，注销在窗口关闭的回调里，生命周期的配对在窗口脚本里集中管理。通道的消息是推送语义不是请求响应，界面的初始数据要靠独立的全量拉取，推送只负责增量更新。

验证与监控

回调的执行异常要有 pcall 包裹并上报，前端通道的异常静默会表现为界面不刷新的工单。

踩坑记录

消息号的分配冲突曾经让两个界面的回调互串，前后端共享的 msgid 常量表是通道的第一份协议文档。回调里做重活（遍历大表、创建大量控件）会造成消息处理队列的积压，推送的渲染合并（一帧内多条推送只刷一次）是高频通道的优化项。

上线要点

SL:RegisterLuaNetMsg 与 SL:UnRegisterLuaNetMsg 的配对纪律在界面脚本的生命周期钩子里强制执行。推送的频率设计：服务端的每次状态变化都推还是节流推送，节流的阈值与界面的刷新预期匹配。调试期用 SL:Print 在回调入口打印消息号与参数，前后端的消息流一目了然。

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