跳到主要内容

PRD-041 藏宝图寻宝

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

1. 背景与目标​

藏宝图提供探索与随机奖励。地图点、事件、奖励池适合用 Lua 编排，可快速扩展节日藏宝、限时寻宝。

目标

  • 藏宝图分普通/高级/传说，挖宝点随机。
  • 挖宝触发随机事件：奖励、怪物、陷阱、传送。
  • 支持组队共享、每日次数、活动期限。

2. 核心规则​

  • 玩家使用藏宝图后获得 1 个挖宝坐标，显示在地图/罗盘。
  • 到达坐标 3 格内使用铲子，读条 2 秒。
  • 普通图奖励材料/金币，高级图有概率出装备，传说图必出稀有。
  • 20% 概率触发事件：守卫怪、陷阱、直接奖励、传送到隐藏点。
  • 每日最多挖 10 次，组队成员在 10 格内可共享奖励。
  • 藏宝图有 7 天有效期，过期作废。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/activity/treasure.lua
Treasure = {
    daily_limit = 10,
    dig_range = 3,
    events = {
        { type="reward", weight=50 },
        { type="monster", weight=25 },
        { type="trap", weight=15 },
        { type="portal", weight=10 },
    },
}

function OnUseMap(ctx, role, map_item)
    local spot = ctx:PickSpot(map_item.level, ctx:GetMapId(role))
    ctx:SetRoleVar(role, "treasure_spot", spot)
    ctx:SetRoleVar(role, "treasure_map", map_item.id)
    ctx:Send(role, "SC_TreasureSpot", spot)
end

function OnDig(ctx, role)
    local spot = ctx:GetRoleVar(role, "treasure_spot")
    if not ctx:InRange(role, spot, Treasure.dig_range) then
        return ctx:Fail(role, "不在挖宝点附近")
    end
    if ctx:GetDailyCount(role, "treasure") >= Treasure.daily_limit then
        return ctx:Fail(role, "今日挖宝次数已用完")
    end
    ctx:ConsumeItem(role, ctx:GetRoleVar(role, "treasure_map"), 1)
    local event = ctx:PickWeighted(Treasure.events)
    ctx:TriggerTreasureEvent(role, spot, event.type)
    ctx:AddDailyCount(role, "treasure", 1)
end
  • 坐标由服务端随机，客户端只显示。
  • 挖宝距离、地图、道具、次数全部服务端校验。
  • 事件由脚本分发，奖励/怪物/陷阱接口由 C++ 导出。
  • 组队共享通过 ctx:GetNearbyParty 计算，不信任客户端。

3.2 协议​

方向协议说明
C→SCS_TreasureUse使用藏宝图
C→SCS_TreasureDig挖宝
S→CSC_TreasureSpot坐标/罗盘
S→CSC_TreasureEvent事件结果
S→CSC_TreasureResult奖励/失败

3.3 事件类型​

事件处理
直接奖励发放奖励池
守卫怪生成 1–3 只守卫，击杀后给奖励
陷阱扣血/减速/传送回城
传送门传送到隐藏宝藏点，额外奖励

4. 客户端设计​

  • 藏宝图使用后显示罗盘/地图标记、距离。
  • 到达后铲子按钮高亮，读条与挖掘动画。
  • 事件表现：宝箱、怪物、陷阱、传送门。
  • 奖励展示与组队共享提示。
  • 藏宝图有效期、每日次数。

5. 配置与 Lua 接口​

配置说明
level图等级
spot_pool坐标池
reward_group奖励池
event_weight事件权重
daily_limit每日次数
expire_days有效期

Lua 接口：PickSpot、InRange、ConsumeItem、PickWeighted、TriggerTreasureEvent、GetNearbyParty。

6. 边界与异常​

场景处理
坐标不可达重新随机/邮件补图
挖宝中移动打断，不扣次数
组队共享10 格内成员，超出不共享
地图关闭/活动结束图作废，邮件补偿
重复挖宝幂等，坐标失效
脚本异常返还藏宝图，记录日志

7. 验收标准​

  • 使用图/坐标/挖宝/事件/奖励全流程正确。
  • 距离、地图、次数、有效期校验完整。
  • 组队共享范围与奖励正确。
  • 坐标不可达/重复挖宝有兜底。
  • 节日藏宝可通过脚本扩展。