转载 游戏模式 CDuels 1.0

[MD]
## 简介

CDuels 是一款面向 Paper 1.21-26.2. 服务端的高度可配置 1v1 PvP 对决插件。插件提供基于 GUI 的装备套件选择、简洁的竞技场管理、详细的对决统计数据，以及不会给服务器带来明显负担的管理工具。

# CDuels

**CDuels** 是一款面向 Paper 1.21-26.2. 服务端的高度可配置 1v1 PvP 对决插件。插件提供基于 GUI 的装备套件选择、简洁的竞技场管理、详细的对决统计数据，以及不会给服务器带来明显负担的管理工具。

## 功能特色

- **GUI 菜单：** 可在 `menu.yml` 中完整自定义菜单布局、标题、物品和 Lore 描述。
- **游戏内套件编辑器：** 可直接在游戏中创建和编辑套件，并提供专用的布局指引菜单，方便正确设置盔甲栏与副手栏物品。
- **竞技场设置：** 支持创建多个竞技场，并可选择竞技场轮换方式：**随机**、**轮流**或**优先使用最先空闲的竞技场**。
- **实时设置 GUI：** 通过可视化设置菜单即时启用或关闭功能、调整数值；按钮会动态显示当前功能的启用状态。
- **统计与历史记录：** 记录胜场、败场、总对局数、造成伤害和承受伤害。数据可使用 YAML 本地保存，也可连接 MySQL 数据库。
- **扩展支持：** 原生支持 PlaceholderAPI、使用 WorldGuard 区域检查控制观战，并内置 Modrinth 更新检查器。

## 使用方法

### 玩家使用

1. **发起挑战：** 使用 `/duel <player>` 向其他玩家发起挑战。每名玩家同一时间只能发送一个待处理的挑战请求。
2. **选择套件：** 在弹出的 GUI 菜单中选择本场对决使用的战斗套件。
3. **接受或拒绝：** 被挑战者可以接受或拒绝请求；请求会在设定的超时时间后自动失效。
4. **进行对决：** 对决结束后，胜者会看到“你赢了”标题，败者会看到“`<player>` 获胜”。副标题会说明对局是否因死亡、退出游戏或离开对决而结束。

### 管理员使用

1. **设置竞技场：** 执行 `/dueladmin create`，按照引导设置出生点和竞技场边界。
2. **创建套件：** 将所需物品放入背包后输入 `/dueladmin kitcreate`。如需调整物品栏位，请使用布局指引功能。
3. **实时管理：** 使用 `/duelsadmin` 或 `/dueladmin settings` 打开实时配置 GUI，或重新加载配置文件。

## 命令

| 命令 | 别名 | 说明 |
| :--- | :--- | :--- |
| `/duel <player>` | `/cd` | 向指定玩家发起 1v1 对决挑战。 |
| `/duelaccept` | | 接受待处理的对决请求。 |
| `/dueldeny` | | 拒绝待处理的对决请求。 |
| `/duels <subcommand>` | | 玩家主命令入口。 |
| `/dueladmin <subcommand>` | | 竞技场与套件管理主命令入口。 |
| `/duelsadmin` | | 打开管理员设置 GUI。 |

### `/duels` 子命令

- `help`：显示帮助菜单。
- `list [page]`：查看正在进行的对决和竞技场状态。
- `top <wins\|winrate\|damage> [page]`：查看排行榜。
- `leaderboard <wins\|winrate\|damage> [page]`：查看排行榜。
- `stats [player]`：查看自己或其他玩家的 PvP 统计数据。
- `history <player> [page]`：查看指定玩家近期的对局历史。
- `cancel <player>`：取消已发出的挑战请求。
- `spectate <player>`：开始观战一场正在进行的对决。
- `stopspectate`：停止观战并返回原来的位置。
- `leave`：认输并离开当前对决。
- `viewkit`：查看挑战中使用的套件物品。

### `/dueladmin` 子命令

- `create` / `edit` / `list` / `remove`：创建、编辑、列出或删除竞技场。
- `kitcreate` / `kitedit` / `kitremove`：创建、编辑或删除套件。
- `reload`：重新加载 `config.yml`、`menu.yml`、`messages.yml` 和 `mysql.yml`。
- `settings`：打开实时设置 GUI。

## 权限

| 权限节点 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `cduels.command` | `true` | 标准玩家命令的基础权限。 |
| `cduels.command.duel` | `true` | 允许使用 `/duel`、观战、查看套件及离开对决。 |
| `cduels.command.duels` | `true` | 允许访问 `/duels` 实用命令入口。 |
| `cduels.command.duelaccept` | `true` | 允许接受挑战请求。 |
| `cduels.command.dueldeny` | `true` | 允许拒绝挑战请求。 |
| `cduels.command.duels.history` | `op` | 允许查看玩家对决历史。 |
| `cduels.command.dueladmin` | `op` | 允许使用主要管理员设置命令。 |
| `cduels.command.duelsadmin` | `op` | 允许打开主配置 GUI。 |
| `cduels.admin` | `op` | 完整管理员权限，包含重载和管理功能。 |

## PlaceholderAPI 变量

在计分板、玩家列表栏或菜单中使用带有 `%cd_<placeholder>%` 前缀的变量。

### 竞技场与服务器状态

- `%cd_total_arenas%`：已配置的竞技场总数。
- `%cd_arenas_available%` / `%cd_free_arenas%`：空闲且可用的竞技场数量。
- `%cd_arenas_unavailable%` / `%cd_busy_arenas%`：当前正在使用的竞技场数量。
- `%cd_total_duels%` / `%cd_current_duels%` / `%cd_active_fights%`：正在进行的对局数量。
- `%cd_players_dueling%` / `%cd_dueling_users%` / `%cd_users_dueling%`：当前正在战斗的玩家总数。
- `%cd_total_kits%`：已创建的套件总数。
- `%cd_spectators%`：当前观战者总数。

### 玩家统计

- `%cd_wins%` / `%cd_player_wins%` / `%cd_stats_wins%`：对决胜场总数。
- `%cd_losses%` / `%cd_player_losses%` / `%cd_stats_losses%`：对决败场总数。
- `%cd_battles%` / `%cd_battles_played%` / `%cd_matches_played%`：参与对决总数。
- `%cd_damage_dealt%` / `%cd_total_damage_dealt%`：所有对局中的累计造成伤害。
- `%cd_damage_taken%` / `%cd_total_damage_taken%`：所有对局中的累计承受伤害。
- `%cd_winrate%` / `%cd_win_rate%`：玩家胜率百分比。

### 当前对局变量

- `%cd_current_kit%` / `%cd_kit_used%` / `%cd_kit_use%`：当前对决使用的套件。
- `%cd_opponent_name%` / `%cd_opponent%`：对手名称。
- `%cd_opponent_health%`：对手当前生命值。
- `%cd_your_health%` / `%cd_self_health%` / `%cd_health%`：自身当前生命值。
- `%cd_in_duel%` / `%cd_is_dueling%`：检查玩家是否正处于对决中。
[/MD]