跳到主要内容

PRD-048 许愿池

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

1. 背景与目标​

许愿池提供每日低门槛抽奖与保底追求。愿望类型、概率、保底、许愿币适合用 Lua 管理，可扩展节日愿望。

目标

  • 每日免费许愿 1 次，额外许愿消耗许愿币。
  • 愿望分普通/稀有/传说，累计许愿值提升概率。
  • 许愿值满必出传说，结果可保存/展示。

2. 核心规则​

  • 每日 0 点重置免费次数。
  • 许愿消耗 1 枚许愿币，获得随机奖励与许愿值。
  • 许愿值 0–100，每抽 +5，满 100 必出传说并清零。
  • 连续 10 次未出稀有，下一次稀有概率翻倍。
  • 愿望结果可保存在“心愿墙”，展示 7 天。
  • 许愿币来源：活跃度、活动、商城。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/activity/wishing_pool.lua
Wish = {
    daily_free = 1,
    value_per_draw = 5,
    pity_value = 100,
    pools = {
        { quality="normal", weight=70, rewards={5001,5002} },
        { quality="rare",   weight=25, rewards={5101,5102} },
        { quality="legend", weight=5,  rewards={5201} },
    },
}

function OnWish(ctx, role)
    local free = ctx:GetDailyCount(role, "wish_free")
    if free < Wish.daily_free then
        ctx:AddDailyCount(role, "wish_free", 1)
    elseif not ctx:ConsumeItem(role, 4901, 1) then
        return ctx:Fail(role, "许愿币不足")
    end
    local value = ctx:GetRoleVar(role, "wish_value") + Wish.value_per_draw
    local quality
    if value >= Wish.pity_value then
        quality = "legend"
        value = 0
    else
        quality = ctx:PickWeighted(Wish.pools, ctx:GetLuckBonus(role))
    end
    ctx:SetRoleVar(role, "wish_value", value)
    ctx:GrantWishReward(role, quality)
    ctx:SaveWishWall(role, quality)
end
  • 免费次数、许愿币、许愿值全部服务端记录。
  • 保底优先于权重，达到 100 必出传说。
  • 心愿墙只保存结果摘要，不保存物品实例。

3.2 协议​

方向协议说明
C→SCS_WishDraw许愿
S→CSC_WishInfo免费次数/许愿值/心愿墙
S→CSC_WishResult结果/保底进度

3.3 概率与审计​

  • 权重表版本化，记录随机种子。
  • 每抽记录 role_id、消耗、结果、许愿值前后。
  • 保底/稀有翻倍逻辑由服务端计算，客户端只显示。

4. 客户端设计​

  • 许愿池场景：池子、许愿按钮、免费次数。
  • 许愿值进度条、保底提示。
  • 结果动画：普通/稀有/传说不同光效。
  • 心愿墙：展示 7 天愿望。
  • 许愿币获取途径。

5. 配置与 Lua 接口​

配置说明
daily_free每日免费
value_per_draw许愿值
pity_value保底值
pools奖池权重
currency许愿币

Lua 接口：GetDailyCount、AddDailyCount、ConsumeItem、PickWeighted、GrantWishReward、SaveWishWall。

6. 边界与异常​

场景处理
免费次数用完扣许愿币
许愿币不足拒绝
背包满奖励转邮件
重复请求幂等
跨天免费次数重置，许愿值保留
脚本异常回滚消耗，记录日志

7. 验收标准​

  • 免费/付费许愿、许愿值、保底、稀有翻倍正确。
  • 奖励发放与消耗事务一致。
  • 概率/保底日志可审计。
  • 跨天/重复请求处理正确。
  • 心愿墙展示与过期清理正确。