跳到主要内容

PRD-026 副本系统

文档编号：PRD-026
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
关联模块：ScenesServer、MiniServer、tbl/Dungeon.xml、lua/fuben/

1. 背景与目标​

副本承载剧情推进、装备产出与日常玩法。当前副本存在次数扣减时机不一致、掉线后进度丢失、结算重复发奖等问题。本 PRD 统一下副本的创建、进度、失败、结算与次数管理。

目标

  • 单人/组队/团队副本共用一套生命周期。
  • 次数、进度、奖励结算具备幂等与回档能力。
  • 支持普通、精英、挑战、限时四种难度。

2. 核心规则​

2.1 副本类型​

类型人数次数复活限制典型产出
剧情1一次性无限经验、主线道具
日常1–5每日 1–3 次3 次材料、金币
精英1–5每日 1 次2 次装备、图纸
团队10–20每周 1 次1 次套装、稀有材料
挑战1–5每周0排名、称号

2.2 生命周期​

创建房间 → 准备/倒计时 → 进入副本 → 战斗推进 → BOSS 击杀
  → 结算（成功/失败/超时）→ 发放奖励 → 解散/传送出本

2.3 次数与消耗​

  • 次数在 进入副本时 扣减，失败/退出不返还（可配置）。
  • 门票在创建房间时扣除，创建失败原路退回。
  • 每日 0 点重置，周常周一 0 点重置。
  • 协助他人不消耗次数，但无奖励（可配置侠义值）。

2.4 进度与失败​

  • 副本进度按击杀的 BOSS/关卡记录，掉线重连可回到当前进度。
  • 全员死亡/超时/离开副本地图视为失败。
  • 失败后保留已击杀 BOSS 的进度，允许重新进入继续（按配置）。
  • 副本内禁止使用回城/传送类道具（可配置白名单）。

3. 服务端设计​

3.1 模块职责​

模块职责
DungeonManager创建、进入、进度、结算、销毁
ScenesServer副本场景实例与怪物管理
MiniServer跨地图/跨服副本调度（团队本）
RecordServer次数、进度、通关记录

3.2 数据结构​

struct DungeonInstance {
    uint64_t instance_id;
    uint32_t dungeon_id;
    uint32_t leader_id;
    std::vector<uint64_t> members;
    uint8_t  state;          // WAITING/FIGHTING/SETTLING/CLOSED
    uint32_t enter_time;
    uint32_t deadline_ms;
    std::vector<uint32_t> cleared_stages;
};

struct DungeonCd {
    uint32_t dungeon_id;
    uint32_t used_today;
    uint32_t used_week;
    uint32_t last_reset_day;
};

3.3 协议​

方向协议说明
C→SCS_DungeonCreate创建房间
C→SCS_DungeonEnter进入副本
C→SCS_DungeonLeave主动离开
C→SCS_DungeonRevive副本内复活
S→CSC_DungeonInfo副本信息、进度、倒计时
S→CSC_DungeonStage关卡/ BOSS 进度
S→CSC_DungeonResult结算结果与奖励
S→CSC_DungeonCd次数同步

3.4 结算流程​

BOSS 死亡/最后关卡完成
  → 锁定副本状态为 SETTLING
  → 校验所有成员是否在副本内
  → 计算奖励（基础 + 贡献 + 首通 + 队长）
  → 写奖励日志 + 发邮件/直接入包
  → 广播 SC_DungeonResult
  → 传送出本 → 销毁实例

3.5 幂等与回档​

  • 每个副本实例只允许结算一次，instance_id 作为幂等键。
  • 奖励发放失败进入补偿队列，邮件补发。
  • 服务器重启后，未结算实例标记为异常，按进度补发基础奖励。
  • 次数扣减与创建房间在同一事务，避免只扣不进。

4. 客户端设计​

  • 副本大厅：按类型/等级/难度筛选，显示次数、推荐战力、奖励预览。
  • 创建房间：选择难度、人数、是否公开，显示门票消耗。
  • 副本内 HUD：倒计时、关卡进度、复活次数、队伍成员状态。
  • 结算面板：通关/失败、用时、伤害占比、奖励列表、再次挑战。
  • 掉线重连：重新进入副本当前进度，不重复播放结算。

5. 配置与数值​

tbl/Dungeon.xml 字段：

字段说明
id副本 ID
type剧情/日常/精英/团队/挑战
map_id副本地图
min_level / max_level等级限制
player_min / player_max人数限制
daily_limit / weekly_limit次数限制
time_limit时限（秒）
revive_limit复活次数
stages关卡与 BOSS 列表
rewards基础/首通/队长奖励
ticket_item门票道具

6. 边界与异常​

场景处理
队员未全部进入倒计时结束未进入者视为放弃，不扣其次数
队长解散副本内成员收到通知，10 秒后传出
结算时掉线奖励通过邮件补发
重复结算请求按 instance_id 幂等，返回首次结果
副本内使用回城拒绝并提示
服务器重启未完成实例标记异常，按进度补偿
次数跨天以进入时间所在自然日计算

7. 埋点与运营​

  • 副本创建/进入/通关/失败率、平均用时、复活次数。
  • 各 BOSS 通关率与灭团点。
  • 奖励产出与市场流通量监控。
  • 后台可调整次数、掉落、难度系数、补偿邮件。

8. 验收标准​

  • 五类副本均可创建、进入、推进、结算、退出。
  • 次数只在进入时扣减，失败/退出按配置处理。
  • 掉线重连回到当前进度，不重复发奖。
  • 结算奖励与日志一致，邮件补发可追踪。
  • 团队副本 20 人同时进入无卡顿/掉线。
  • 服务器重启后副本状态可恢复或安全关闭。