跳到主要内容

PRD-042 节日活动框架

文档编号：PRD-042
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
脚本挂载：lua/activity/festival.lua

1. 背景与目标​

节日活动需要快速上线、复用流程、活动间互不干扰。本 PRD 定义通用活动框架，具体玩法由 Lua 子脚本实现，C++ 只提供活动生命周期与通用接口。

目标

  • 一个框架承载春节、中秋、周年庆等活动。
  • 活动分预热/正式/结束三个阶段，支持签到、任务、兑换、Boss。
  • 脚本可插拔，活动结束自动清理。

2. 核心规则​

  • 活动配置包含开始/结束时间、阶段、子玩法列表。
  • 预热期开放预告/预约，正式期开放玩法，结束后只保留兑换。
  • 每个子玩法有独立脚本与开关，可单独热更。
  • 活动货币独立，活动结束按比例回收/兑换。
  • 同一时间最多 3 个活动，避免入口过载。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/activity/festival.lua
Festival = {
    id = 4201,
    phases = { warmup = 3, formal = 14, closing = 3 },
    modules = { "signin", "quest", "exchange", "boss" },
}

function OnFestivalStart(ctx)
    ctx:LoadModules(Festival.modules)
    ctx:Broadcast("world", "节日活动开启")
end

function OnPhaseChange(ctx, phase)
    for _, name in ipairs(Festival.modules) do
        ctx:CallModule(name, "OnPhase", phase)
    end
end

function OnFestivalEnd(ctx)
    ctx:SettleExchange()
    ctx:CleanupModules()
    ctx:Broadcast("world", "节日活动结束")
end
  • ctx:LoadModules 加载子脚本，失败则跳过并告警，不影响其他模块。
  • 每个模块实现 OnPhase/OnPlayerEvent/OnEnd 约定接口。
  • 活动状态写 ctx.state，重启后按阶段恢复。
  • 活动货币、兑换比例由配置驱动，脚本不硬编码。

3.2 协议​

方向协议说明
S→CSC_FestivalInfo活动阶段/入口/倒计时
S→CSC_FestivalModule子玩法状态
C→SCS_FestivalEnter进入子玩法

3.3 生命周期​

配置加载 → 预热 → 正式 → 结束 → 兑换期 → 清理
  • 阶段切换由定时器驱动，服务端时间。
  • 活动结束停止产出，只保留兑换。
  • 清理时删除临时 NPC/怪物/地图实例。

4. 客户端设计​

  • 活动主面板：阶段、倒计时、子玩法入口、红点。
  • 子玩法独立面板，由服务端下发配置。
  • 活动货币/兑换商店。
  • 结束时提示未兑换货币与截止时间。

5. 配置与 Lua 接口​

配置说明
festival_id活动 ID
start_time / end_time周期
phases阶段天数
modules子玩法列表
currency活动货币
exchange兑换表

Lua 接口：LoadModules、CallModule、SetPhase、Broadcast、SettleExchange、CleanupModules。

6. 边界与异常​

场景处理
子脚本加载失败跳过该模块，其他正常
活动时间重叠按优先级/配置限制
服务器重启按当前阶段恢复
活动结束仍在场景传送回主城
货币未兑换邮件提醒/按比例回收
脚本异常停用模块，不影响框架

7. 验收标准​

  • 活动创建/阶段切换/结束/清理正确。
  • 子玩法可插拔、可独立热更。
  • 活动货币/兑换/回收正确。
  • 多活动并行不冲突。
  • 重启/异常有兜底。