PRD-034 运镖与劫镖

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

1. 背景与目标

运镖提供日常资源产出与野外冲突。路线、镖车等级、劫镖收益经常调整，适合用 Lua 编排状态机与结算，C++ 只负责移动、战斗与广播。

目标

• 接镖、路线、镖车血量、劫镖、交付全流程脚本化。
• 支持不同品质镖车、组队护镖、劫镖次数限制。
• 奖励与损失可配置，防止刷镖。

2. 核心规则

• 玩家 30 级以上可接镖，每日 3 次，可刷新品质。
• 镖车分白/绿/蓝/紫/橙，品质越高奖励越高、血量越低。
• 接镖后镖车跟随玩家，移动速度降低 20%，不能使用传送。
• 到达终点交付获得奖励；镖车被击毁则任务失败，损失押金。
• 劫镖者击毁镖车获得部分奖励，每日劫镖上限 5 次。
• 安全区与部分地图禁止劫镖；国战期间按配置关闭。

3. 服务端设计

3.1 Lua 脚本设计

-- lua/activity/escort.lua
Escort = {
    npc_start = 5001,
    npc_end = 5002,
    max_daily = 3,
    rob_daily = 5,
}

function OnEscortAccept(ctx, role, quality)
    if ctx:GetDailyCount(role, "escort") >= Escort.max_daily then
        return ctx:Fail(role, "今日运镖次数已用完")
    end
    local cart = ctx:SpawnCart(role, quality)
    ctx:BindCart(role, cart)
    ctx:TrackEvent(role, "cart_destroyed", OnCartDestroyed)
    ctx:TrackEvent(role, "cart_arrived", OnCartArrived)
end

function OnCartDestroyed(ctx, role, cart, killer)
    ctx:AddDailyCount(killer, "rob", 1)
    ctx:GrantRobReward(killer, cart)
    ctx:FailEscort(role, "镖车被劫")
end

function OnCartArrived(ctx, role, cart)
    ctx:GrantEscortReward(role, cart)
    ctx:CompleteEscort(role)
end

• ctx:SpawnCart 创建镖车实体并绑定跟随关系。
• ctx:TrackEvent 注册一次性事件，交付/失败后自动解绑。
• 奖励、押金、劫镖分成通过 ctx:GrantReward / ctx:DeductItem，保证事务。
• 脚本只维护业务状态，移动/战斗由 C++ 处理。

3.2 数据结构

struct EscortState {
    uint64_t role_id;
    uint64_t cart_id;
    uint8_t  quality;
    uint32_t start_time;
    uint8_t  state; // running/success/failed
};

3.3 协议

方向	协议	说明
C→S	CS_EscortAccept	接镖
C→S	CS_EscortRefresh	刷新品质
C→S	CS_EscortDeliver	交付
S→C	SC_EscortState	镖车/路线/倒计时
S→C	SC_EscortResult	成功/失败/被劫

3.4 防作弊

• 镖车位置由服务端移动逻辑驱动，客户端只表现。
• 交付校验 NPC 距离、镖车存活、任务状态。
• 同 IP 互劫不计数、不奖励。
• 传送/回城/进副本自动判定失败（可配置）。

4. 客户端设计

• 接镖面板：品质、奖励、押金、路线预览。
• 镖车血条、护镖状态、劫镖者标记。
• 地图路线指引与终点倒计时。
• 被劫提示：劫镖者名字、损失、复仇入口。
• 交付/失败结算面板。

5. 配置与 Lua 接口

配置	说明
quality_rate	品质概率
cart_hp	各品质血量
reward_group	交付奖励
rob_rate	劫镖分成
daily_limit	运镖/劫镖次数
safe_maps	禁止劫镖地图

Lua 接口：SpawnCart、BindCart、TrackEvent、GrantEscortReward、GrantRobReward、FailEscort、CompleteEscort。

6. 边界与异常

场景	处理
接镖后下线	镖车保留 5 分钟，超时失败
镖车卡地形	自动寻路失败 3 次后传送到最近路点
组队护镖	队友共享奖励，劫镖者只算最后一击
跨地图	禁止传送，强制走路线
服务器重启	运镖状态取消并返还押金
脚本异常	停用本场，已接任务按失败补偿

7. 验收标准

• 接镖/刷新/护镖/劫镖/交付/失败全流程正确。
• 品质、血量、奖励、次数按配置生效。
• 传送/下线/重启等异常有明确处理。
• 同 IP/低等级防刷生效。
• 脚本热更不影响进行中的镖车。