queue

A simple queue mod for Minecraft Java Edition. Lightweight, works on essentially any server types, (Spigot/Bukkit/Fabric/Paper), Tiered Priority Queue, and simple at its core.

Table of Contents

• Features
• Commands
• Requirements
• Configuration

Features

Core Queue System

• Automatic Queue Management - Players are automatically sent to a queue server when the main server is full
• Point-Based Queue System - Players accumulate points over time; the player with the most points gets the next available slot
• Tiered Priority Queue System - Support for multiple VIP/donor tiers with configurable point accumulation rates
• Configurable Point Tiers - Define custom permission nodes with different point accumulation rates (e.g., VIP tiers get points faster)
• Fair Tiebreaker - If two players have the same points, the one with the better tier (lower seconds-per-point) goes first
• Queue Persistence - Players reconnecting to the queue server are automatically re-added to their queue position
• Real-Time Position Updates - Action bar displays current queue position and points

Admin Access System

• Admin Bypass (queue.admin) - can join even when server is over max capacity
• Force Pull Players - Admins can force pull any player from the queue directly to the main server, bypassing max capacity

Server Management

• Automatic Pause on Server Down - Queue processing pauses when main server goes offline
• Server Status Monitoring - Checks main server status every 5 seconds
• Manual Queue Control - Admins can pause/resume queue processing at any time
• Player Notifications - All queue players are notified when server status changes or queue is paused/resumed

Additional Features

• Require Resource Pack - Option to hold players in queue until they successfully load/apply a resource pack packet
• Hot Reload & Dynamic Toggling - Use /queue reload or /queue requirepack [on|off] to toggle resource pack requirements dynamically

Commands

Player Commands

• /queue info - View your current queue position, points, point accumulation rate, and resource pack status
• /queue status - View overall queue system status (players in queue, paused state, resource pack requirement, server online status, player count)
• /queue credits - View plugin credits with clickable GitHub link

Admin Commands (Require queue.admin permission)

• /queue pull <player> - Force pull a specific player from queue to main server (bypasses max capacity)
• /queue pause [server] - Pause the queue globally or for a specific server
• /queue resume [server] - Resume the queue globally or for a specific server
• /queue requirepack [on|off] - Toggle requirement for players to successfully load a resource pack before leaving queue
• /queue joindelay [seconds] - View or change the time between player joins from the queue
• /queue list - List all players in queue with their position, points, and priority tier
• /queue reload - Reload all configuration files without restarting

Requirements

What You Need:

• A Velocity Proxy Server
  • Permission System (Optional but required for tiered queue and admin account bypasses LuckPerms Velocity Recommended).
  • The Queue plugin installed on the velocity server.
• Your Main Server:
  • This can be any type of Minecraft Server, as long as it connects to the velocity proxy it will work.
  • Fabric Proxy Lite is recommended for fabric servers.
• The Queue Server
  • This can be any type of Minecraft Server, as long as it connects to the velocity proxy it will work.
  • If you don't want to deploy yet another heavy load Minecraft Server it is recommended to use PicoLimbo or NanoLimbo.

Redis-backed queue storage

Redis mode keeps queue position and transfer claims in Redis so queue ownership can survive proxy reconnects and short restarts. Configure it with environment variables:

QUEUE_REDIS_MODE=redis
QUEUE_REDIS_URL=redis://username:password@redis-host:6379/0
QUEUE_PROXY_ID=velocity-main
QUEUE_REDIS_NAMESPACE=summit26

• QUEUE_REDIS_MODE: redis enables Redis storage; omit it or set local for in-memory mode.
• QUEUE_REDIS_URL: Redis connection URI. Use rediss:// when the connection is not already protected by a trusted private tunnel.
• QUEUE_PROXY_ID: Stable, unique ID for each Velocity proxy that can own queued players.
• QUEUE_REDIS_NAMESPACE: Optional key namespace. Proxies sharing a queue must use the same value.

Redis is required while Redis mode is enabled. If it becomes unavailable, queue admissions pause instead of falling back to unsafe local state. Queue reconnect grace is currently three minutes. Protect the Redis endpoint with an ACL/password, restrict it to the private interface or tunnel, enable persistence appropriate to your recovery requirements, and use a non-evicting memory policy for queue data.

When multiple Velocity proxies share a namespace, the configured main servers' ping responses are the source of truth for player counts. Before a Redis-mode transfer, the plugin queries the target shard and Redis atomically combines that observed count with pending reservations, preventing two proxies from claiming the same remaining slot. /queue status also queries every shard directly while reading the global queue size from Redis. The queue does not duplicate backend membership state in Redis. Use the same server list, capacity, join delay, and players-per-join configuration on every proxy, but give every proxy a distinct QUEUE_PROXY_ID. Each main server must expose its online player count in its server-list ping response.

Configuration

The plugin uses two YAML configuration files, all located in the plugins/queue/ directory. These files are automatically generated with default values on first run.

server-config.yml

Defines the main server, queue server, player capacity, and join timing settings.

# List of main servers to balance between
main-servers:
  - main1
  - main2

# The name of the queue/lobby server in your Velocity configuration
queue-server: queue

# Maximum players allowed on each main server (admins can bypass this)
main-server-max-players: 100

# Require players to successfully apply a resource pack before leaving the queue
require-resource-pack: false

# Time in seconds between player joins from the queue
join-delay-seconds: 5

# Maximum number of players transferred from queue per join interval
players-per-join: 1

Configuration Options:

• main-servers: List of main server names as defined in Velocity's velocity.toml (balanced using round robin)
• main-server: (Legacy / Fallback) The name of your main server if main-servers is not defined
• queue-server: The name of your queue/lobby server as defined in Velocity's velocity.toml
• main-server-max-players: Maximum player capacity per target main server before queue activates (admins with queue.admin can bypass this limit)
• require-resource-pack: When set to true, holds players in the queue until Velocity receives a successful resource pack status packet from the client
• join-delay-seconds: Time in seconds between player transfers/joins from the queue to the main server (default: 5)
• players-per-join: Maximum number of players moved from queue per join interval (default: 1)

queue-points.yml

Configures the point-based queue system with priority tiers.

tiers:
  queue.vip.diamond: 10  # 1 point every 10 seconds
  queue.vip.gold: 20     # 1 point every 20 seconds
  queue.vip.silver: 30   # 1 point every 30 seconds
  queue.vip: 45          # 1 point every 45 seconds

default-seconds: 60      # Default for players without permissions

How It Works:

• Players earn points while waiting in queue
• Lower seconds = faster points = higher priority
• Player with most points gets the next slot
• First matching permission in the list is used

Example: A VIP Diamond player earns 6 points per minute, while a default player earns 1 point per minute.

bonus-points.json

Allows assigning accumulating bonus points to lists of player UUIDs over time. Located in plugins/queue/bonus-points.json.

[
  {
    "points": 5,
    "seconds": 30,
    "uuids": [
      "00000000-0000-0000-0000-000000000000",
      "11111111-1111-1111-1111-111111111111"
    ]
  }
]

How It Works:

• Every seconds interval (e.g. 30s), players listed in uuids accumulate points bonus points (e.g. +5 pts).
• Bonus points accumulate alongside normal permission tier points over time while in queue.
• Reload configurations at any time using /queue reload.

Permission Nodes

Player Permissions:

• Custom tier permissions defined in queue-points.yml (e.g., queue.vip.diamond, queue.vip.gold, etc.)

Bypass Permissions:

• queue.bypass - Bypasses queue:
  • Bypass queue entirely
  • If server is down, placed at front of queue with maximum priority
• Role names such as "creator" are not hard-coded. Grant those roles queue.bypass through your permissions system.

Admin Permissions:

• queue.admin - Full admin access:
  • Bypass the queue and join even when server is over max capacity
  • Access to all admin commands
  • If server is down, placed at front of queue with maximum priority

Reloading Configuration

Use /queue reload in-game or console to reload all configuration files without restarting the proxy.

Changes will take effect immediately for:

• Server names and max players
• Point tier configuration

Note: Players already in the queue will keep their current point accumulation rate until they reconnect.