武器系统设计文档

武器系统设计文档

1. 设计目标

• 支持多种武器类型（步枪、手枪、狙击枪、手雷等）
• 支持武器切换、开火、换弹、瞄准等核心操作
• 支持武器属性配置（伤害、射速、弹夹容量等）
• 支持武器状态管理（空弹、过热、冷却等）
• 支持武器动画和音效触发
• 支持武器升级和自定义（配件、皮肤）
• 支持网络同步，保证多人游戏一致性

2. 系统架构

+-------------------+
|   武器管理器      | <--- 管理玩家持有的所有武器，切换武器
+-------------------+
          |
          v
+-------------------+
|   武器基类        | <--- 定义武器通用接口和属性
+-------------------+
          |
          v
+-------------------+
|   具体武器类      | <--- 步枪、手枪、狙击枪等具体实现
+-------------------+
          |
          v
+-------------------+
|   武器状态机      | <--- 管理武器状态（待机、开火、换弹等）
+-------------------+
          |
          v
+-------------------+
|   武器动画与音效  | <--- 触发对应动作的动画和音效
+-------------------+

3. 核心模块设计

3.1 武器管理器（WeaponManager）

• 持有玩家所有武器实例
• 处理武器切换请求
• 转发输入事件到当前武器
• 管理武器拾取和丢弃

3.2 武器基类（WeaponBase）

• 定义武器属性（伤害、射速、弹夹容量、射程等）
• 定义武器接口（开火、换弹、瞄准、切换状态）
• 管理弹药数量和状态
• 处理射击逻辑（射线检测、弹道计算）

3.3 具体武器类（Rifle, Pistol, Sniper等）

• 实现具体武器的特殊行为（如狙击枪蓄力、手雷投掷）
• 定义武器专属参数和动画事件

3.4 武器状态机（WeaponStateMachine）

• 管理武器状态转换（Idle, Firing, Reloading, Aiming, etc）
• 防止状态冲突（如换弹时不能开火）
• 触发状态对应的动画和音效

3.5 武器动画与音效（WeaponFX）

• 绑定武器动作与动画
• 播放射击、换弹、瞄准音效
• 处理粒子特效（枪口火焰、弹壳抛射）

4. 关键数据结构

enum class WeaponState {
    Idle,
    Firing,
    Reloading,
    Aiming,
    Switching,
    Empty
};

struct WeaponAttributes {
    std::string name;
    int damage;
    float fireRate;          // 每秒射击次数
    int magazineCapacity;    // 弹夹容量
    int ammoInMagazine;      // 当前弹夹弹药数
    int ammoReserve;         // 备用弹药数
    float reloadTime;        // 换弹时间（秒）
    float range;             // 有效射程
    bool isAutomatic;        // 是否自动射击
};

class WeaponBase {
public:
    virtual void Fire();
    virtual void Reload();
    virtual void Aim(bool enable);
    virtual void SwitchState(WeaponState newState);
    virtual void Update(float deltaTime);

protected:
    WeaponAttributes attributes;
    WeaponState currentState;
    float fireCooldown;      // 射击冷却计时
};

5. 功能流程

5.1 开火流程

1. 玩家按下开火键
2. 武器状态机判断当前状态是否允许开火（Idle或Aiming）
3. 检查弹夹是否有弹药
4. 触发射击逻辑（射线检测、伤害计算）
5. 播放射击动画和音效
6. 弹药数减少，设置射击冷却时间
7. 如果弹夹空，切换到Empty状态，提示换弹

5.2 换弹流程

1. 玩家按下换弹键或弹夹空自动触发
2. 状态机切换到Reloading状态
3. 播放换弹动画和音效
4. 等待换弹时间结束
5. 弹药从备用弹药补充到弹夹
6. 状态机切换回Idle或Aiming状态

5.3 瞄准流程

1. 玩家按下瞄准键
2. 状态机切换到Aiming状态
3. 调整视角和准星
4. 播放瞄准动画
5. 松开瞄准键，状态切换回Idle

5.4 武器切换流程

1. 玩家选择切换武器
2. 当前武器状态切换到Switching，播放切换动画
3. 切换完成后，激活新武器，状态切换到Idle

6. 网络同步设计

• 同步武器状态（当前武器、弹药数、状态）
• 同步开火事件（射击时间戳、弹道信息）
• 服务器权威判定伤害和命中
• 客户端预测武器动作，服务器校正

7. 扩展设计

• 武器配件系统：支持瞄准镜、消音器、扩容弹夹等配件，动态修改武器属性
• 武器皮肤系统：支持武器外观自定义
• 武器升级系统：通过经验或货币提升武器性能
• 特殊武器机制：如手雷投掷、火箭筒爆炸、近战武器挥砍等
• 武器抖动和后坐力模拟：提升射击手感
• 弹道物理模拟：子弹飞行轨迹、穿透、弹道下坠等

8. 示例代码片段（开火逻辑）

void WeaponBase::Fire() {
    if (currentState != WeaponState::Idle && currentState != WeaponState::Aiming)
        return;

    if (fireCooldown > 0.0f)
        return;

    if (attributes.ammoInMagazine <= 0) {
        currentState = WeaponState::Empty;
        // 播放空弹提示音
        return;
    }

    // 触发射击逻辑（射线检测、伤害计算）
    ShootBullet();

    attributes.ammoInMagazine--;
    fireCooldown = 1.0f / attributes.fireRate;

    // 播放射击动画和音效
    PlayFireAnimation();
    PlayFireSound();

    if (attributes.ammoInMagazine == 0) {
        currentState = WeaponState::Empty;
    }
}

下面为你详细设计：

1. 武器配件系统详细设计

1.1 设计目标

• 支持多种武器配件（瞄准镜、消音器、握把、弹夹等）
• 动态修改武器属性和外观
• 支持配件的装备、拆卸和切换
• 支持配件对武器性能的影响（精准度、射速、后坐力等）
• 支持配件的等级和升级系统
• 支持网络同步配件状态

1.2 系统架构

+-------------------+
|  武器管理器       |
+-------------------+
          |
          v
+-------------------+
|  武器基类         |
+-------------------+
          |
          v
+-------------------+
|  配件管理模块     | <--- 管理当前武器配件
+-------------------+
          |
          v
+-------------------+
|  配件基类         | <--- 定义配件属性和接口
+-------------------+
          |
          v
+-------------------+
|  具体配件类       | <--- 瞄准镜、消音器等具体实现
+-------------------+

1.3 关键数据结构

enum class AttachmentType {
    Scope,
    Suppressor,
    Grip,
    Magazine,
    Laser,
    Other
};

struct AttachmentAttributes {
    float accuracyModifier;      // 精准度加成
    float recoilModifier;        // 后坐力减弱
    float fireRateModifier;      // 射速变化
    int extraAmmo;               // 弹夹容量增加
    std::string modelPath;       // 配件模型路径
    std::string iconPath;        // UI图标路径
};

class AttachmentBase {
public:
    AttachmentType type;
    AttachmentAttributes attributes;
    int level;                   // 配件等级，影响属性
    virtual void ApplyToWeapon(WeaponBase* weapon);
    virtual void RemoveFromWeapon(WeaponBase* weapon);
};

1.4 功能流程

• 装备配件：玩家选择配件，调用ApplyToWeapon，修改武器属性，更新外观
• 拆卸配件：调用RemoveFromWeapon，恢复武器原始属性，移除配件模型
• 升级配件：提升配件等级，增强属性
• 网络同步：同步配件类型和等级，保证多人游戏一致性

1.5 示例代码（装备配件）

void AttachmentBase::ApplyToWeapon(WeaponBase* weapon) {
    weapon->attributes.accuracy += attributes.accuracyModifier * level;
    weapon->attributes.recoil -= attributes.recoilModifier * level;
    weapon->attributes.fireRate += attributes.fireRateModifier * level;
    weapon->attributes.magazineCapacity += attributes.extraAmmo * level;
    weapon->UpdateModelWithAttachment(modelPath);
}

2. 武器UI界面设计

2.1 设计目标

• 显示当前武器信息（名称、弹药数、状态）
• 显示武器配件信息和状态
• 支持武器切换和配件更换操作
• 显示瞄准镜视野（可选）
• 提供清晰直观的用户交互体验

2.2 UI元素

2.3 交互设计

• 弹药计数动态更新：开火、换弹时实时刷新
• 配件图标点击：弹出配件详情和更换选项
• 武器切换快捷键：快速切换武器，UI高亮当前武器
• 状态提示动画：空弹时闪烁提示，换弹时进度条显示

2.4 示例界面布局

+------------------------------------------------+
| 武器图标  武器名称                              |
| 弹药计数: 30 / 90                              |
| [配件图标1][配件图标2][配件图标3]              |
| 状态提示: 换弹中...                            |
|                                                |
| 武器切换: [步枪][手枪][狙击枪]                 |
+------------------------------------------------+

3. 武器动画状态机设计

3.1 设计目标

• 管理武器动画状态转换
• 保证动画与武器状态同步
• 支持多种动画（开火、换弹、瞄准、切换）
• 支持动画事件回调（触发音效、粒子等）

3.2 状态定义

3.3 状态转换示意

3.4 动画事件回调

• 在动画关键帧触发事件，如：
  • 发射子弹（射线检测）
  • 弹壳抛射
  • 播放音效
  • 震动反馈

4. 多人同步细节设计

4.1 设计目标

• 保证所有玩家看到的武器状态一致
• 减少网络带宽消耗
• 支持客户端预测和服务器校正
• 处理网络延迟和丢包

4.2 同步内容

4.3 同步策略

• 状态同步：定期同步武器状态和弹药数，保证一致性
• 事件同步：开火、换弹等关键事件即时广播
• 客户端预测：客户端提前播放开火动画和音效，提升响应速度
• 服务器权威：服务器判定命中和伤害，防止作弊
• 插值平滑：客户端对状态变化进行插值，避免跳帧和卡顿

4.4 网络包示例（伪代码）

struct WeaponStateUpdate {
    int playerId;
    int weaponId;
    WeaponState state;
    int ammoInMagazine;
    int ammoReserve;
    AttachmentData attachments;
    uint64_t timestamp;
};

struct FireEvent {
    int playerId;
    int weaponId;
    Vector3 firePosition;
    Vector3 fireDirection;
    uint64_t timestamp;
};