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. 其他辅助方法

// 获取原始数据（主要用于调试）
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() 处理装备数据