一文掌握游戏引导的实现思路

触发点：
什么时候判断

触发条件：
判断是否满足条件

local M = class("GuideMgr")

function M.tryStart() end

function M.start(groupConfig) end

function M.step(stepId) end

function M.finish() end

function M.saveGuideStep(stepId) end

return M

local M = class("GuideMgr")

...

-- 引导触发判定总入口
function M.tryStart()
    -- 引导禁用
    if M.isForbidGuide() then return end
    -- 正在引导，不触发判定
    if M.isGuiding() then return end
  
    -- 获取没有触发过的引导组别，判定是否满足触发条件
    local groupConfigs = M.getGroupConfigs()
    for i = 1, #groupConfigs do
        local config = groupConfigs[i]
        -- 如果满足触发条件
        if CondMgr.isConditionArrayMet(config._triggerCond) then
            -- 触发引导
            M.start(config)
            return true
        end
    end
end

-- 获取没有触发过的引导组别
function M.getGroupConfigs()
    local configs = M._groupConfigs
    if configs == nil then
        configs = {}
            
        for k, v in pairs(D._guideGroupConfig) do
            -- 取没有触发过的引导组别
            if not M.isFinished(k) then
                configs[#configs + 1] = v
            end
        end
    
        table.sort(configs, function(a, b) return a._priority < b._priority end)
        M._groupConfigs = configs
    end
    return configs
end

...

return M

local M = class("CondMgr")

...

--[[--
配表类型：[S
配表写法：{"form": 101, "hero_level": 20} | {"form":101, "vip_level":3}
在101界面，英雄等级达到20级或vip等级达到3级，触发引导

cond参数结构：
table数组
{
    {form = 101, hero_level = 20},
    {form = 101, vip_level = 3}
}

只要数组中其中一个条件满足即可
--]]--
function M.isConditionArrayMet(conds)
    for i = 1, #conds do
        if M.isConditionMet(conds[i]) then
            return true
        end
    end
    return false
end

function M.isConditionMet(cond)
    for k, v in pairs(cond) do
        if not M.CondCheck[k](v) then return false end
    end
    return true
end

M.CondCheck = {
    ["form"] = function(val)
        local form = Form.getTop()
        return form and form._id == val
    end,
    ["hero_level"] = function(val)
        local lv = P._playerHero:getOwnedHeroMaxLevel()
        return lv >= val
    end,
    ["vip_level"] = function(val)
        return P:vipLevel() >= val
    end
}

...

return M

local M = class("GuideMgr")

...

function M.start(groupConfig)
    -- 如果有引导正在进行，结束所有引导，开始触发传入组别的引导
    M.finish()

    -- 保存当前正在触发的引导组别ID
    local groupId = groupConfig._id
    M.saveGuideGroup(groupId)
  
    local stepId = groupConfig._stepId
    M.saveGuideStep(stepId)
  
    -- 引导视图层准备工作
    M.prepareLayer()
  
    -- 开始当前引导组的第一步操作
    M._groupId = groupId
    M._stepId = stepId
    M.step(stepId)
end

-- 创建引导图层，后续的所有操作添加的元素都放在这里
function M.prepareLayer()
    local layer = M._layer
    if layer == nil then
        layer = class(nil, V).new(lc.CocosClass.ui_widget)
        layer:setContentSize(lc.ScrSize)
        lc.addChildToCenter(Scene._current, layer, V.ZOrder.guide)
        M._layer = layer

        layer:setTouchListener(function() end)
    end
end

function M.saveGuideGroup(groupId)
    -- TODO：保存到服务端
    ...
end

function M.saveGuideStep(stepId)
    -- TODO：保存到服务端
    ...
end

...

return M

local M = class("GuideMgr")

...

function M.step(stepId)
    -- 保证step在引导中执行（由M.start发起）
    if not M.isGuiding() then return end

    --[[--
    stepId不为空，表示开始当前步骤操作；
    stepId为空，表示在M._stepId基础上，进入下一步操作；
    --]]--
    if stepId == nil then
        stepId = M._stepId
 
        -- 在当前步骤结束，准备进入下一步时，记录当前步骤的保存点
        local stepConfig = D._guideStepConfig[stepId]
        local saveId = stepConfig._saveId
        if saveId then
            if saveId == 100 then
                M.setGroupFinished(M._groupId)
                M.saveGuideStep()

            elseif saveId > 0 then
                M.saveGuideStep(saveId)
            end
        end

        stepId = stepId + 1
    end
  
    -- 传入的步骤ID不存在，结束引导
    local config = D._guideStepConfig[stepId]
    if config == nil then
        M.finish()
        return
    end
  
    M._stepId = stepId

    -- 清除所有引导元素
    M.clearLayer()

    -- 根据步骤参数做相应处理
    -- （后面继续）
    ...
end

function M.isGuiding()
    return M._stepId and D._guideStepConfig[M._stepId]
end

-- 清理所有layer上的引导元素，包括手指、高亮、立绘对话等
function M.clearLayer()
    local layer = M._layer
    if layer == nil then return end

    layer:setSwallowTouches(true)
    layer:setTouchListener(function() end)

    M.removeFinger()
    M.removeDilog()
    M.removeTipText()
    ...
end

...

return M

local M = class("GuideMgr")

...

function M.step(stepId)
    ...
  
    -- （接上面的代码）
    local config = D._guideStepConfig[stepId]

    -- 根据步骤参数做相应处理
    local param = M.getStepParam(config)
    if param then
        -- 允许玩家自由点击
        if param.free_op then
            M._layer:setSwallowTouches(false)
        end

        M._waitParam = nil

        if param.delay then
            M._waitParam = V.scheduleCall(function() M.doAction() end, param.delay)

        elseif param.event then
            _, M._waitParam = lc.event.once(param.event, function() M.doAction() end)

            if not param.free_op then
                M._layer:setTouchListener(function()
                    -- 提示当前无法点击
                end)
            end
      
        elseif param.form_show then
            local form = Form.getTop()
            if form == nil or form._id ~= param.form_show or not form._isShown then
                _, M._waitParam = lc.event.on("form.show", function(form)
                    if form._id == param.form_show then M.doAction() end
                end)
            end
      
        elseif param.form_close then
            local form = Form.getTop()
            if form and form._id == param.form_close then
                _, M._waitParam = lc.event.on("form.close", function(formId)
                    if param.form_close == formId then M.doAction() end
                end)
            end
        end
    
        if M._waitParam == nil then
            M.doAction()
        end
    end
end

function M.getStepParam(stepConfig)
    stepConfig = stepConfig or D._guideStepConfig[M._stepId]
    return json.decode(stepConfig._param or "")
end

...

return M

local M = class("GuideMgr")

...

function M.doAction()
    if not M.isGuiding() then return end
  
    local config = D._guideStepConfig[M._stepId]
    M._waitParam = nil
  
    local layer = M._layer
    layer:setSwallowTouches(true)
  
    local action = config._action
    if action == 0 then
        -- 执行下一步操作
        M.step()

    else
        local func = M.ActionFuncs[action]
        if func then
            if not func(config) then
                M.finish()
            end
  
        else
            -- 交给外部处理
            V.scheduleCall(function() lc.event.emit("guide.step", config) end, lc.FrameInterval)
        end
    end
end

M.Action = {
    click_main_tab = 10001,
    click_sys_entrance = 10002,
    click_by_name = 10003,
    ...
    dialog = 30001,
    ...
    tip_text = 40001,
    ...
}

M.ActionFuncs = {
    [M.Action.click_main_tab] = function(config)
        local index = config._val
        local tab = table.walk(Scene._curent, "_tabs", index)
        if tab and tab:isVisible() then
            M.addTouchFinger(tab)
            return true
        end
    end,
    [M.Action.click_sys_entrance] = function(config) ... end,
    [M.Action.click_by_name] = function(config) ... end,
  
    [M.Action.role_dialog] = function(config)
        local textConfig = D._guideTextConfig[config._val]
        M.addDialog(textConfig)
        return true
    end,
  
    [M.Action.tip_text] = function(config)
        local textConfig = D._guideTextConfig[config._val]
        M.addTipText(textConfid._textSid, config._param)
        return true
    end
}

...

return M

local M = class("GuideMgr")
...

function M.finish()
    -- 数据层
    M.saveGuideGroup()
    M.saveGuideStep()

    if M._groupId then
        M.setGroupFinished(M._groupId)
    end
  
    M._groupId = 0
    M._stepId = 0

    -- 视图层
    M.clearLayer()
    M.removeLayer()

    local param = M._waitParam
    if param then
        -- 移除事件监听
        if param._event then
            lc.event.remove(param)
        
        -- 移除延迟操作的定时器
        else
            param:unschedule()
        end
        M._waitParam = nil
    end
  
    -- 延迟一帧判断是否有新的引导可以触发
    V.scheduleCall(M.tryStart, lc.FrameInterval)
end

...

return M

local M = class("GuideMgr")
...

function M.addTouchFinger(node, ...)
    ...
    node._lastListener = node._listener
    node._listener = M.fingerTouchListener
    ...
end

function M.fingerTouchListener(...)
    ...
    if node._lastListener then
        node._lastListener(...)
        node._listener = node._lastListener
    end
  
    -- 按钮点击后，执行下一步
    M.step()
    ...
end

...
return M

local M = class("GuideMgr")
...

function M.addDialog()
    ...
  
    M._layer:setTouchListener(function()
        ...
        -- 设置layer点击事件
       M.step()
        ...
    end)
  
    ...
end

function M.addTipText()
    ...
  
    M._layer:setTouchListener(function()
        ...
        -- 设置layer点击事件
        M.step()
        ...
    end)
  
    ...
end

...
return M