Equipment 类详细使用方法

类概述

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

构造函数

public function __construct($player)<br />
```<br />
- **功能**：初始化装备组件，加载配置并设置初始状态<br />
- **参数**：<br />
  - `$player` (Player)：玩家对象实例，用于关联玩家数据和其他组件<br />
- **初始化流程**：<br />
  1. 加载装备槽位配置（`equipment_slots`）和装备配置（`equipment`）<br />
  2. 初始化装备槽位为空状态<br />
<br />
## 核心方法说明<br />
<br />
### 1. 获取装备属性总加成<br />
```php<br />
public function getEquipAttrs() : array<br />
```<br />
- **功能**：计算并返回所有已穿戴装备的属性总加成（带缓存机制）<br />
- **返回值**：关联数组，格式如 `['attack' => 25, 'defense' => 10]`<br />
- **缓存机制**：<br />
  - 首次调用计算并缓存结果<br />
  - 装备变动时自动清空缓存，确保数据准确性<br />
- **使用示例**：<br />
```php<br />
// 获取玩家装备的总属性加成<br />
$totalAttrs = $player->getComponent('Equipment')->getEquipAttrs();<br />
echo "总攻击力加成: " . ($totalAttrs['attack'] ?? 0);<br />
```<br />
<br />
### 2. 穿戴装备<br />
```php<br />
public function equip($itemId) : array<br />
```<br />
- **功能**：将指定装备穿戴到对应槽位<br />
- **参数**：<br />
  - `$itemId` (string)：装备ID（需在装备配置中存在）<br />
- **返回值**：操作结果数组，包含：<br />
  - `success` (bool)：操作是否成功<br />
  - `msg` (string)：操作结果描述<br />
- **执行流程**：<br />
  1. 验证装备ID格式有效性<br />
  2. 检查装备配置是否存在<br />
  3. 验证装备对应的槽位是否有效<br />
  4. 检查玩家等级是否满足装备要求<br />
  5. 检查背包中是否有该装备<br />
  6. 若目标槽位已有装备，自动卸下<br />
  7. 从背包移除装备并更新槽位信息<br />
  8. 触发 `equipment_equipped` 事件<br />
  9. 清空缓存并返回成功信息<br />
- **使用示例**：<br />
```php<br />
// 穿戴木剑<br />
$result = $player->getComponent('Equipment')->equip('wooden_sword');<br />
if ($result['success']) {<br />
    echo $result['msg']; // 输出: 成功穿戴【木剑】<br />
} else {<br />
    echo "穿戴失败: " . $result['msg'];<br />
}<br />
```<br />
<br />
### 3. 卸下装备<br />
```php<br />
public function unequip($slot) : array<br />
```<br />
- **功能**：将指定槽位的装备卸下并放回背包<br />
- **参数**：<br />
  - `$slot` (string)：装备槽位标识（如 `weapon`、`armor` 等）<br />
- **返回值**：操作结果数组，包含 `success` 和 `msg` 字段<br />
- **执行流程**：<br />
  1. 验证槽位是否有效<br />
  2. 检查槽位是否有装备<br />
  3. 将装备放回玩家背包<br />
  4. 清空槽位信息<br />
  5. 触发 `equipment_unequipped` 事件<br />
  6. 清空缓存并返回结果<br />
- **使用示例**：<br />
```php<br />
// 卸下武器槽的装备<br />
$result = $player->getComponent('Equipment')->unequip('weapon');<br />
if ($result['success']) {<br />
    echo $result['msg']; // 输出: 成功卸下【木剑】<br />
}<br />
```<br />
<br />
### 4. 获取已穿戴装备信息<br />
```php<br />
public function getEquipped() : array<br />
```<br />
- **功能**：获取所有槽位的装备信息（带缓存）<br />
- **返回值**：格式化的装备列表，结构如下：<br />
```php<br />
[<br />
    'weapon' => [<br />
        'slot_name' => '武器',<br />
        'equipment' => [<br />
            'id' => 'wooden_sword',<br />
            'name' => '木剑',<br />
            'attrs' => ['attack' => 5]<br />
        ]<br />
    ],<br />
    'armor' => [<br />
        'slot_name' => ' armor',<br />
        'equipment' => null // 无装备时为null<br />
    ]<br />
    // 其他槽位...<br />
]<br />
```<br />
- **使用示例**：<br />
```php<br />
$equipped = $player->getComponent('Equipment')->getEquipped();<br />
foreach ($equipped as $slot => $info) {<br />
    echo $info['slot_name'] . ": " . <br />
         ($info['equipment'] ? $info['equipment']['name'] : '无') . "<br>";<br />
}<br />
```<br />
<br />
### 5. 序列化与反序列化<br />
```php<br />
// 序列化：将装备数据转换为可存储格式<br />
public function serialize() : array<br />
<br />
// 反序列化：从存储数据恢复装备状态<br />
public function unserialize($data) : void<br />
```<br />
- **功能**：用于装备数据的持久化存储和恢复<br />
- **使用示例**：<br />
```php<br />
// 保存装备数据<br />
$saveData = $player->getComponent('Equipment')->serialize();<br />
$_SESSION['player_equipment'] = $saveData;<br />
<br />
// 恢复装备数据<br />
$equipment = $player->getComponent('Equipment');<br />
$equipment->unserialize($_SESSION['player_equipment']);<br />
```<br />
<br />
### 6. 其他辅助方法<br />
```php<br />
// 获取原始数据（主要用于调试）<br />
public function getRawData() : array<br />
<br />
// 清空缓存（装备变动时自动调用）<br />
private function clearCache() : void<br />
```<br />
<br />
## 事件触发说明<br />
装备系统会触发两种事件，可通过 `EventManager` 监听：<br />
<br />
1. `equipment_equipped`：装备穿戴成功时触发<br />
   - 事件参数：`player`（玩家对象）、`equipment_id`（装备ID）、`equipment`（装备配置）<br />
<br />
2. `equipment_unequipped`：装备卸下成功时触发<br />
   - 事件参数：同上<br />
<br />
## 配置依赖<br />
该类依赖以下配置文件：<br />
- `equipment_slots.php`：定义装备槽位（如武器、 armor等）<br />
- `equipment.php`：定义所有装备的详细信息（包含名称、槽位、属性、等级要求等）<br />
<br />
## 典型使用场景<br />
1. **装备界面展示**：使用 `getEquipped()` 获取所有装备信息并展示<br />
2. **战斗属性计算**：通过 `getEquipAttrs()` 获取属性加成，计算玩家总属性<br />
3. **装备操作处理**：响应用户穿戴/卸下装备的请求，调用 `equip()` 和 `unequip()` 方法<br />
4. **数据持久化**：游戏存档/读档时使用 `serialize()` 和 `unserialize()` 处理装备数据