⏰️ Powerful queue plugin for anarchy/survival servers.
PistonQueue is a powerful, but easy to use queue plugin designed for anarchy and survival servers. It is a recreation of the 2b2t.org queue system design, but adds a lot of features on top.
- BungeeCord and Velocity support.
- Queue system with reserved slots.
- Shadow-banning players.
- Built-in support for forcing people into the end void.
- Auth server support for cracked (offline mode: false) servers.
- Joining the auth server first before the queue server.
- Optional multi-endpoint lobby groups with transfer (packet-based external redirect) to load-balance across multiple proxies/nodes.
- Configurable queue position display (chat, action bar, title/subtitle).
- Minimum queue time enforcement to prevent instant joins.
- XP sound notification when approaching front of queue.
- Recovery system to handle connection failures gracefully.
Check out the wiki for a tutorial on how to set up PistonQueue.
If you run multiple Velocity nodes on different public IPs and want basic load balancing and DDoS resilience, you can enable the optional lobby group feature. It lets you define multiple endpoints for a lobby, mixing regular Velocity servers and external nodes, and route players by priority → weight, then break ties by the server with fewer players.
Highlights:
- Modes: VELOCITY (connect via proxy server name) and TRANSFER (client is instructed to connect to host:port directly; requires modern clients, e.g. 1.20.5+).
- Selection: priority (lower is better), weight (weighted pick within same priority), tie-breaker by least players.
- Safety: TRANSFER_MIN_PROTOCOL guard to fall back to proxy connect for older clients.
- Health checks: Automatic SLP (Server List Ping) status checks for TRANSFER endpoints.
- Cooldown: 10-second transfer cooldown to prevent recovery re-queuing loops.
Configuration is documented inline in proxy_config.yml under the section "Advanced: Multi-endpoint lobby groups".
Players can see their queue position through multiple methods (all configurable):
- Chat messages: Traditional text messages with position updates (configurable interval)
- Action bar: Compact display above the hotbar
- Title/Subtitle: Large on-screen display with independent update interval
- Tab list: Player list header/footer with position and estimated wait time
Each display method has its own update frequency:
POSITION_MESSAGE_DELAY: Controls chat and action bar updates (default: 10 seconds)POSITION_TITLE_DELAY: Controls title/subtitle updates (default: 1 second for smoother display)
Animation timing is fully customizable (fadeIn/fadeOut can be disabled for instant display).
Prevent players from instantly joining the main server by enforcing a minimum wait time:
- Configurable minimum seconds before allowing server transfer
- XP sound only plays when queue actually progresses (not during enforced wait)
- Individual entry sound for players joining the queue
Handles connection failures gracefully:
- Automatic re-queuing if player connection to main server fails
- Position cache to distinguish normal joins from recovery scenarios
- Prevents false "recovery" messages on normal server joins
- Cooldown system to prevent re-queue loops after transfers
Queue pause when all nodes are offline:
- Automatically pauses queue movement when no endpoints are available
- Displays configurable pause message to players (throttled to avoid spam)
- Resumes automatically when nodes come back online
- Works with both traditional TARGET_SERVER and lobby group configurations
Feel free to join our Discord community server:
This project is in active development, so if you have any feature requests or issues please submit them here on GitHub. PRs are welcome, too. 