Equipment 类详细使用方法

类概述

Equipment 类是玩家装备系统的核心组件，负责管理装备的穿戴、卸下、属性加成计算等功能，通过与玩家对象和背包组件交互，实现装备系统的完整逻辑。

构造函数

public function __construct($player)

• 功能：初始化装备组件，加载配置并设置初始状态
• 参数：
  • $player (Player)：玩家对象实例，用于关联玩家数据和其他组件
• 初始化流程：
  1. 加载装备槽位配置（equipment_slots）和装备配置（equipment）
  2. 初始化装备槽位为空状态

核心方法说明

1. 获取装备属性总加成

public function getEquipAttrs() : array

• 功能：计算并返回所有已穿戴装备的属性总加成（带缓存机制）
• 返回值：关联数组，格式如 ['attack' => 25, 'defense' => 10]
• 缓存机制：
  • 首次调用计算并缓存结果
  • 装备变动时自动清空缓存，确保数据准确性
• 使用示例：

  // 获取玩家装备的总属性加成
  $totalAttrs = $player->getComponent('Equipment')->getEquipAttrs();
  echo "总攻击力加成: " . ($totalAttrs['attack'] ?? 0);

2. 穿戴装备

public function equip($itemId) : array

• 功能：将指定装备穿戴到对应槽位
• 参数：
  • $itemId (string)：装备ID（需在装备配置中存在）
• 返回值：操作结果数组，包含：
  • success (bool)：操作是否成功
  • msg (string)：操作结果描述
• 执行流程：
  1. 验证装备ID格式有效性
  2. 检查装备配置是否存在
  3. 验证装备对应的槽位是否有效
  4. 检查玩家等级是否满足装备要求
  5. 检查背包中是否有该装备
  6. 若目标槽位已有装备，自动卸下
  7. 从背包移除装备并更新槽位信息
  8. 触发 equipment_equipped 事件
  9. 清空缓存并返回成功信息
• 使用示例：

  // 穿戴木剑
  $result = $player->getComponent('Equipment')->equip('wooden_sword');
  if ($result['success']) {
    echo $result['msg']; // 输出: 成功穿戴【木剑】
  } else {
    echo "穿戴失败: " . $result['msg'];
  }

3. 卸下装备

public function unequip($slot) : array

• 功能：将指定槽位的装备卸下并放回背包
• 参数：
  • $slot (string)：装备槽位标识（如 weapon、armor 等）
• 返回值：操作结果数组，包含 success 和 msg 字段
• 执行流程：
  1. 验证槽位是否有效
  2. 检查槽位是否有装备
  3. 将装备放回玩家背包
  4. 清空槽位信息
  5. 触发 equipment_unequipped 事件
  6. 清空缓存并返回结果
• 使用示例：

  // 卸下武器槽的装备
  $result = $player->getComponent('Equipment')->unequip('weapon');
  if ($result['success']) {
    echo $result['msg']; // 输出: 成功卸下【木剑】
  }

4. 获取已穿戴装备信息

public function getEquipped() : array

• 功能：获取所有槽位的装备信息（带缓存）
• 返回值：格式化的装备列表，结构如下：

  [
    'weapon' => [
        'slot_name' => '武器',
        'equipment' => [
            'id' => 'wooden_sword',
            'name' => '木剑',
            'attrs' => ['attack' => 5]
        ]
    ],
    'armor' => [
        'slot_name' => ' armor',
        'equipment' => null // 无装备时为null
    ]
    // 其他槽位...
  ]

• 使用示例：

  $equipped = $player->getComponent('Equipment')->getEquipped();
  foreach ($equipped as $slot => $info) {
    echo $info['slot_name'] . ": " . 
         ($info['equipment'] ? $info['equipment']['name'] : '无') . "<br>";
  }

5. 序列化与反序列化

// 序列化：将装备数据转换为可存储格式
public function serialize() : array

// 反序列化：从存储数据恢复装备状态
public function unserialize($data) : void

• 功能：用于装备数据的持久化存储和恢复
• 使用示例：

  
  // 保存装备数据
  $saveData = $player->getComponent('Equipment')->serialize();
  $_SESSION['player_equipment'] = $saveData;

// 恢复装备数据 $equipment = $player->getComponent('Equipment'); $equipment->unserialize($_SESSION['player_equipment']);

### 6. 其他辅助方法
```php
// 获取原始数据（主要用于调试）
public function getRawData() : array

// 清空缓存（装备变动时自动调用）
private function clearCache() : void

事件触发说明

装备系统会触发两种事件，可通过 EventManager 监听：

1. equipment_equipped：装备穿戴成功时触发

   • 事件参数：player（玩家对象）、equipment_id（装备ID）、equipment（装备配置）

2. equipment_unequipped：装备卸下成功时触发

   • 事件参数：同上

配置依赖

该类依赖以下配置文件：

• equipment_slots.php：定义装备槽位（如武器、 armor等）
• equipment.php：定义所有装备的详细信息（包含名称、槽位、属性、等级要求等）

典型使用场景

1. 装备界面展示：使用 getEquipped() 获取所有装备信息并展示
2. 战斗属性计算：通过 getEquipAttrs() 获取属性加成，计算玩家总属性
3. 装备操作处理：响应用户穿戴/卸下装备的请求，调用 equip() 和 unequip() 方法
4. 数据持久化：游戏存档/读档时使用 serialize() 和 unserialize() 处理装备数据