跳到主要内容

PRD-043 帮会篝火宴会

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

1. 背景与目标​

篝火宴会提供帮会集体在线场景与经验增益。开启时间、燃料、经验倍率、节目互动适合用 Lua 编排。

目标

  • 帮主/副帮主在帮会领地开启篝火，持续 30 分钟。
  • 成员添加燃料提升经验倍率与篝火等级。
  • 围坐、跳舞、答题等互动获得额外奖励。
  • 活动结束按贡献发放帮会资金/个人奖励。

2. 核心规则​

  • 每日 19:00–22:00 可开启，每帮会每日 1 次。
  • 开启消耗帮会资金，成员可捐献木材/燃料。
  • 篝火 1–5 级，经验倍率 1.2–2.0，范围 20 格。
  • 每 60 秒给范围内成员发经验，离开范围停止。
  • 互动动作（跳舞/鼓掌）每 5 分钟获得一次小奖励。
  • 活动结束按燃料贡献排名发奖。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/activity/guild_bonfire.lua
Bonfire = {
    duration = 1800,
    max_level = 5,
    tick_seconds = 60,
    exp_rate = { 1.2, 1.4, 1.6, 1.8, 2.0 },
}

function OnBonfireStart(ctx, guild)
    if ctx:GetDailyCount(guild, "bonfire") >= 1 then
        return ctx:Fail(guild, "今日已开启")
    end
    local fire = ctx:SpawnBonfire(guild, 1)
    ctx:SetGuildVar(guild, "bonfire_id", fire.id)
    ctx:StartTimer("bonfire_tick", Bonfire.tick_seconds, OnTick)
end

function OnAddFuel(ctx, role, item)
    local fire = ctx:GetGuildVar(ctx:GetGuild(role), "bonfire_id")
    local level = ctx:AddFuel(fire, item)
    if level > Bonfire.max_level then return ctx:Fail(role, "已达最高等级") end
    ctx:UpdateBonfireLevel(fire, level)
end

function OnTick(ctx)
    local fire = ctx:GetActiveBonfire()
    if not fire then return end
    for _, role in ipairs(ctx:GetRolesInRange(fire, 20)) do
        ctx:GrantExp(role, ctx:CalcBonfireExp(role, Bonfire.exp_rate[fire.level]))
    end
end
  • 篝火实体、范围、等级由 C++ 维护，脚本负责规则与奖励。
  • 燃料贡献记录在脚本状态，结束时排名发奖。
  • 活动结束/帮会解散自动清理。

3.2 协议​

方向协议说明
C→SCS_BonfireStart开启
C→SCS_BonfireFuel添加燃料
C→SCS_BonfireInteract跳舞/鼓掌
S→CSC_BonfireState等级/经验/倒计时
S→CSC_BonfireResult奖励/贡献排名

3.3 权限与限制​

  • 仅帮主/副帮主可开启。
  • 开启期间帮会成员才能获得经验。
  • 退会/被踢立即停止获得经验。

4. 客户端设计​

  • 帮会领地篝火模型、等级光效、范围圈。
  • 经验飘字与倍率显示，倒计时。
  • 燃料捐献按钮、贡献榜。
  • 互动动作按钮与冷却。
  • 结束时结算面板。

5. 配置与 Lua 接口​

配置说明
duration持续时间
max_level最高等级
fuel_items燃料
exp_rate各等级倍率
reward_group贡献奖励

Lua 接口：SpawnBonfire、AddFuel、UpdateBonfireLevel、GetRolesInRange、GrantExp、GetGuild。

6. 边界与异常​

场景处理
帮会解散立即结束并清理
帮主掉线篝火继续，结束由定时器触发
重复开启拒绝
燃料超上限转换为帮会资金
跨天以开启时间计算
脚本异常结束活动并补偿已参与成员

7. 验收标准​

  • 开启/燃料/升级/经验/互动/结算正确。
  • 权限、范围、帮会成员校验完整。
  • 燃料贡献与奖励排名正确。
  • 解散/掉线/跨天处理正确。
  • 脚本热更不影响进行中活动。