跳到主要内容

PRD-052 限时增益活动框架

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

1. 背景与目标​

双倍经验、掉落提升、金币加成等限时增益活动频繁上线。用 Lua 统一管理增益时段、叠加、上限与公告，避免每次改 C++。

目标

  • 配置化开启经验/掉落/金币/声望等倍率活动。
  • 支持全服/地图/帮会/等级段范围。
  • 与道具/装备加成正确叠加，设置上限。

2. 核心规则​

  • 活动配置倍率、范围、开始/结束时间、公告。
  • 同类倍率取最高值，不叠乘；不同类可叠乘。
  • 总倍率上限可配置（如经验最高 5 倍）。
  • 活动开始/结束全服公告，客户端显示增益图标/倒计时。
  • 支持手动开启/关闭（GM），用于补偿/事故。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/activity/buff_event.lua
BuffEvent = {
    events = {
        { id=1, type="exp",   rate=2.0, scope="world", start="20:00", stop="22:00" },
        { id=2, type="drop",  rate=1.5, scope="map:101", start="12:00", stop="14:00" },
    },
    caps = { exp=5.0, drop=3.0, gold=3.0 },
}

function OnBuffEventStart(ctx, ev)
    ctx:SetGlobalBuff(ev.type, ev.rate, ev.scope)
    ctx:Broadcast("world", "限时增益开启：" .. ev.type .. " x" .. ev.rate)
    ctx:SetTimer("buff_stop_" .. ev.id, ctx:SecondsUntilToday(ev.stop), function()
        OnBuffEventStop(ctx, ev)
    end)
end

function OnBuffEventStop(ctx, ev)
    ctx:ClearGlobalBuff(ev.type, ev.scope)
    ctx:Broadcast("world", "限时增益结束")
end
  • 倍率存全局状态，C++ 结算时查询 GetBuffRate(type, role)。
  • 同类取最高、不同类相乘，上限在 C++ 侧统一裁剪。
  • 活动状态持久化，重启后按当前时间恢复/结束。

3.2 协议​

方向协议说明
S→CSC_BuffEventInfo活动类型/倍率/倒计时
S→CSC_BuffEventEnd结束通知

3.3 叠加规则​

来源叠加方式
限时活动同类取最高
道具加成与活动乘算
VIP/月卡与活动乘算
装备/称号固定值，不参与倍率
总上限按类型裁剪

4. 客户端设计​

  • 主界面增益图标：类型、倍率、剩余时间。
  • 活动日历/公告入口。
  • 经验/掉落飘字显示倍率。
  • 结束前 5 分钟提示。
  • 多活动并存时按优先级排序。

5. 配置与 Lua 接口​

配置说明
typeexp/drop/gold/reputation
rate倍率
scopeworld/map/guild/level
start / stop时段
cap上限

Lua 接口：SetGlobalBuff、ClearGlobalBuff、GetBuffRate、Broadcast、SecondsUntilToday。

6. 边界与异常​

场景处理
活动时间重叠同类取最高，不同类并存
服务器重启按当前时间恢复/结束
手动关闭GM 命令立即清除并公告
倍率配置错误服务端夹到上限，记录告警
跨天活动按绝对时间，不随 0 点重置
脚本异常清除本活动增益，记录日志

7. 验收标准​

  • 活动按配置开启/结束/公告。
  • 同类取最高、不同类乘算、上限裁剪正确。
  • 重启/手动关闭/时间重叠处理正确。
  • 客户端图标/倒计时与服务端一致。
  • 新类型增益可通过 Lua 扩展。