一个为 Timeless and Classics Zero（TACZ） 量身定制的 Bukkit/Paper 插件，用来把你的服务器与 TACZ 后端、WarvsWar 模组、Simple Voice Chat、PlaceholderAPI 串在一起，提供：

• 🔗 比赛结果 & 玩家战绩 自动上报后端
• 🏅 段位积分系统 + 段位名称
• 📊 通过 PlaceholderAPI 在记分板显示 段位 / 积分 / 排名 / K/D
• 🎧 与 Simple Voice Chat 联动的大厅禁言 & C/T 阵营语音
• 🧩 与 WarvsWar 模组的无侵入集成（通过 Java API + 反射）

---

• ✅ 对接 TACZ Web 后端（见 mc_api.md）

  • /api/mc/player/check：玩家进服资格校验
  • /api/mc/player/sync：玩家战绩同步
  • /api/mc/match/report：比赛结果上报
  • /api/mc/rank/player：玩家段位 / 排名 / K/D 查询（见 api.md）

• 🏆 段位与积分系统

  • 服务端通过 API 返回积分，插件本地用 RankUtil 映射成段位名称
  • 段位区间示例：
    • 1000–1099：战术学员
    • …
    • 4500+：统治者

• 📈 PlaceholderAPI 记分板占位符

  • tacz_rank：当前段位名称（例：战术大师）
  • tacz_points：当前积分
  • tacz_top：全服排名
  • player_kdr / tacz_kdr：K/D 比值

• 🎧 Simple Voice Chat 联动（见 TaczVoicechatPlugin）

  • 大厅世界 world：默认禁言
    • 不在任何语音组 → 不允许发送语音
    • 在任意语音组 → 可以说话
  • 进入 WarvsWar 对局后：
    • 根据新 WarvsWar API 提供的 WarTeam / getTeam() 自动把玩家分配到：
      • C 阵营语音组
      • T 阵营语音组
    • C 只听 C，T 只听 T，互相隔离

• ⚔️ WarvsWar 模组深度对接

  • 通过 WarMatchApi + WarMatchListener：
    • onMatchStart(WarMatchContext)：对局开始时，根据 C/T 阵营绑定语音组
    • onMatchEnd(WarMatchSummary)：对局结束时上报比赛结果和玩家战绩
  • 比赛结束后自动把玩家传送回大厅世界 world 出生点

---

• 服务器：Bukkit / Spigot / Paper（推荐 1.20+）
• 插件 / 模组依赖：
  • ✅ 必需：TACZ Web 后端（mc_api.md 中描述的接口）
  • ✅ 推荐：WarvsWar 模组（并实现 war_api.md 与 war_new_api.md 中的 Java API）
  • ✅ 推荐：Simple Voice Chat（并启用 voicechat-api）
  • ✅ 推荐：PlaceholderAPI（用于记分板显示数据）

在 build.gradle 中：

• spigot-api 作为 compileOnly
• PlaceholderAPI 作为 compileOnly
• Simple Voice Chat voicechat-api 作为 implementation（仅 API，不会自带模组）

---

配置文件：src/main/resources/config.yml

• api.base-url
  • TACZ 后端地址，例如：https://tacz.mingpixel.net
• api.server-api-key
  • 当前服务器的 API Key，用于鉴权

• features.player-check-enabled
  • 是否启用玩家进服资格校验（/api/mc/player/check）

（如需扩展其他开关，可以在此节继续增加字段）

---

• 基本用法：/taczmc <check|sync|matchdemo> ...
• 权限：
  • tacz.admin：使用 /taczmc 命令
  • tacz.admins：加入服务器时接收 WarvsWar 对接状态提示（默认 OP）

注意：原本的 /tacz 命令为了避免与模组冲突，已经改名为 /taczmc。

---

插件在加载时会自动检测 PlaceholderAPI，如存在则注册 tacz 前缀的扩展。

可用占位符（以 %...% 形式使用）：

• 段位：%tacz_rank%
• 积分：%tacz_points%
• 排名：%tacz_top%
• K/D：
  • %tacz_player_kdr%
  • %tacz_kdr%

K/D 计算规则：

• deaths == 0 && kills == 0 → 0.00
• deaths == 0 && kills > 0 → 显示 kills（两位小数）
• 否则 → kills / deaths（保留两位小数）

你可以在任意支持 PlaceholderAPI 的记分板插件中使用这些占位符。

---

由 TaczVoicechatPlugin 负责：

• 插件启用时：

  • 尝试通过 BukkitVoicechatService 注册到 Simple Voice Chat
  • 如果未安装 Simple Voice Chat，则跳过语音逻辑，其他功能不受影响

• 大厅禁言：

  • 在世界名为 world 的大厅：
    • 未加入任何语音组的玩家 → 所有语音包被拦截（禁言）
    • 已加入任意语音组的玩家 → 可以正常使用语音

• 阵营语音：

  • 使用 WarvsWar 新接口 onMatchStart(WarMatchContext) 获取每个玩家的 WarTeam：
    • 阵营为 C → 加入 C 阵营语音组
    • 阵营为 T → 加入 T 阵营语音组
  • Simple Voice Chat 的 Group 机制保证：
    • C 只听到 C 队友的声音
    • T 只听到 T 队友的声音
    • 阵营之间完全隔音

---

详细 Java 接口定义请见：

• war_api.md：原始 WarvsWar × TACZ 后端对接说明
• war_new_api.md：为语音与阵营扩展设计的新接口需求（模组已实现）

插件通过反射方式集成：

• 自动检测 com.warvswar.WarvsWar 和 com.warvswar.common.api.* 是否存在
• 如存在：
  • 获取 WarMatchApi 实例
  • 注册 WarMatchListener 监听器
  • 在：
    • onMatchStart 中做语音阵营分组
    • onMatchEnd 中上报比赛与玩家战绩，并将玩家传回大厅
• 如不存在：
  • 在控制台打印一行提示，跳过 WarvsWar 对接，插件仍可独立运行

---

构建命令（根目录）：

./gradlew build -x test

输出插件 Jar：

• build/libs/ 目录下

开发时可使用 run-paper 插件在本地快速启动 Paper 服务器（详见 build.gradle 中的 runServer 任务配置）。

---

• mc_api.md：TACZ 后端 HTTP 接口文档
• war_api.md：旧版 WarvsWar Java API 说明
• war_new_api.md：新版 WarvsWar × TACZ × 语音 联动接口需求（模组已实现）
• api.md：TACZ 段位 / 排名查询等扩展 API

如果你在接入过程中遇到任何问题（例如 API 字段对不上、语音行为与预期不符等），可以根据这些文档快速定位是「后端」还是「模组」或「插件」的问题。