【界面UI】新手引导系统：步骤状态机与遮罩高亮的实现

实战应用：用在哪里

新手引导决定玩家的前期留存：步骤跳错、遮罩挡住按钮、引导与弹窗抢时序，都会造成直接流失。可靠的引导系统 = 步骤状态机 + 遮罩高亮 + 服务端进度保存，本文给出三个组件的实现要点。

步骤状态机：数据驱动的引导表

引导步骤定义成有序表，每步声明目标控件、提示文案与完成条件：

local steps = {
    { id = "open_bag",  panel = "main",  widget = "btn_bag",
      text = "点击打开背包", done = function() return bagOpened() end },
    { id = "equip_item", panel = "bag",  widget = "item_1001",
      text = "穿上新手装备", done = function() return hasEquip(1001) end },
}

function Guide.apply(step)
    local s = steps[step]
    Mask.showExcept(s.panel, s.widget)          -- 遮罩挖孔高亮目标
    Tip.show(s.text, anchorOf(s))
end

遮罩实现：全屏半透明遮罩上为目标控件"挖孔"（挖孔区域不拦截触摸、其他区域吞掉触摸），玩家只能点到引导目标。完成条件用轮询或事件驱动检测，达成后自动进入下一步。

进度保存与跳过

进度存服务端（新手进度是运营指标，也是断线重续的依据）：每完成一步上报一次，登录时按服务端进度恢复到对应步骤。跳过按钮按运营策略配置（可跳过的引导在数据里标记 skippable），跳过即把进度推进到该链路终点。多个引导链（主线、功能解锁）各自独立状态机，互不阻塞。

与弹窗的时序治理

引导与运营弹窗（公告、活动页）抢时序是常见事故。规则两条：引导期间的非关键弹窗入队延迟展示；关键弹窗（防沉迷类）优先于引导。实现上给弹窗系统加优先级队列，引导占用的步骤在队列里标记为"引导持有"，弹窗等引导让位后再出。新手引导的体验问题九成是时序问题，优先级队列 + 服务端进度两个机制就能根治。

引导步骤的埋点统计：每一步记录到达人数与完成人数，完成率骤降的步骤就是流失点。数据驱动地精简引导链路，比主观争论哪一步该删有效得多。

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