ExooQueue

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)

1. Copy build/libs/ExooQueue-1.0.0.jar to your Paper server "plugins" folder.
2. Start the server once to generate config.yml.
3. Stop the server and edit plugins/ExooQueue/config.yml as needed.
4. 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 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
  Description: Grants temporary VIP bypass to a player (persists until server restart; not saved to DB).
  Permission: exooqueue.vip (default: op)

Permissions

• exooqueue. → 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

1. Player runs a join command (e.g., /lifesteal).
2. If VIP/op or if main world has capacity, configured actions run immediately (e.g., teleport), and the player joins.
3. If full and not VIP, the player is added to an in-memory queue and teleported to the wait world.
4. A background task checks every 5 seconds: if slots are free, the next queued player is processed and their actions run.
5. 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

1. 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.

2. 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"

3. 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
• Config path: plugins/ExooQueue/config.yml
• Permissions: exooqueue., 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.