元梦之星活动系统完整开发指南

一、活动系统概述

活动系统是元梦之星游戏的核心系统之一，负责管理游戏内各类限时活动、商业化活动、节日活动等。系统采用模块化、模板化设计，支持快速开发和复用。

1.1 系统架构

活动系统主要由以下部分组成：

配置层：Excel配置表（H_活动中心配置.xlsx）
数据层：NewActivityModel（活动数据管理）
UI层：基于UMG的界面系统，支持继承和组件化
协议层：活动数据下发、红点推送、通用协议
任务系统：活动任务数据管理（TaskSystemModel）

1.2 目录结构

根据iwiki文档目录，活动系统文档包含80个文档，主要分为：

活动开发指南
活动实例（商业化活动）
模板与组件
具体活动实现文档
活动改造与优化

二、活动开发流程

2.1 完整开发流程（从零开始）

第一步：活动配置

所有活动都需要在 H_活动中心配置.xlsx 及其分表中进行配置。

核心配置表：

活动页签表
- id：一级页签ID
- seq：页签顺序
- 控制活动在发现中的分类显示
活动配置表（最重要）
- id：活动ID（唯一标识，必填）
- activityNameType：活动类型枚举（同类型活动共享）
- showInCenter：是否展示在活动中心
- tagId：所属页签ID（必填）
- labelId：活动在页签内的排序（必填）
- activityUIDetail：关联的UMG界面文件名（必填）
- timeInfo：活动时间（beginTime, endTime, showBeginTime, showEndTime）
- activityTaskGroup：任务组ID数组（分号分隔）
- activityShopType：商城ID（如有兑换商店）
- clientParams：客户端显示参数（字符串数组）
- rewardInfo：活动奖励 {itemId:itemNum}
- jumpId/jumpType：跳转配置
- pakGroupId：分包ID（如需分包下载）
- activityGroup：活动分组（区分主玩法/副玩法）
活动任务组表
- 一个活动包含一个或多个任务组
- 每个任务组包含一个或多个任务
- 配置任务有效期、任务类型
活动红点配置表（H_红点配置.xlsx）
- playerLevel：玩家等级限制
- registerDays：注册天数限制
- redDotType：红点显示类型（0:所有 1:可领奖 2:上新）

第二步：资源准备

Layout视角（UI资源）：

活动资源存放路径

Feature/System/Script/System/Activity/
├── Public/ # 模板化活动模板逻辑
├── Instance/ # 模板化活动实例逻辑
└── HistoryActivity/ # 旧版本活动逻辑

资源组织规范

每个活动创建独立文件夹（便于分包下载）
Layout资源 → Blueprints/ 文件夹
图片资源 → Texture/ 文件夹
禁止直接引用其他活动文件夹的资源

通用组件存放路径
Feature/System/Script/System/Activity/Public/Component/
多个活动复用的组件放入此目录

第三步：数据协议对接

核心协议（NewActivityModel.lua）：

活动数据下发

协议：ActivityListAll_C2S_Msg
触发时机：打开发现或跳转活动
处理逻辑：
– 请求所有活动列表
_MOE.NetworkManager:SendMsg(_MOE.MsgName2Id.ActivityListAll_C2S_Msg, {},
function(msg)
– 处理活动数据
self:InitActivityData()
end)

活动数据解析
- InitActivityMap()：以页签ID为Key缓存活动数据
- 检测活动有效期和显示状态
- 处理PixUI活动和无极大图公告混排
新活动协议（推荐）
- ActivityGetAllInfo_C2S_Msg：通过活动ID获取活动数据
- ActivityInfoUpdateNtf：活动数据更新监听
- ActivityGeneralReqHandle：活动通用协议（支持自定义msgType）
- ActivityReceiveRewards_C2S_Msg：领奖协议
红点协议
- ActivityReadDotNtf：红点数据下发
- ActivityClickRedDot_C2S_Msg：红点消除
- ClearAllRedDot_C2S_Msg：一键清除红点

第四步：UI开发

UI开发规范：

基于模板开发（推荐）
- 继承现有模板（如 UI_ActivityLottery_BaseView）
- 重写必要的方法（GetTAG(), PlayEffectItems() 等）
- 使用父类组件减少重复代码
独立开发
- 创建新的UMG界面
- 在 UIWndNameToLuaPath.lua 中注册
- 实现活动逻辑脚本
UI继承示例（抽奖活动）

第五步：逻辑开发

客户端逻辑（以抽奖活动为例）：

– 1. 定义活动Model（如需要缓存数据）
local ActivityLotteryModel = _MOE.Class(“ActivityLotteryModel”, _MOE.BaseModel)

function ActivityLotteryModel:GetDataSourceRewardList()
– 获取抽奖奖励列表
end

– 2. 在主界面中注册Model
function UI_ActivityLottery_BaseView:GetModel()
return _MOE.Models.ActivityModel.subModels.ActivityLotteryModel
end

– 3. 监听活动数据更新
self:AddEventListener(_MOE.Models.NewActivityModel.OnActivityInfoUpdateNtf,
self.OnActivityInfoUpdate)

– 4. 处理任务数据（如有任务）
self:AddEventListener(_MOE.EventEnum.TASK_INFO_MAP_UPDATE_NOTICE,
self.OnTaskUpdate)

第六步：测试与上线

配置推送：策划配置完成后推送服务器并reload
分包打包：如配置了 pakGroupId，需打包分包
功能测试：
- 活动显示/隐藏
- 时间控制
- 任务完成与领奖
- 红点逻辑
- 中断处理（切页签、杀进程）
- 断线重连

2.2 策划视角配置要点

活动基础配置
- 在正确的分表中配置（依据活动类型）
- 必填字段：id, activityNameType, tagId, labelId, activityUIDetail
- 时间配置：注意 showBeginTime/showEndTime 与 beginTime/endTime 的区别
任务配置
- 任务组需配置在 activityTaskGroup 字段（分号分隔）
- 任务组包含任务类型和有效期
- 有效期控制任务是否开放
活动类型与分组
- activityType：服务器使用，需服务器增加枚举
- activityGroup：控制显示在主玩法或副玩法发现中
- 枚举值：0=主玩法, 1=农场, 2=MOBA等
换皮活动
- 复制现有活动配置
- 修改活动有效时间和 activityUIDetail
- 推送reload服务器

2.3 客户端视角开发要点

活动数据管理：

数据下发流程
- 打开发现 → 请求 ActivityListAll_C2S_Msg → 解析并缓存活动数据
- 数据以活动页签ID为Key进行缓存
- 自动过滤无效页签和过期活动
红点管理
- 登录成功后下发 ActivityReadDotNtf
- 活动变动时重新下发
- 主页面/页签红点由服务器处理
- 界面内红点由客户端自行处理
活动脚本组织
- 模板活动：Feature/System/Script/System/Activity/Public/
- 实例活动：Feature/System/Script/System/Activity/Instance/
- 旧活动：Feature/System/Script/System/Activity/HistoryActivity/
- 子Model需在 ActivityModelPath.lua 中注册
任务系统对接
- 监听 _MOE.EventEnum.TASK_INFO_MAP_UPDATE_NOTICE
- 通过参数 taskMap 判断是否为当前活动任务

三、核心概念详解

3.1 活动配置表字段详解

必填字段

字段	说明	示例
`id`	活动ID（唯一标识）	10001
`activityNameType`	活动类型枚举	1
`tagId`	所属页签ID	101
`labelId`	活动排序	1
`activityUIDetail`	UMG界面文件名	UI_Activity_Lottery

时间字段

字段	说明
`timeInfo.beginTime`	活动真正开始时间
`timeInfo.endTime`	活动真正结束时间
`timeInfo.showBeginTime`	活动展示开始时间（未开始可预览）
`timeInfo.showEndTime`	活动展示结束时间

功能字段

字段	说明
`showInCenter`	是否显示在活动中心
`slapFace`	是否有拍脸通知
`activityTaskGroup`	任务组ID数组（分号分隔）
`activityShopType`	商城ID数组
`rewardInfo`	奖励配置 {itemId:itemNum}
`jumpId`/`jumpType`	跳转配置
`pakGroupId`	分包ID
`activityGroup`	活动分组（主玩法/副玩法）

客户端参数

字段	说明
`clientParams`	客户端显示参数（字符串数组）
`activityParam`	活动自定义参数（整数数组）

3.2 协议与数据模型

NewActivityModel 核心方法

-- 获取所有活动列表
NewActivityModel:ReqGetAllActivityList(callback)

-- 通过活动ID获取活动数据
NewActivityModel:ReqGetActivityInfoById(activityId, onSuccess, onFail)

-- 监听活动数据更新
NewActivityModel.OnActivityInfoUpdateNtf(activityId)

-- 活动通用协议
NewActivityModel:ActivityGeneralReqHandle(activityId, msgType, reqData, onSuccess, onFail)

-- 领奖协议
NewActivityModel:ActivityReceiveRewardsByData(activityId, rewardType, receiveId, receiveCount, onSuccess, onFail)
NewActivityModel:ActivityReceiveRewardsByDataList(activityId, rewardType, rewardInfo, onSuccess, onFail)

活动数据缓存结构

-- 活动数据以 activityId 为Key缓存
self.m_ActivityMap = {
    [activityId] = {
        activityId = 10001,
        activityName = "国庆活动",
        timeInfo = {...},
        taskGroups = {...},
        ...
    }
}

-- 活动页签数据以 tagId 为Key缓存
self.m_ActivityTabMap = {
    [tagId] = {
        id = 101,
        seq = 1,
        activities = {...}
    }
}

3.3 红点系统

红点类型

ActivityRedDotType = {
    ARDT_New = 1,              -- 上新
    ARDT_ShareLuckyMoney = 2,   -- 分享红包
    ARDT_ReceiveLuckyMoney = 3,  -- 领取红包
    ARDT_DepositCommodityAvailable = 4,  -- 招财返利可购买
    ...
}

红点处理流程

服务器下发红点
- 协议：ActivityReadDotNtf
- 包含：活动ID、红点类型、红点ID
客户端处理红点
- 主页面/页签红点：服务器自动处理
- 界面内红点：客户端根据活动数据自行判断
- 一次性红点：调用 ActivityClickRedDot_C2S_Msg 消除
一键清除红点
- 第一部分：本地红点（公告、PixUI引导）→ PlayerModel:SetClientCacheTable
- 第二部分：服务器红点 → ClearAllRedDot_C2S_Msg
- 第三部分：PixUI红点 → 收到 PixuiRedDotNtf 后调用 PixuiRedDotReport_C2S_Msg

四、模板与组件

4.1 活动模板

现有模板

活动抽奖模板（UI_ActivityLottery_BaseView）
- 适用：带抽奖功能的活动
- 功能：抽奖、进度奖励、兑换商店、分享
- 组件：抽奖按钮、进度奖励、分享按钮
逐任务活动模板（UI_Activity_Task_BaseView）
- 适用：以任务为主的活动
- 功能：任务列表、任务领奖、进度显示
简单任务列表模板
- 适用：简单任务展示
- 配置驱动，无需额外开发

模板使用规范

继承模板

-- 新活动继承自模板
UI_NationalDay_MainView = _MOE.Class("UI_NationalDay_MainView", UI_ActivityLottery_BaseView)

function UI_NationalDay_MainView:PlayEffectItems()
    -- 重写父类方法
end

组件复用
- 直接使用父类组件，无需生成代码
- 注册方式：
  - 方式一：在 UIWndNameToLuaPath.lua 中定义（推荐）
  - 方式二：在UMG的View字段定义
重写注意事项
- 使用 类名:CallSuper() 而非 self:CallSuper()（避免多层继承堆栈溢出）
- 子类重写 TAG 字段定义独立Log标记

4.2 通用组件

常用组件

UI_ActivityBtn_ShareWithTips
- 功能：带Tips的分享按钮
- 参数：activityId
- 自动处理分享任务组刷新
UI_ActivityLottery_DrawBtn
- 功能：抽奖按钮
- 参数：raffleId, poolId, drawType
- 自动处理货币检查、红点显示
UI_ActivityLottery_RewardItem
- 功能：进度奖励Item
- 继承自：UI_Activity_DailyDrawItem
UI_CommonComp_BtnWheel
- 功能：交互展开按钮组件
- 适用：需要展开/收起的交互

4.3 活动模块化改造

改造目标

抽象界面功能共性
通用独立元素组件化
功能接近的界面通过继承提高效率

改造方案

参考文档：活动模块化改造方案说明

核心思路：

基类实现通用逻辑
子类重写差异化部分
组件化独立功能模块

五、具体活动案例分析

5.1 大富翁玩法实现

核心玩法

玩家投掷骰子，角色在棋盘上前进，踩中格子触发奖励。

格子类型

奖励格子：踩中后获得奖励
跳转格子：传送到指定位置（前进步数、快速前进）
抽奖格子：触发抽奖
任务格子：触发任务

数据模型

-- 活动数据
activityData = {
    curIndex = 5,              -- 当前所处格子索引
    finishedStepNum = 12,       -- 已完成步数
    finishedRoundNum = 1,       -- 已完成圈数
    hasReceiveReward = false     -- 是否已领取格子奖励
}

掷骰子流程

客户端发送协议
- 三种骰子：常规（1个）、双倍（2个）、指定点数
- 协议包含：骰子类型、自选点数（如适用）
服务器返回结果
- beforeIndex：投掷前位置
- afterIndex：目标位置
- step：点数数组
客户端模拟移动
- 先播放投掷动画
- 本地计算路径：CurStandIndex + step
- 逐格移动，触发经过逻辑
- 到达目标后触发踩中逻辑

角色移动逻辑

-- 移动流程
for i = 1, stepCount do
    -- 1. 移动到下一格
    local nextIndex = self.CurStandIndex + 1
    self:MoveToGrid(nextIndex)
    
    -- 2. 更新步数
    self.finishedStepNum = self.finishedStepNum + 1
    self:UpdateStepUI()
    
    -- 3. 触发经过逻辑（奖励格子）
    if self:IsRewardGrid(nextIndex) then
        self:TriggerPassLogic(nextIndex)
    end
    
    -- 4. 检查是否经过起点（更新圈数）
    if nextIndex == 0 then
        self.finishedRoundNum = self.finishedRoundNum + 1
        self:UpdateRoundUI()
    end
end

-- 5. 触发踩中逻辑
self:TriggerLandLogic(targetIndex)

中断处理

切出活动页签再切回：

请求活动数据
根据数据初始化位置和状态
检查当前格子是否需要处理（奖励/抽奖）

杀进程/断线重连：

同上，根据活动数据重新初始化

5.2 活动抽奖模板实现

UI结构

UI_ActivityLottery_BaseView（基类）
├── 活动时间
├── 活动货币
├── 分享按钮（UI_ActivityBtn_ShareWithTips）
├── 奖励预览
├── 兑换商店
├── 获取更多（任务组）
├── 抽奖按钮（UI_ActivityLottery_DrawBtn）
├── 进度奖励（UI_ActivityLottery_RewardItem）
└── 特效挂点

配置说明

H_活动中心配置：

activityParam[1]：抽奖ID
currencyCfg[1]：活动主代币ID
activityShopType[1]：商店ID
taskGroupsGetMore：获取更多任务组ID列表
taskGroupsDrawBase[1]：分享任务组ID
taskGroupsDrawBase[2]：进度任务组ID

C_抽奖奖池：

creditItemId：积分道具ID
reason：奖励原因（用于跳过动画缓存Key）

C_抽奖奖池 - 奖励：

groupId：奖励组（控制动效表现）
isGrand：是否大奖（在主界面展示）

抽奖流程

点击抽奖按钮
- 检查货币是否足够
- 显示红点（如有）
- 调用抽奖协议
播放抽奖动画
- 根据 groupId 显示不同动效
- 支持跳过动画（缓存 reason）
显示奖励
- 根据 isGrand 显示普通/大奖
- 调用通用奖励弹窗

红点逻辑

兑换商店红点：_MOE.Models.MallModel:IsMallNeedShowRedById(mallId)
获取更多红点：_MOE.Models.NewActivityModel:HasTaskReward(activityInfo)
抽奖按钮红点：检查 CanCheckRed = true，根据拥有道具数量刷新

5.3 柯南联动活动

活动组成

柯南联动活动包含多个子活动：

柯南集卡活动
柯南预热答题活动
少年侦探团活动
柯南走格子活动
柯南活动导航页

开发要点

集卡活动
- 卡片收集与交换
- 奖励兑换
- 社交功能（好友助力）
答题活动
- 题目配置与下发
- 答题结果判定
- 奖励发放
走格子活动
- 类似大富翁玩法
- 柯南主题格子设计
- 剧情触发
导航页
- 整合多个子活动入口
- 统一活动说明
- 进度汇总显示

5.4 其他典型活动

次留优化活动

新手奖励系统
- 目标：提升次日留存
- 机制：新账号登录奖励
- 配置：分阶段奖励
七日签到
- 连续签到奖励
- 拍脸通知（slapFace 配置）
- 断签处理

商业化活动

时装基金活动
- 购买基金 → 完成任务 → 领取返利
- 分阶段返利
- 进度追踪
农场拼图活动
- 拼图收集
- 农场主题奖励
- 社交分享
免肝卷活动
- TaskList组件复用
- 任务自动完成
- 奖励直接发放

六、副玩法活动开发

6.1 副玩法活动隔离

概念

副玩法活动指不属于主玩法的活动，如：

农场玩法活动
MOBA玩法活动
其他独立玩法活动

配置隔离

activityGroup字段：

0：主玩法活动（默认）
1：农场玩法
2：MOBA玩法
…

发现页显示：

主玩法发现只显示 activityGroup=0 的活动
农场发现只显示 activityGroup=1 的活动
以此类推

开发注意事项

资源隔离
- 副玩法活动资源放在独立目录
- 避免与主玩法资源混淆
协议隔离
- 副玩法活动数据独立下发
- 避免影响主玩法性能
UI适配
- 副玩法可能有独立的UI风格
- 需要针对性调整

6.2 活动中心优化

副玩法活动过滤

需求： 在活动中心过滤掉不属于当前玩法的活动

实现：

前端根据 activityGroup 过滤
服务器也可配置过滤规则
跳转逻辑适配（从副玩法跳转到活动中心时，只显示当前玩法活动）

活动筛选改造

需求： 支持更复杂的活动筛选逻辑

实现：

配置表增加筛选字段
前端根据筛选条件动态过滤
支持多维度筛选（玩法、类型、标签等）

七、常见问题与解决方案

7.1 活动不显示

可能原因：

配置问题
- showInCenter 未设置为 true
- tagId 对应的页签不在有效期
- suspend 字段未设置为 0
时间问题
- 当前时间不在 timeInfo 范围内
- showBeginTime 未到或 showEndTime 已过
分包问题
- 配置了 pakGroupId 但未下载分包
- 分包下载失败
数据问题
- 服务器未推送配置
- 客户端未请求到活动数据

排查步骤：

检查配置表字段
检查服务器配置是否推送
检查客户端日志（搜索 NewActivityModel）
检查分包状态

7.2 红点不显示/不消除

可能原因：

红点配置问题
- 未配置在 H_红点配置.xlsx 中
- 玩家等级/注册天数不满足
协议问题
- 未收到 ActivityReadDotNtf
- 红点类型不匹配
逻辑问题
- 界面内红点需客户端自行处理
- 一次性红点未调用消除协议

解决方案：

检查红点配置表
监听 NewActivityModel.OnActivityInfoUpdateNtf 刷新红点
一次性红点调用 ActivityClickRedDot_C2S_Msg
检查 redDotType 是否正确

7.3 任务不更新

可能原因：

任务组未配置
- activityTaskGroup 字段未填写或格式错误
- 任务组ID不存在
任务有效期问题
- 任务组不在有效期
- 任务已完成但状态未同步
监听问题
- 未监听 TASK_INFO_MAP_UPDATE_NOTICE
- 监听了但判断逻辑错误

解决方案：

-- 正确监听任务更新
function UI_Activity_TaskPanel:OnTaskUpdate(taskMap)
    if not taskMap then return end
    
    -- 判断是否为当前活动的任务
    local activityInfo = self:GetActivityInfo()
    if not activityInfo or not activityInfo.activityTaskGroup then return end
    
    for _, taskGroupId in pairs(activityInfo.activityTaskGroup) do
        if taskMap[taskGroupId] then
            self:RefreshTaskInfo()
            break
        end
    end
end

7.4 抽奖报错

可能原因：

配置问题
- activityParam[1] 抽奖ID不存在
- 抽奖奖池未配置
协议问题
- 抽奖协议返回错误
- 货币不足
UI问题
- 抽奖按钮组件未正确配置
- 动效播放失败

解决方案：

检查抽奖ID和奖池配置
检查货币是否足够（按钮红点会提示）
检查动效资源是否存在
查看协议返回错误码

7.5 中断后状态异常

问题描述：
切出活动页签再切回，或杀进程后，活动状态显示异常。

解决方案：

初始化时重新请求数据

function UI_Activity_BaseView:OnShow()
    -- 重新请求活动数据
    _MOE.Models.NewActivityModel:ReqGetActivityInfoById(self.activityId, 
        function()
            self:RefreshUI()
        end)
end

根据数据恢复状态
- 角色位置（大富翁类活动）
- 已完成步数
- 已领取奖励状态
处理中断前的操作
- 检查是否有未领取的奖励
- 检查是否有未完成的抽奖

7.6 分包相关

问题： 配置了分包但活动不显示

排查步骤：

检查 pakGroupId 是否配置正确
检查分包是否已打包
检查分包是否已下载
检查分包内容是否完整

分包调试：

-- 检查分包状态
local pakGroupId = activityInfo.pakGroupId
if pakGroupId and not _MOE.PakManager:IsPakDownloaded(pakGroupId) then
    -- 提示下载或隐藏活动
end

八、最佳实践

8.1 开发建议

优先使用模板
- 减少重复开发
- 统一用户体验
- 便于维护
组件化开发
- 独立功能封装为组件
- 提高复用性
- 降低耦合
配置驱动
- 尽量通过配置实现功能
- 减少硬编码
- 方便策划调整
充分测试
- 时间边界测试
- 中断测试
- 断线重连测试
- 分包测试

8.2 性能优化

数据缓存
- 活动数据按需缓存
- 切换场景时清理无用数据
- 避免重复请求
资源优化
- 使用分包减少初始包体
- 图片资源压缩
- 动效资源优化
协议优化
- 合并协议请求
- 减少不必要的数据下发
- 使用增量更新

8.3 协作建议

策划-程序协作
- 策划提供详细的需求文档
- 程序提供配置表说明
- 共同确认配置字段含义
文档维护
- 及时更新iwiki文档
- 记录特殊逻辑和坑点
- 提供典型案例
代码Review
- 继承关系审查
- 组件复用审查
- 性能影响评估

九、附录

9.1 相关文档链接

9.2 配置表清单

H_活动中心配置.xlsx：主配置表
- 活动页签表
- 活动配置表
- 活动组表
- 活动表
H_红点配置.xlsx：红点配置
C_抽奖奖池.xlsx：抽奖配置
活动专属配置表：特定活动的配置

9.3 协议清单

活动数据协议：

ActivityListAll_C2S_Msg：获取所有活动
ActivityGetAllInfo_C2S_Msg：获取指定活动数据
ActivityInfoUpdateNtf：活动数据更新通知

活动功能协议：

ActivityGeneralReqHandle：活动通用协议
ActivityGeneralNtf：活动通用推送
ActivityReceiveRewards_C2S_Msg：领奖协议

红点协议：

ActivityReadDotNtf：红点下发
ActivityClickRedDot_C2S_Msg：红点消除
ClearAllRedDot_C2S_Msg：一键清除红点
PixuiRedDotNtf：PixUI红点下发
PixuiRedDotReport_C2S_Msg：PixUI红点上报

9.4 常见问题FAQ

Q：如何快速开发一个新活动？
A：优先使用现有模板，继承后重写差异化部分。

Q：活动配置后为什么不显示？
A：检查 showInCenter、tagId、时间配置、分包状态。

Q：如何实现活动内红点？
A：客户端根据活动数据自行判断，不依赖服务器红点协议。

Q：副玩法活动如何隔离？
A：使用 activityGroup 字段，在配置和UI上做隔离。

Q：活动数据何时清理？
A：切换场景时，子Model会自动清理数据。

十、总结

本文档全面梳理了元梦之星活动系统的开发流程、核心概念、模板组件、具体案例和常见问题。活动系统采用模块化、模板化设计，支持快速开发和高效复用。

关键要点回顾：

活动开发从配置开始，配置表是核心
优先使用模板和组件，减少重复开发
协议和数据模型理解透彻，避免踩坑
充分测试边界情况（时间、中断、分包）
及时更新文档，沉淀最佳实践

希望本文档能帮助开发者快速上手活动开发，减少踩坑，提高开发效率。

本文从 LearnByCompany 原始文档自动同步。