MMOItems API Player 知识文档

概述

MMOItems API 的 Player 包提供了玩家数据管理、RPG系统集成、物品装备管理等核心功能。该包位于 net.Indyuce.mmoitems.api.player 路径下，包含多个关键类和接口。

核心类结构

1. PlayerData (主玩家数据类)

位置: net.Indyuce.mmoitems.api.player.PlayerData
继承: SynchronizedDataHolder
作用: 玩家数据的主容器，管理玩家的所有MMOItems相关数据

主要功能：

RPG玩家管理: 存储和管理RPGPlayer实例
库存解析: 通过InventoryResolver处理玩家装备和物品
冷却管理: 管理各种类型的冷却时间
状态获取: 获取玩家的统计数据和状态
数据持久化: 继承SynchronizedDataHolder的数据保存功能

关键方法：

// 获取玩家数据实例
public static PlayerData get(@NotNull OfflinePlayer player)
public static PlayerData get(UUID uuid)

// RPG玩家相关
public RPGPlayer getRPG()
public void setRPGPlayer(RPGPlayer rpgPlayer)

// 库存管理
@NotNull public InventoryResolver getInventory()
public void resolveInventory()
public boolean isEncumbered()  // 检查是否超重

// 冷却管理
public boolean isOnCooldown(CooldownType type)
public void applyCooldown(CooldownType type, double value)

// 统计数据
public double getStat(@NotNull ItemStat<?, ?> stat)

冷却类型 (CooldownType):

ELEMENTAL_ATTACK: 元素攻击冷却
SPECIAL_ATTACK: 特殊攻击冷却（如法杖右键）
BOUNCING_CRACK: 反弹裂缝冷却（防止游戏崩溃）

2. RPGPlayer (RPG系统接口)

位置: net.Indyuce.mmoitems.api.player.RPGPlayer
作用: 连接MMOItems与RPG核心插件（如MMOCore、Heroes等）的桥梁

抽象方法：

public abstract int getLevel()          // 获取玩家等级
public abstract String getClassName()   // 获取职业名称
public abstract double getMana()        // 获取当前法力值
public abstract double getStamina()     // 获取当前耐力值
public abstract void setMana(double value)
public abstract void setStamina(double value)

实用方法：

// 法力/耐力操作
public void giveMana(double value)
public void consumeMana(double value)
public void giveStamina(double value)
public void consumeStamina(double value)

// 物品使用检查
public boolean canUse(@NotNull NBTItem item, boolean message)
public boolean canUse(@NotNull NBTItem item, boolean message, boolean allowDynamic)

物品使用检查逻辑：

检查物品是否未鉴定
检查物品是否已被移除
检查所有物品限制条件（ItemRestriction）

3. EmptyRPGPlayer (空RPG玩家实现)

位置: net.Indyuce.mmoitems.api.player.EmptyRPGPlayer
继承: RPGPlayer
作用: 当RPG插件（如AureliumSkills）未及时加载玩家数据时的临时替代

特点：

所有方法返回默认值（等级0，空职业，法力/耐力为0）
用于避免空指针异常
在RPG插件加载后会被替换为真正的RPGPlayer实例

4. PlayerStats (已弃用)

位置: net.Indyuce.mmoitems.api.player.PlayerStats
状态: @Deprecated
替代: 使用 PlayerData.getStat() 和 MMOPlayerData.getStatMap()

弃用方法：

@Deprecated public double getStat(@NotNull ItemStat<?, ?> stat)
@Deprecated public StatInstance getInstance(@NotNull ItemStat<?, ?> stat)
@Deprecated public PlayerMetadata newTemporary(@NotNull EquipmentSlot castSlot)
@Deprecated public void updateStats()

5. Inventory 子包

位置: net.Indyuce.mmoitems.api.player.inventory

EquippedItem (已弃用)

位置: net.Indyuce.mmoitems.api.player.inventory.EquippedItem
状态: @Deprecated
作用: 包装内部EquippedItem类，提供API访问

方法：

@Deprecated public VolatileMMOItem getCached()
@Deprecated public NBTItem getNBT()
@Deprecated public EquipmentSlot getSlot()
@Deprecated public boolean isPlacementLegal()
@Deprecated public abstract void setItem(@Nullable ItemStack item)

EquippedItemImpl (已弃用)

位置: net.Indyuce.mmoitems.api.player.inventory.EquippedItemImpl
继承: EquippedItem
作用: EquippedItem的具体实现

API使用示例

获取玩家数据

// 获取在线玩家数据
Player player = ...;
PlayerData playerData = PlayerData.get(player);

// 获取离线玩家数据（可能返回null）
PlayerData playerDataOrNull = PlayerData.getOrNull(offlinePlayer);

检查冷却时间

PlayerData playerData = PlayerData.get(player);
if (!playerData.isOnCooldown(PlayerData.CooldownType.SPECIAL_ATTACK)) {
    // 执行特殊攻击
    playerData.applyCooldown(PlayerData.CooldownType.SPECIAL_ATTACK, 5.0); // 5秒冷却
}

获取RPG信息

PlayerData playerData = PlayerData.get(player);
RPGPlayer rpgPlayer = playerData.getRPG();

int level = rpgPlayer.getLevel();
String className = rpgPlayer.getClassName();
double mana = rpgPlayer.getMana();

// 消耗法力
rpgPlayer.consumeMana(10.0);

检查物品使用权限

NBTItem nbtItem = NBTItem.get(itemStack);
RPGPlayer rpgPlayer = PlayerData.get(player).getRPG();

if (rpgPlayer.canUse(nbtItem, true)) {
    // 玩家可以使用该物品
}

重要注意事项

1. 弃用API

PlayerStats 类已完全弃用，应使用 PlayerData.getStat() 替代
EquippedItem 相关类已弃用，应使用内部实现
许多旧方法已标记为 @Deprecated，建议使用新API

2. 数据同步

PlayerData 继承 SynchronizedDataHolder，确保数据线程安全
玩家数据在会话就绪后自动初始化库存解析器
数据保存时会自动移除修饰器

3. RPG插件集成

RPGPlayer 是抽象类，需要具体RPG插件实现
EmptyRPGPlayer 作为临时解决方案
RPGPlayer实例在玩家重新连接时重新加载

4. 冷却系统

冷却系统支持多种类型
使用 CooldownType 枚举定义冷却类型
冷却时间以秒为单位

最佳实践

总是检查玩家是否在线：使用 playerData.isOnline() 或 PlayerData.getOrNull()
处理弃用警告：及时更新代码使用新API
异步操作：库存解析等操作应考虑异步执行
错误处理：RPG插件可能未加载，准备好处理异常

版本信息

文档基于 MMOItems GitLab 仓库 master 分支
最后更新：2024年
PlayerData 最近更新：1个月前（移除TriggerMetadata使用）
PlayerStats 最近更新：10个月前（性能改进）
RPGPlayer 最近更新：6个月前（改进法力系统支持）

此文档基于对MMOItems API Player包源代码的分析，适用于插件开发者集成MMOItems功能。

Overview