🛠 EssentialsX API 使用方法知识库（概要）

🔍 核心 API 结构简介

EssentialsX Javadoc 索引显示大量类与方法定义，其中常用的 API 分类如下：([jd-v2.essentialsx.net][3])

核心插件接口
- net.ess3.api.IEssentials — 插件核心接口，提供基础服务入口。
- com.earth2me.essentials.Essentials — 主插件类实现，可以通过 Bukkit 插件管理器获取。
经济与余额
- com.earth2me.essentials.api.Economy — 经济操作接口。
  - add(UUID, BigDecimal) / add(User, BigDecimal) — 增加余额。([jd-v2.essentialsx.net][3])
用户与事件
- 多种事件类定义在 net.ess3.api.events 包。
  - AfkStatusChangeEvent — 玩家 AFK 状态变化事件。([jd-v2.essentialsx.net][3])

🔑 3. 获取 EssentialsX 核心插件实例

JavaPlugin 中获取

import org.bukkit.plugin.Plugin;
import net.ess3.api.IEssentials;
import org.bukkit.Bukkit;

Plugin plugin = Bukkit.getServer().getPluginManager().getPlugin("Essentials");
if (plugin instanceof IEssentials) {
    IEssentials ess = (IEssentials) plugin;
    // 现在可以通过 ess 调用 Essentials API 功能
}

IEssentials 是 EssentialsX API 的核心接口。
如果你想访问实现类，实际插件实现为 com.earth2me.essentials.Essentials。([jd-v2.essentialsx.net][4])

💰 4. 经济（Balance）操作

EssentialsX API 提供基础经济操作接口，可在插件中对玩家余额进行增减：

查询余额

BigDecimal balance = ess.getUser(player.getUniqueId()).getMoney();

具体方法可通过 Essentials API 具体接口查阅 Javadoc。([jd-v2.essentialsx.net][3])

增加余额

com.earth2me.essentials.api.Economy.add(player.getUniqueId(), BigDecimal.valueOf(100));

扣除余额

com.earth2me.essentials.api.Economy.add(player.getUniqueId(), BigDecimal.valueOf(-50));

推荐使用 UUID 版本而不是玩家名，以兼容改名等情况。([jd-v2.essentialsx.net][3])

👥 5. 用户与状态相关 API

EssentialsX 中定义了多个用户相关的实用类与事件：

示例事件：AFK 状态变化

@EventHandler
public void onAfkChange(AfkStatusChangeEvent event) {
    boolean isAfk = event.isAfk();
    // 处理玩家 AFK 状态变化
}

该事件包含事件原因枚举等信息，可在 Javadoc 中查阅详细字段。([jd-v2.essentialsx.net][3])

📌 6. 其他 API 入口示例

EssentialsX Javadoc 索引中还有大量方法，例如：

工具类方法

com.earth2me.essentials.utils.StringUtil.abbreviate(String input, int length);

用于字符串处理等辅助功能。([jd-v2.essentialsx.net][3])

玩家背包/物品帮助类

com.earth2me.essentials.craftbukkit.Inventories.addItem(Player player, ItemStack... items);

用于直接操作玩家背包。([jd-v2.essentialsx.net][3])

🧠 7. 新增服务（BalanceTop API）

EssentialsX 除了直接 API 外，还支持通过 Bukkit 服务管理器加载一项服务，例如余额排行榜：

import net.essentialsx.api.v2.services.BalanceTop;

BalanceTop balanceTop = Bukkit.getServicesManager().load(BalanceTop.class);

balanceTop.calculateBalanceTopMapAsync().thenAccept(cache -> {
    // 处理余额排行榜缓存
});

这种服务式 API 适合异步和功能扩展场景。([CurseForge][1])

💡 注意事项与推荐实践

优先使用 API 包：
对外稳定 API 通常在 net.essentialsx.api.v2、net.ess3.api、com.earth2me.essentials.api 包中。其他内部类可能随版本改变。([CurseForge][1])
不要直接依赖内部实现：
核心实现类（如 com.earth2me.essentials.Essentials）可以获取功能，但建议通过 API 接口调用逻辑功能。
使用 UUID 而不是玩家名：
EssentialsX 旧版 API 有一些方法仍接收字符串玩家名，但建议使用 UUID 以确保兼容性。

EssentialsX API 知识库

Overview