ExooQueue – 队列管理插件(Paper 1.21)
概述
- ExooQueue 限制主世界中的玩家数量,并将溢出玩家排队至等待世界。
- 玩家可以查看自己的队列位置及预计等待时间 (ETA)。
- VIP 玩家(通过权限或 /vip 命令授予)可跳过队列。
- 命令和操作均可配置。操作可以玩家身份或控制台身份运行,并支持 %player_name% 和 PlaceholderAPI(如果已安装)。
- 初始化了 SQLite 以用于未来的持久化存储(目前尚未实际使用)。
要求
- Multiverse core(用于定义等待世界和其他世界)
- 服务器:Paper 1.21.x
- Java:21 (JDK/JRE)
- 可选:PlaceholderAPI(用于操作中的高级占位符)
- 可选:一个世界管理插件,如果你在操作中使用了类似 "mvtp" 的命令(例如 Multiverse-Core)
文件
- src/main/resources/plugin.yml → Bukkit 命令/权限声明
- src/main/resources/config.yml → 插件配置(世界、队列、命令 + 操作)
- src/main/java/.../ExooQueuePlugin.java → 主插件类
- build.gradle, settings.gradle → Gradle 构建文件
安装(使用编译好的 JAR 包)
- 将 build/libs/ExooQueue-1.0.0.jar 复制到你的 Paper 服务器 "plugins" 文件夹中。
- 启动服务器一次以生成 config.yml。
- 停止服务器并根据需要编辑 plugins/ExooQueue/config.yml。
- 再次启动服务器。
构建(如果你需要重新编译)
- 从项目根目录执行:./gradlew build(Linux/macOS)或 .\gradlew.bat build(Windows)
- 输出的 JAR 包:build/libs/ExooQueue-1.0.0.jar
核心概念
- 主世界:玩家想要加入的目标世界(例如 "world")。
- 等待世界:排队玩家所在的大厅世界。
- 最大玩家数:当主世界达到此人数时,额外添加的玩家将被排队。
- VIP 跳过:拥有 "exooqueue.vip" 权限或通过 /vip <player> 添加的玩家可跳过队列。操作员(op)默认也可跳过。
- 操作:当玩家被允许进入主世界时要运行的一系列命令。你可以分别以玩家或控制台身份运行不同的命令。
配置(config.yml)
键值说明
- author: 自由文本字符串。
- max-players: 整数。主世界允许的最大玩家数量。
- main-world: 目标世界的名称。
- wait-world: 队列大厅世界的名称。
- wait-time-per-player: 每个队列位置的秒数,用于计算预计等待时间 (ETA)。
- commands: 命令名称到设置的映射(描述、权限、VIP 权限、操作)。
示例(默认)
author: "Moin"
max-players: 10
main-world: "world"
wait-world: "wait"
wait-time-per-player: 10
commands:
lifesteal:
description: "Join lifesteal queue"
permission: "exooqueue.lifesteal"
vip-permission: "exooqueue.vip"
actions:
player:
- "say %player_name% joined lifesteal!"
console:
- "mvtp %player_name% world"
vip:
description: "Make player VIP bypass"
permission: "exooqueue.vip"
actions:
player: []
console: []
操作中的占位符
- %player_name% 始终会被替换为玩家名称。
- 如果安装了 PlaceholderAPI,所有 PAPI 占位符也会被处理。
命令(用户可见)
权限
- exooqueue.<command> → 运行该命令所需的权限(例如 exooqueue.lifesteal)
- exooqueue.vip → 跳过队列并使用 /vip
- 操作员默认也可跳过队列。
队列工作原理
- 玩家运行加入命令(例如 /lifesteal)。
- 如果是 VIP/op 或者主世界有容量,则立即运行配置的操作(例如传送),玩家加入。
- 如果已满且非 VIP,玩家将添加到内存队列中并被传送至等待世界。
- 后台任务每 5 秒检查一次:如果有空位,则处理下一个排队的玩家并运行其操作。
- 向玩家显示的预计等待时间 (ETA) 为位置 × wait-time-per-player。
添加自定义加入命令
注意:命令必须在 plugin.yml 中声明才能被 Bukkit 识别。然后在 config.yml 中配置其行为。
步骤
-
编辑 src/main/resources/plugin.yml 并添加命令块:
commands:
myworld:
description: Join myworld queue
permission: exooqueue.myworld
permission-message: You don't have permission to use this command.
-
编辑 src/main/resources/config.yml 并在 commands 下添加相应的配置:
commands:
myworld:
description: "Join myworld queue"
permission: "exooqueue.myworld"
vip-permission: "exooqueue.vip"
actions:
player:
- "say %player_name% is joining myworld!"
console:
- "mvtp %player_name% myworld"
-
重启服务器(或完全重载插件)以注册新命令并加载配置。
关于队列处理的重要说明
- 默认的队列处理在移动玩家时使用 "lifesteal" 命令的操作。
- 如果你依赖多个不同的加入命令/世界,你应该要么:
a) 对所有队列使用相同的操作(将所有人指向同一个目的地),或者
b) 更新代码以跟踪每个玩家使用的命令,并在处理队列时运行相应的操作。
如果需要选项 (b),请考虑增强代码以存储一个映射表:排队的玩家 UUID → 命令名称,并修改 processQueue() 以查找并运行该命令的操作。
世界与出生点设置
- 确保 config.yml(main-world、wait-world)中列出的世界已在你的服务器上存在。
- 使用游戏内命令(例如 /setworldspawn)或你的世界管理插件来设置等待世界的出生点。
- 如果在动作中使用了 Multiverse-Core 的命令(例如 mvtp),请安装该插件并确保控制台/玩家的权限配置正确。
SQLite 数据库
- 插件会创建 plugins/ExooQueue/queue.sqlite 文件以及一个名为 "queue" 的数据表(uuid TEXT PRIMARY KEY, position INTEGER)。
- 当前版本尚未在重启之间持久化队列内容。未来的更新可能会利用此功能实现持久化存储。
重载配置
- 此版本仅在服务器启动时读取配置文件。要应用更改:
- 停止并重新启动服务器,或者
- 谨慎使用完整服务器重载命令(/reload confirm)。建议采用重启方式。
故障排除
- 命令未找到:确保命令存在于 plugin.yml 中,并且在 config.yml 的 commands 下有对应的条目。
- 玩家未被传送:验证你的动作引用了正确世界,并确保安装了任何必需的插件(例如 Multiverse-Core)。
- 占位符未替换:安装 PlaceholderAPI 以使用高级占位符。%player_name% 始终有效。
- VIP 状态未保存:/vip 是临时的,重启后会被清除。如需永久 VIP,请通过你的权限插件授予 exooqueue.vip 权限。
- 构建问题:请使用 Java 21 并确保可以访问 Paper 仓库。提供的 Gradle 配置针对的是 Paper 1.21.x。
路线图构想(如果你扩展该插件)
- 在重启之间将队列和 VIP 列表持久化到 SQLite。
- 在处理排队玩家时,支持按命令区分的队列和动作。
- 添加 /queue status、/queue leave 和管理员控制功能。
- 添加配置重载命令。
- 支持按世界限制(main-world 列表包含独立容量)。
快速参考
- 主命令:/lifesteal
- VIP 命令:/vip <player>
- 配置文件路径:plugins/ExooQueue/config.yml
- 权限节点:exooqueue.<command>、exooqueue.vip
- 世界设置:main-world(目的地)、wait-world(队列大厅)
技术支持
- 如果你需要代码更新以支持按命令区分的队列或持久化功能,请提供你期望的行为描述,我们可以据此扩展该插件。
ExooQueue – Queue Management Plugin (Paper 1.21)
Overview
- ExooQueue limits players in a main world and queues overflow players in a waiting world.
- Players see their queue position and an ETA.
- VIPs (permission or /vip command) bypass the queue.
- Commands and actions are configurable. Actions can run as player or console and support %player_name% and PlaceholderAPI if installed.
- SQLite is initialized for future persistence (not actively used yet).
Requirements
- Multiverse core (for define waiting and other worlds)
- Server: Paper 1.21.x
- Java: 21 (JDK/JRE)
- Optional: PlaceholderAPI (for advanced placeholders in actions)
- Optional: A world management plugin if you use commands like "mvtp" in actions (e.g., Multiverse-Core)
Files
- src/main/resources/plugin.yml → Bukkit command/permission declarations
- src/main/resources/config.yml → Plugin configuration (worlds, queue, commands + actions)
- src/main/java/.../ExooQueuePlugin.java → Main plugin class
- build.gradle, settings.gradle → Gradle build files
Install (Using Built JAR)
- Copy build/libs/ExooQueue-1.0.0.jar to your Paper server "plugins" folder.
- Start the server once to generate config.yml.
- Stop the server and edit plugins/ExooQueue/config.yml as needed.
- Start the server again.
Build (If you need to rebuild)
- From project root: ./gradlew build (Linux/macOS) or .\gradlew.bat build (Windows)
- Output JAR: build/libs/ExooQueue-1.0.0.jar
Core Concepts
- Main world: The target world players want to join (e.g., "world").
- Wait world: A lobby where queued players wait.
- Max players: When the main world reaches this number, additional players are queued.
- VIP bypass: Players with permission "exooqueue.vip" or added via /vip <player> bypass the queue. Operators (op) bypass by default.
- Actions: A list of commands to run when a player is allowed into the main world. You can run separate commands as the player or the console.
Configuration (config.yml)
Keys
- author: Free-form string.
- max-players: Integer. Maximum player count allowed in the main world.
- main-world: World name for the destination world.
- wait-world: World name for the queue lobby.
- wait-time-per-player: Integer seconds per queue position to calculate ETA.
- commands: Map of command-name → settings (description, permission, vip-permission, actions).
Example (default)
author: "Moin"
max-players: 10
main-world: "world"
wait-world: "wait"
wait-time-per-player: 10
commands:
lifesteal:
description: "Join lifesteal queue"
permission: "exooqueue.lifesteal"
vip-permission: "exooqueue.vip"
actions:
player:
- "say %player_name% joined lifesteal!"
console:
- "mvtp %player_name% world"
vip:
description: "Make player VIP bypass"
permission: "exooqueue.vip"
actions:
player: []
console: []
Placeholders in actions
- %player_name% is always replaced with the player name.
- If PlaceholderAPI is installed, all PAPI placeholders are also processed.
Commands (User-visible)
-
/lifesteal
Description: Attempts to join the main world. If full, adds the player to the queue and teleports to the wait world.
Permission: exooqueue.lifesteal (default: true via plugin.yml)
-
/vip <player>
Description: Grants temporary VIP bypass to a player (persists until server restart; not saved to DB).
Permission: exooqueue.vip (default: op)
Permissions
- exooqueue.<command> → Required to run that command (e.g., exooqueue.lifesteal)
- exooqueue.vip → Bypass queue and use /vip
- Operators also bypass the queue by default.
How Queueing Works
- Player runs a join command (e.g., /lifesteal).
- If VIP/op or if main world has capacity, configured actions run immediately (e.g., teleport), and the player joins.
- If full and not VIP, the player is added to an in-memory queue and teleported to the wait world.
- A background task checks every 5 seconds: if slots are free, the next queued player is processed and their actions run.
- ETA shown to players is position × wait-time-per-player.
Adding a Custom Join Command
Note: Commands must be declared in plugin.yml to be recognized by Bukkit. Then configure the behavior in config.yml.
Steps
-
Edit src/main/resources/plugin.yml and add a command block:
commands:
myworld:
description: Join myworld queue
permission: exooqueue.myworld
permission-message: You don't have permission to use this command.
-
Edit src/main/resources/config.yml and add matching config under commands:
commands:
myworld:
description: "Join myworld queue"
permission: "exooqueue.myworld"
vip-permission: "exooqueue.vip"
actions:
player:
- "say %player_name% is joining myworld!"
console:
- "mvtp %player_name% myworld"
-
Restart the server (or fully reload the plugin) to register the new command and load config.
Important Note About Queue Processing
- The default queue processing uses the actions of the "lifesteal" command when moving players from the queue.
- If you rely on multiple different join commands/worlds, you should either:
a) Use the same actions for all queues (point everyone to the same destination), or
b) Update the code to track which command each player used and run the corresponding actions when processing the queue.
If you need option (b), consider enhancing the code to store a map of queued player UUID → command name, and modify processQueue() to look up and run that command's actions.
Changing Worlds and Spawns
- Ensure the worlds listed in config.yml (main-world, wait-world) exist on your server.
- Set the wait world spawn using in-game commands (e.g., /setworldspawn) or your world management plugin.
- If you use Multiverse-Core commands in actions (e.g., mvtp), install that plugin and ensure permissions for console/player are correct.
SQLite Database
- The plugin creates plugins/ExooQueue/queue.sqlite and a table "queue" (uuid TEXT PRIMARY KEY, position INTEGER).
- Current version does not persist the queue contents across restarts yet. Future updates may use this for persistence.
Reloading Configuration
- This version reads configuration on startup. To apply changes:
- Stop and start the server, or
- Use a full server reload with caution (/reload confirm). A restart is recommended.
Troubleshooting
- Command not found: Ensure the command exists in plugin.yml and has a matching entry under commands in config.yml.
- Player not teleported: Verify your actions reference the correct world and that any required plugins (e.g., Multiverse-Core) are installed.
- Placeholder not replaced: Install PlaceholderAPI to use advanced placeholders. %player_name% always works.
- VIP not saved: /vip is temporary and cleared on restart. Grant the exooqueue.vip permission via your permissions plugin for permanent VIP.
- Build issues: Use Java 21 and ensure the Paper repository is reachable. The provided Gradle config targets Paper 1.21.x.
Roadmap Ideas (if you extend the plugin)
- Persist queue and VIP list to SQLite across restarts.
- Per-command queues and actions when processing queued players.
- Add /queue status, /queue leave, and admin controls.
- Config reload command.
- Per-world limits (main-world list with individual capacities).
Quick Reference
- Main command: /lifesteal
- VIP command: /vip <player>
- Config path: plugins/ExooQueue/config.yml
- Permissions: exooqueue.<command>, exooqueue.vip
- Worlds: main-world (destination), wait-world (queue lobby)
Support
- If you need the code updated to support per-command queues or persistence, provide your desired behavior and we can extend the plugin accordingly.
评论 0
登录后参与评分
还没有评论,来抢沙发吧