跳到主要内容

PRD-040 跑环任务

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

1. 背景与目标​

跑环是日常经验/材料的重要来源，任务链需要频繁调整。用 Lua 编排任务池、轮次、奖励与刷新，可以在线调整而不改 C++。

目标

  • 每轮 10 环，任务从池中按权重抽取。
  • 支持提交物品、杀怪、对话、护送、使用道具等类型。
  • 完成整轮获得阶段奖励，可付费刷新任务。

2. 核心规则​

  • 玩家 30 级以上，每日 2 轮。
  • 每环任务随机，连续 3 环不重复类型。
  • 任务可放弃，放弃后本轮进度保留但需重新抽当前环。
  • 每环有星级（1–5 星），星级越高奖励越好、难度越高。
  • 完成 10 环获得轮次宝箱，概率额外大奖。
  • 每日 0 点重置轮次与次数。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/quest/ring.lua
Ring = {
    rounds_per_day = 2,
    steps = 10,
    pool = {
        { type="kill",   weight=40 },
        { type="item",   weight=30 },
        { type="talk",   weight=15 },
        { type="escort", weight=10 },
        { type="use",    weight=5 },
    },
    star_rate = { 0.5, 0.3, 0.15, 0.04, 0.01 },
}

function OnRingAccept(ctx, role)
    if ctx:GetDailyCount(role, "ring") >= Ring.rounds_per_day then
        return ctx:Fail(role, "今日跑环次数已用完")
    end
    ctx:SetRoleVar(role, "ring_step", 1)
    ctx:SetRoleVar(role, "ring_chain", {})
    ctx:SetRoleVar(role, "ring_star", ctx:PickStar(Ring.star_rate))
    ctx:GenerateStep(role)
end

function OnStepComplete(ctx, role)
    local step = ctx:GetRoleVar(role, "ring_step")
    ctx:GrantStepReward(role, ctx:GetRoleVar(role, "ring_star"))
    if step >= Ring.steps then
        ctx:GrantRoundReward(role)
        ctx:AddDailyCount(role, "ring", 1)
        ctx:ClearRoleVars(role)
    else
        ctx:SetRoleVar(role, "ring_step", step + 1)
        ctx:GenerateStep(role)
    end
end
  • 任务生成、进度、奖励全部在脚本；C++ 只提供击杀/提交/对话事件。
  • 任务链状态存 ctx.state，断线/重启从快照恢复。
  • 刷新当前环消耗道具，脚本重新 GenerateStep，不改变轮次进度。

3.2 协议​

方向协议说明
C→SCS_RingAccept接取
C→SCS_RingRefresh刷新当前环
C→SCS_RingSubmit提交
C→SCS_RingAbandon放弃
S→CSC_RingInfo当前环/进度/星级
S→CSC_RingResult完成/奖励

3.3 事件驱动​

  • C++ 将击杀、采集、对话、到达事件转发给 LuaQuestMgr。
  • 脚本匹配当前环目标，增加进度。
  • 进度满后标记可提交，等待玩家回 NPC 提交。

4. 客户端设计​

  • 跑环面板：轮次、环数、星级、任务目标、奖励预览。
  • 一键寻路到 NPC/目标点。
  • 刷新按钮显示消耗与预览，二次确认。
  • 完成动画、轮次宝箱、额外大奖。
  • 放弃确认与进度提示。

5. 配置与 Lua 接口​

配置说明
steps每轮环数
rounds_per_day每日轮次
pool任务类型权重
star_rate星级概率
reward_group单环/整轮奖励

Lua 接口：GenerateStep、TrackQuestEvent、GrantStepReward、GrantRoundReward、SetRoleVar、PickStar。

6. 边界与异常​

场景处理
任务目标被删除登录/接取时重新生成
背包满提交拒绝，保留任务
放弃后重新接取保留轮次，重新抽当前环
跨天未完成本轮保留至完成或放弃
脚本异常保留当前进度，记录日志
重复提交幂等

7. 验收标准​

  • 接取/生成/进度/提交/整轮奖励正确。
  • 星级、权重、防连续重复类型生效。
  • 刷新/放弃/跨天处理正确。
  • 脚本热更不影响当前轮次。
  • 奖励与日志可追溯。