🥔 HotPotato Plugin

一个功能丰富的 Minecraft 烫手山芋小游戏插件，支持多语言、排行榜、统计系统等高级功能。

A feature-rich Minecraft Hot Potato mini-game plugin with multi-language support, ranking system, statistics, and advanced features.

---

✨ 功能特性 / Features

🎮 核心游戏功能 / Core Game Features

• 🔥 烫手山芋机制 - 玩家需要快速传递山芋避免爆炸

• ⚡ 动态游戏规则 - 根据玩家数量自动调整爆炸时间和持有者数量

• 🎯 智能传递系统 - 支持近距离传递，防止作弊

• 💥 爆炸效果 - 真实的爆炸伤害和视觉效果

• 👥 多人支持 - 支持2-20+玩家同时游戏

• 🔥 Hot Potato Mechanics - Players must quickly pass the potato to avoid explosion

• ⚡ Dynamic Game Rules - Automatically adjusts explosion time and holder count based on player count

• 🎯 Smart Passing System - Supports close-range passing with anti-cheat protection

• 💥 Explosion Effects - Realistic explosion damage and visual effects

• 👥 Multiplayer Support - Supports 2-20+ players simultaneously

🎨 视觉与体验 / Visual & Experience

• ✨ 美化界面 - 彩色聊天消息、图标和格式化文本

• 📊 实时记分板 - 显示游戏状态、倒计时和玩家统计

• 🔴 视觉标识 - 持有山芋的玩家在Tab栏显示红色名字

• 💣 TNT帽子 - 持有者自动戴上TNT帽子作为视觉提示

• 🌍 多语言支持 - 支持中文和英文界面

• ✨ Beautiful Interface - Colored chat messages, icons, and formatted text

• 📊 Real-time Scoreboard - Shows game status, countdown, and player statistics

• 🔴 Visual Indicators - Potato holders show red names in Tab list

• 💣 TNT Hat - Holders automatically wear TNT hat as visual indicator

• 🌍 Multi-language Support - Supports Chinese and English interfaces

📈 统计与排行 / Statistics & Rankings

• 🏆 排行榜系统 - 显示胜场、负场和胜率统计

• 📊 个人统计 - 记录每个玩家的游戏数据

• 🔄 自动更新 - 游戏结束后立即更新排行榜

• 💾 数据持久化 - 服务器重启后数据不丢失

• 🎯 排名显示 - 美观的盔甲架排行榜展示

• 🏆 Ranking System - Shows wins, losses, and win rate statistics

• 📊 Personal Statistics - Records game data for each player

• 🔄 Auto Update - Rankings update immediately after each game

• 💾 Data Persistence - Data persists after server restarts

• 🎯 Ranking Display - Beautiful armor stand ranking displays

⚙️ 管理功能 / Administrative Features

• 🎛️ 全局记分板 - 管理员可控制记分板显示

• 📍 位置管理 - 设置游戏大厅和加入大厅位置

• 🔄 热重载 - 支持配置热重载

• 🛡️ 权限控制 - 细粒度的权限管理系统

• 📝 详细日志 - 完整的游戏事件记录

• 🎛️ Global Scoreboard - Admins can control scoreboard display

• 📍 Location Management - Set game lobby and join lobby locations

• 🔄 Hot Reload - Supports configuration hot reload

• 🛡️ Permission Control - Fine-grained permission management system

• 📝 Detailed Logging - Complete game event logging

---

🚀 安装指南 / Installation

系统要求 / System Requirements

• Java 21+ - 需要 Java 21 或更高版本

• Paper 1.21.4+ - 基于 Paper API 开发

• Minecraft 1.21.4 - 支持最新版本

• Java 21+ - Requires Java 21 or higher

• Paper 1.21.4+ - Built on Paper API

• Minecraft 1.21.4 - Supports latest version

安装步骤 / Installation Steps

1. 下载插件 / Download Plugin

   # 从 Releases 页面下载最新版本
   # Download latest version from Releases page
   

2. 放置文件 / Place Files

   # 将 .jar 文件放入服务器的 plugins 文件夹
   # Place .jar file in server's plugins folder
   

3. 启动服务器 / Start Server

   # 重启服务器以加载插件
   # Restart server to load plugin
   

4. 配置设置 / Configure Settings

   # 编辑 plugins/HotPotato/config.yml 文件
   # Edit plugins/HotPotato/config.yml file
   

---

⚙️ 配置说明 / Configuration

主要配置项 / Main Configuration

# 语言设置 / Language Settings
language: zh  # zh = 中文, en = 英文

# 游戏设置 / Game Settings
min-players: 2                    # 最少玩家数 / Minimum players
lobby-wait-seconds: 120           # 大厅等待时间 / Lobby wait time
initial-countdown: 40             # 初始倒计时 / Initial countdown
min-countdown: 15                 # 最小倒计时 / Minimum countdown

# 爆炸设置 / Explosion Settings
explosion-radius: 2.0             # 爆炸半径 / Explosion radius
explosion-damage: 100.0           # 爆炸伤害 / Explosion damage
eliminate-on-explode: true        # 爆炸时淘汰 / Eliminate on explode

# 传递设置 / Passing Settings
pass-cooldown: 1000               # 传递冷却时间 / Pass cooldown
max-pass-distance: 4.0            # 最大传递距离 / Max pass distance

# 世界边界 / World Boundaries
use-world: world                  # 使用世界 / Use world
center-x: 0.0                     # 中心X坐标 / Center X coordinate
center-z: 0.0                     # 中心Z坐标 / Center Z coordinate
radius: 64.0                      # 边界半径 / Boundary radius
out-of-bounds-damage-per-second: 2.0  # 出界伤害 / Out of bounds damage

# 其他设置 / Other Settings
elimination-reward: 0             # 淘汰奖励 / Elimination reward
anti-cheat: true                  # 反作弊 / Anti-cheat
speed-amplifier: 1                # 速度增幅 / Speed amplifier

动态游戏规则 / Dynamic Game Rules

插件会根据当前玩家数量自动调整游戏规则：

The plugin automatically adjusts game rules based on current player count:

玩家数量 / Players	爆炸时间 / Explosion Time	持有者数量 / Holders
> 9 玩家	40 秒	2 名持有者
5-9 玩家	30 秒	2 名持有者
≤ 5 玩家	30 秒	1 名持有者

---

📝 命令列表 / Commands

玩家命令 / Player Commands

命令 / Command	描述 / Description	权限 / Permission
/hotpotato join	加入游戏队列 / Join game queue	hotpotato.play
/hotpotato leave	离开游戏 / Leave game	hotpotato.play
/hotpotato status	查看游戏状态 / Check game status	hotpotato.play
/hotpotato help	显示帮助信息 / Show help	hotpotato.play

管理员命令 / Admin Commands

命令 / Command	描述 / Description	权限 / Permission
/hotpotato start	强制开始游戏 / Force start game	hotpotato.admin
/hotpotato stop	强制停止游戏 / Force stop game	hotpotato.admin
/hotpotato setlobby	设置加入大厅位置 / Set join lobby location	hotpotato.admin
/hotpotato setgamelobby	设置游戏开始位置 / Set game start location	hotpotato.admin
/hotpotato scoreboard	切换全局记分板 / Toggle global scoreboard	hotpotato.admin
/hotpotato ranking	创建/删除排行榜 / Create/remove ranking	hotpotato.admin
/hotpotato reload	重载配置 / Reload configuration	hotpotato.admin

---

🔐 权限系统 / Permissions

权限列表 / Permission List

权限 / Permission	描述 / Description	默认值 / Default
hotpotato.play	允许玩家参与游戏 / Allow players to participate	true
hotpotato.admin	允许使用管理员命令 / Allow admin commands	op

权限配置示例 / Permission Configuration Example

# LuckPerms 配置示例 / LuckPerms Configuration Example
permissions:
  - hotpotato.play
  - hotpotato.admin

---

🎯 游戏规则 / Game Rules

基本规则 / Basic Rules

1. 🎮 游戏目标 - 避免持有山芋时爆炸

2. ⏰ 时间限制 - 山芋会在倒计时结束后爆炸

3. 👥 玩家互动 - 通过右键点击其他玩家传递山芋

4. 💥 爆炸后果 - 爆炸时持有者被淘汰

5. 🏆 胜利条件 - 最后存活的玩家获胜

6. 🎮 Game Objective - Avoid holding the potato when it explodes

7. ⏰ Time Limit - Potato explodes when countdown reaches zero

8. 👥 Player Interaction - Pass potato by right-clicking other players

9. 💥 Explosion Consequence - Holder is eliminated when potato explodes

10. 🏆 Victory Condition - Last surviving player wins

高级规则 / Advanced Rules

• 🔄 动态调整 - 根据玩家数量调整游戏参数

• 🛡️ 反作弊 - 防止玩家丢弃或存储山芋

• 📏 距离限制 - 传递距离有限制

• ⏱️ 冷却时间 - 传递有冷却时间防止刷屏

• 🌍 边界系统 - 玩家不能离开游戏区域

• 🔄 Dynamic Adjustment - Game parameters adjust based on player count

• 🛡️ Anti-cheat - Prevents players from dropping or storing potato

• 📏 Distance Limit - Passing distance is limited

• ⏱️ Cooldown - Passing has cooldown to prevent spam

• 🌍 Boundary System - Players cannot leave game area

---

🛠️ 开发信息 / Development

技术栈 / Technology Stack

• Java 21 - 主要开发语言 / Main development language
• Paper API 1.21.4 - Minecraft 服务器 API / Minecraft server API
• Gradle - 构建工具 / Build tool
• Lombok - 代码简化 / Code simplification

开发环境 / Development Environment

• IDE: IntelliJ IDEA 或 Eclipse
• JDK: OpenJDK 21+
• 构建工具: Gradle 8.14+
• 测试服务器: Paper 1.21.4

---

📄 许可证 / License

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

---

🙏 致谢 / Acknowledgments

感谢所有为这个项目做出贡献的开发者和测试者！

Thanks to all developers and testers who contributed to this project!

• PaperMC - 提供优秀的服务器 API / Providing excellent server API
• Bukkit - 基础插件框架 / Basic plugin framework
• Minecraft 社区 - 持续的支持和反馈 / Continuous support and feedback

---