PRD-033 世界 BOSS 定时活动

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

1. 背景与目标

世界 BOSS 用于制造全服争夺与定时上线理由。玩法规则变化频繁，适合用 Lua 脚本编排刷新、阶段、伤害排行与奖励，不改 C++ 主流程。

目标

• 活动时间、BOSS 属性、阶段技能、奖励全部可配置。
• 伤害排行、归属、最后一击、参与奖由脚本计算。
• 支持热更脚本，不重启场景服。

2. 核心规则

• 每日 12:30、20:30 各一场，单场 30 分钟。
• BOSS 出现在指定地图固定坐标，刷新前 5 分钟全服公告。
• 伤害排行前 10 名、最后一击、参与奖（伤害 ≥ 1%）分别发奖。
• BOSS 分 3 个阶段，血量 70%/40% 触发阶段技能与公告。
• 死亡后 60 秒拾取，归属队伍优先，其他玩家可 Roll 参与奖。
• 同地图分线时，仅主line刷新，其他线通过跨线传送参与。

3. 服务端设计

3.1 模块职责

模块	职责
LuaActivityMgr	加载脚本、注册定时器/事件、热更
ScenesServer	创建 BOSS 实体、广播、伤害转发
RecordServer	排行、奖励、参与记录持久化
MailManager	奖励邮件补发

3.2 Lua 脚本设计

-- lua/activity/world_boss.lua
Activity = {
    id = 3301,
    maps = { 101, 102 },
    boss_id = 90001,
    duration = 1800,
}

function OnActivityStart(ctx)
    ctx:Broadcast("world", "世界BOSS将在5分钟后刷新")
    ctx:SetTimer("spawn", 300, OnBossSpawn)
end

function OnBossSpawn(ctx)
    local boss = ctx:SpawnMonster(Activity.boss_id, 101, 320, 240)
    ctx:RegisterDamageRank(boss, 10)
end

function OnBossDamage(ctx, boss, role, damage)
    ctx:AddDamageRank(boss, role, damage)
end

function OnBossKill(ctx, boss, killer)
    local rank = ctx:GetDamageRank(boss)
    ctx:GrantRankReward(rank, killer)
    ctx:SetTimer("corpse", 60, function() ctx:RemoveEntity(boss) end)
end

function OnActivityEnd(ctx)
    ctx:Cleanup()
end

脚本约束

• 只允许通过 ctx 提供的接口操作实体/发奖，禁止直接访问 DB。
• 每个回调 50ms 超时；连续 3 次超时自动停用脚本并告警。
• 状态数据放 ctx.state，跨天/重启由 RecordServer 快照恢复。
• 奖励发放使用 ctx:GrantReward，内部走邮件/背包事务，脚本不直接改物品。

3.3 协议

方向	协议	说明
S→C	SC_WorldBossInfo	活动时间、BOSS 状态、阶段
S→C	SC_WorldBossRank	伤害排行
S→C	SC_WorldBossReward	结算奖励
C→S	CS_WorldBossEnter	传送/进入

3.4 热更与回滚

• //reloadlua world_boss 重新加载脚本；进行中的活动保留旧实例状态。
• 脚本版本号写入日志，奖励按版本可追溯。
• 热更失败保留旧脚本，控制台提示行号。

4. 客户端设计

• 活动日历显示场次与倒计时，可点击传送到 BOSS 地图。
• BOSS 血条显示阶段、狂暴倒计时、当前伤害排行。
• 阶段切换播放全屏公告与技能预警。
• 结算面板显示排名、伤害占比、奖励；未参与显示参与奖条件。

5. 配置与 Lua 接口

配置	说明
activity_time	每日场次
boss_id / hp / skills	BOSS 配置
rank_size	排行人数
reward_group	排名/最后一击/参与奖
min_damage_rate	参与奖门槛

Lua 导出接口：SpawnMonster、RegisterDamageRank、AddDamageRank、GetDamageRank、GrantRankReward、SetTimer、Broadcast、Cleanup。

6. 边界与异常

场景	处理
活动时间重叠	后一场排队/跳过，脚本配置
BOSS 被拉出地图	超过边界强制回归/重置
服务器重启	按快照恢复或本场取消并补偿
脚本报错	pcall 捕获，停用本场，保留日志
伤害排行并列	按首次达到时间排序
玩家掉线	排行保留，奖励邮件补发

7. 验收标准

• 活动按配置定时开启/结束，公告正确。
• BOSS 阶段、伤害排行、最后一击、参与奖正确。
• 脚本热更不影响进行中的活动。
• 脚本异常不导致场景服崩溃。
• 掉线/重启奖励可补发。