跳到主要内容

PRD-036 钓鱼玩法

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

1. 背景与目标​

钓鱼提供休闲产出与图鉴收集。鱼种、概率、天气/时段影响适合用 Lua 配置，C++ 只负责鱼点、施法与背包。

目标

  • 钓鱼点、鱼种、概率、尺寸、稀有度可配置。
  • 抛竿/咬钩/收杆由服务端判定，客户端做小游戏表现。
  • 支持图鉴、每日任务、钓鱼大赛扩展。

2. 核心规则​

  • 玩家 20 级以上、装备鱼竿、消耗鱼饵才能钓鱼。
  • 每个钓鱼点有鱼种池，受地图、时段、天气影响。
  • 抛竿后 2–8 秒随机咬钩，窗口 3 秒内收杆成功。
  • 收杆小游戏：控制张力条，张力过高断线，过低鱼跑掉。
  • 鱼分普通/稀有/传说，记录最大尺寸与首次捕获。
  • 每日钓鱼 100 次，超出不再消耗鱼饵。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/activity/fishing.lua
Fishing = {
    daily_limit = 100,
    bite_min = 2, bite_max = 8,
    reel_window = 3,
    pools = {
        [101] = { {fish=4001, w=600}, {fish=4002, w=300}, {fish=4003, w=100} },
    },
}

function OnCast(ctx, role, spot_id)
    if ctx:GetDailyCount(role, "fishing") >= Fishing.daily_limit then
        return ctx:Fail(role, "今日钓鱼次数已用完")
    end
    if not ctx:ConsumeBait(role) then return ctx:Fail(role, "鱼饵不足") end
    local delay = ctx:RandomInt(Fishing.bite_min, Fishing.bite_max)
    ctx:SetRoleVar(role, "fishing_spot", spot_id)
    ctx:SetTimer(role, "bite", delay, OnBite)
end

function OnBite(ctx, role)
    ctx:SetRoleVar(role, "bite_deadline", ctx:Now() + Fishing.reel_window)
    ctx:Send(role, "SC_FishingBite")
end

function OnReel(ctx, role, tension)
    if ctx:Now() > ctx:GetRoleVar(role, "bite_deadline") then
        return ctx:Fail(role, "鱼跑了")
    end
    local fish = ctx:PickWeighted(Fishing.pools[ctx:GetRoleVar(role, "fishing_spot")])
    local size = ctx:RandomSize(fish)
    local min_t, max_t = ctx:GetTensionRange(fish)
    if tension < min_t or tension > max_t then
        return ctx:Fail(role, "收杆失败")
    end
    ctx:GrantFish(role, fish, size)
    ctx:AddDailyCount(role, "fishing", 1)
end
  • 咬钩延迟与鱼种由服务端随机，客户端无法预知。
  • 客户端提交张力值，服务端按鱼种区间校验，异常值记录。
  • 鱼获直接入包，满包转邮件。

3.2 协议​

方向协议说明
C→SCS_FishingCast抛竿
C→SCS_FishingReel收杆（张力）
S→CSC_FishingBite咬钩
S→CSC_FishingResult鱼种/尺寸/失败原因

3.3 鱼点与刷新​

  • 鱼点由 scenesinfo.xml 配置，脚本只引用。
  • 鱼点不消耗，按玩家独立冷却。
  • 同一点多人可同时钓，不互相影响。

4. 客户端设计​

  • 抛竿动作、浮漂、咬钩提示“！”，3 秒倒计时。
  • 张力条小游戏：左右移动保持绿色区间，过高断线。
  • 鱼获展示：鱼种、品质、尺寸、图鉴解锁。
  • 钓鱼图鉴：按地图/鱼种分类，最大尺寸记录。
  • 每日次数、鱼饵数量显示。

5. 配置与 Lua 接口​

配置说明
spot_id / map_id鱼点
pool鱼种权重
bite_range咬钩时间
reel_window收杆窗口
size_range尺寸范围
daily_limit每日次数

Lua 接口：ConsumeBait、RandomInt、PickWeighted、RandomSize、GrantFish、Send、SetTimer。

6. 边界与异常​

场景处理
抛竿后移动取消本次钓鱼，退还鱼饵（可配置）
重复收杆幂等，只结算一次
背包满鱼获转邮件
钓鱼中下线取消，不扣次数
脚本异常停止该玩家钓鱼，记录日志
钓鱼大赛通过同一脚本的 activity 子模式扩展

7. 验收标准​

  • 抛竿/咬钩/收杆/鱼获全流程正确。
  • 鱼种概率、尺寸、图鉴、每日次数正确。
  • 客户端无法伪造鱼种/尺寸。
  • 移动/下线/满包处理正确。
  • 钓鱼大赛可通过脚本配置开启。