# KartaEmeraldCurrency
KartaEmeraldCurrency 是一个为 PaperMC 服务器设计的现代、高性能经济插件，以原版翡翠物品为核心货币。它具有虚拟银行系统、交互式 GUI 和强大的开发者 API，使其成为任何服务器的通用且稳定的选择。
它专为高效和安全而设计，所有数据库操作均以异步方式处理，以防止服务器卡顿。
**兼容性：** PaperMC 1.21 – 1.21.8 (Java 21+)
## 特性
- **翡翠经济：** 使用实物翡翠进行存款和取款。
- **虚拟银行：** 在安全的虚拟银行账户中存储你的翡翠，免受物品栏丢失的困扰。
- **交互式 GUI：** 用于所有常见操作的现代化且易于使用的 GUI，可通过 `/emerald` 访问。
- **主菜单：** 显示你的账户余额摘要。
- **银行 GUI：** 专用的界面，用于存款和取款翡翠。 可以单击一次性从你的物品栏中存入所有翡翠，或者通过在聊天中输入数值来存入/取出一个自定义金额。
- **Vault 集成：** 可以作为任何 Vault 兼容插件的主要经济提供者。
- **PlaceholderAPI 支持：** 一套完整的占位符，用于在积分板、聊天等处显示经济数据。
- **开发者 API：** 用于其他插件与经济交互的干净、异步 API。
- **异步 & 高性能：** 所有数据库 I/O 都是异步的，以确保你的服务器保持流畅运行。
- **可配置：** 几乎每个方面，从费用到消息，都可以进行自定义。
## 安装
1. 从 [Releases](https://github.com/your-repo-link/releases) 页面下载最新版本。
2. 将 `KartaEmeraldCurrency-x.x.x.jar` 文件放入服务器的 `/plugins` 目录中。
3. 重启你的服务器。 默认配置文件将生成在 `/plugins/KartaEmeraldCurrency/` 目录中。
## 命令 & 权限
### 用户命令 (`/emerald` 或 `/kec`)
与经济交互的主要方式是通过主 GUI (`/emerald`)。 虽然可能存在一些直接命令，但 GUI 提供了访问所有功能，包括银行、转账和排行榜。
| 命令 | 权限 | 描述 |
|---|---|---|
| `/emerald` | `kec.gui` | 打开主交互式 GUI。 |
| `/emerald balance` | `kec.balance` | 显示你的当前银行、钱包和总余额。 |
| `/emerald pay ` | `kec.pay` | 从你的银行账户向其他玩家付款。 |
| `/emerald deposit ` | `kec.deposit` | 将实物翡翠存入你的银行。 |
| `/emerald withdraw ` | `kec.withdraw` | 将翡翠从你的银行取出到你的物品栏。 |
| `/emerald top` | `kec.top` | 显示最富有的玩家排行榜。 |
| `/emerald help` | `kec.help` | 显示帮助消息。 |
### 管理员命令 (`/emeraldadmin` 或 `/kecadmin`)
所有管理员命令都需要基础权限 `kec.admin` 或分层权限。
| 命令 | 权限 | 描述 |
|---|---|---|
| `/kecadmin set ` | `kec.admin.set` | 设置玩家的银行余额。 |
| `/kecadmin add ` | `kec.admin.add` | 增加玩家的银行余额。 |
| `/kecadmin remove ` | `kec.admin.remove` | 减少玩家的银行余额。 |
| `/kecadmin give ` | `kec.admin.give` | 给玩家实物翡翠。 |
| `/kecadmin take ` | `kec.admin.take` | 从玩家那里拿走实物翡翠。 |
| `/kecadmin reload` | `kec.admin.reload` | 重新加载配置文件。 |
| `/kecadmin migrate ` | `kec.admin.migrate` | 将数据从一种存储类型迁移到另一种存储类型（例如，SQLITE 到 MYSQL）。 |
## 占位符
需要 [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.624/)。
- `%kartaemerald_balance%` - 玩家的总银行余额。
- `%kartaemerald_balance_formatted%` - 玩家的银行余额，带后缀（例如，1.2k）。
- `%kartaemerald_balance_comma%` - 玩家的银行余额，带逗号（例如，1,234,567）。
- `%kartaemerald_bank%` - `%kartaemerald_balance%` 的别名。
- `%kartaemerald_wallet%` - 玩家在物品栏中拥有的实物翡翠数量。
- `%kartaemerald_top_<1-10>_name%` - **(尚未实现)** 排行榜上第 N 名玩家的姓名。
- `%kartaemerald_top_<1-10>_amount%` - **(尚未实现)** 排行榜上第 N 名玩家的余额。
**关于自定义占位符的说明：** 在配置文件 (`gui.yml`、`messages.yml`) 中，你可以使用上下文特定占位符。 这些占位符使用 `` 格式，与 [MiniMessage](https://docs.adventure.kyori.net/minimessage/format.html#placeholder) 库兼容。 例如，在排行榜 GUI 中，你可以使用 ``、`` 和 ``。
## 开发者 API
KartaEmeraldCurrency 提供了一个干净、易于使用的 API，供开发者使用。 所有数据相关的函数都是异步的，并返回一个 `CompletableFuture`。
### 访问 API
首先，从 Bukkit 的 `ServicesManager` 获取服务。
```java
import com.minekarta.kec.api.KartaEmeraldService;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;
public class MyPlugin {
private KartaEmeraldService economyService;
public void onEnable() {
RegisteredServiceProvider rsp = Bukkit.getServicesManager().getRegistration(KartaEmeraldService.class);
if (rsp != null) {
this.economyService = rsp.getProvider();
}
}
}
```
### 使用示例：向玩家付款
```java
import com.minekarta.kec.api.TransferReason;
public void rewardPlayer(Player player, long amount) {
if (economyService != null) {
// 使用空 UUID 作为 'from' 参数来转账给无人 (服务器) 不支持。
// 而是使用 addBankBalance 方法进行服务器到玩家的交易。
economyService.addBankBalance(player.getUniqueId(), amount).thenAccept(success -> {
if (success) {
player.sendMessage("你获得了 " + amount + " 翡翠！");
}
});
}
}
```