BlockyQueue — Leaf Studios Wiki

Overview

BlockyQueue runs on Velocity and communicates with backend Paper servers through a bridge plugin. When a player tries to connect to a full or offline server they are placed in a position-sorted queue. The proxy polls server status on a configurable interval and sends players one at a time as capacity frees up.

Architecture

Velocity plugin — manages all queue state, sends players, handles commands and actionbar updates.
Paper bridge plugin — installed on each backend server. Forwards GUI interactions and allows backend plugins to push actionbar content through BlockyQueue's channel.

Optional Dependencies

LuckPerms — required for priority-based queue ordering via blockyqueue.priority.<number> permissions

✓

Multiple queues are supported simultaneously. Players can be in different queues for different servers at the same time.

Installation

Download BlockyQueue from BuiltByBit. The release includes both the Velocity JAR and the Paper bridge JAR.
Place the Velocity JAR in your plugins/ folder on the proxy
Place the Paper bridge JAR in plugins/ on every backend server you want queue support for
Start the proxy and backends — config files generate automatically
Edit plugins/BlockyQueue/config.yml on the proxy
Run /queue reload to apply

i

The bridge plugin on backend servers uses the plugin messaging channel to communicate with the Velocity plugin. No additional configuration is needed on the backend side for basic functionality.

Configuration

Core Settings

config.yml

default-queue-server:    "Lobby-1"     # used when /queue is run with no argument
wait-time:               5.0           # seconds between send attempts
message-time:            10            # seconds between position update messages
send-actionbar:          true          # show queue position in actionbar
actionbar-time:          1.0           # refresh rate for actionbar (keep 0.5-1.0)
send-title:              false         # title when player reaches position 1
remove-on-server-switch: true          # kick from queue if player switches servers
remove-on-disconnect:    true
max-tries:               10            # failed send attempts before queue removal
offline-time:            120           # seconds before server is marked offline vs restarting
allow-multiple-queues:   true
queue-command-cooldown:  3             # seconds between /queue uses
require-queue-permission: false        # require blockyqueue.queue.<server>
auto-queue-on-restart:   false         # re-queue players when their server restarts
lobby-server:            "Lobby-1"

Server Display Names

config.yml

servers:
  survival:
    display-name: "Survival"
  lobby-1:
    display-name: "Lobby 1"

Disabling Commands per Server

Prevents BlockyQueue from handling a command on a specific backend server — useful when another plugin on that server uses the same command name.

config.yml

disabled-commands-per-server:
  survival:
    - queue
    - q

Messages

All messages support MiniMessage tags, legacy & colour codes and hex colours. Placeholders are listed below each message group.

Queue Status Messages

messages.yml

now-in-queue: "<gold>You are now queued for <yellow>{SERVER}<gold>! Position <yellow>{POS}<gold> of <yellow>{LEN}<gold>."
status-online:      "<gold>Position <yellow>{POS}<gold> of <yellow>{LEN}<gold>. ETA: <yellow>{TIME}"
status-offline:     "<red>{SERVER} is offline. Position {POS} of {LEN}."
status-restarting:  "<red>{SERVER} is restarting. Position {POS} of {LEN}."
status-full:        "<red>{SERVER} is full. Position {POS} of {LEN}. ETA: {TIME}"
sending-now:        "<gold>Sending you to <yellow>{SERVER}<gold> now..."
left-queue:         "<green>You left the queue for {SERVER}."

Actionbar Messages

messages.yml

actionbar-online:      "&7Queued for &f{SERVER}&7. Position &f{POS}&7 of &f{LEN}&7. ETA: {TIME}"
actionbar-restarting:  "&7Queued for &f{SERVER}&7 &e(restarting)&7. Position &f{POS}&7 of &f{LEN}"
actionbar-paused:      "&7Queued for &f{SERVER}&7 &e(paused)&7. Position &f{POS}&7 of &f{LEN}"

Message Placeholders

placeholders

{SERVER}    Server display name
{POS}       Player's current position in queue
{LEN}       Total players in queue
{TIME}      Estimated time remaining (e.g. 1m 30s)
{STATUS}    Server status string
{PLAYER}    Player name
{EXPRESS}   Express or non-express string (configured separately)
{PRIORITY}  Player's priority level

Priority System

Queue priority is controlled entirely through LuckPerms permissions. Assign blockyqueue.priority.<number> to a player or group — higher numbers mean higher priority and earlier placement in the queue. The default priority for players without a priority permission is 0.

example

blockyqueue.priority.100   VIP players — near the front
blockyqueue.priority.50    Premium tier
blockyqueue.priority.10    Default registered players
blockyqueue.priority.0     Guest / unregistered (implicit default)

Players with the same priority level are ordered by join time within that tier.

i

If LuckPerms is not installed, all players default to priority 0 and are queued in first-come-first-served order.

Server Selector GUI

An optional chest GUI lets players browse and connect to servers. Configured in plugins/BlockyQueue/gui.yml on the backend bridge server. Supports PAPI placeholders, custom player heads, paged layouts and multiple actions per item.

gui.yml

gui:
  enabled: true
  title:   "<gold>Server Selector"
  size:    9

  items:
    "1":
      material:    "GRASS_BLOCK"
      displayname: "&aSurvival"
      lore:        ["<gray>Click to connect!"]
      actions:
        - "[sound] ENTITY_PLAYER_LEVELUP 1 1"
        - "[connect] Survival"
        - "[message] <green>Connecting to Survival..."

Supported Actions

Action	Description
[exit]	Close the GUI.
[back]	Open the previous page.
[next]	Open the next page.
[connect] <server>	Ask the proxy to connect the player to a server.
[message] <text>	Send a formatted message to the player.
[sound] <SOUND> <vol> <pitch>	Play a sound for the player.

Commands

/queue <server>blockyqueue.command.queue

Join the queue for a server. Aliases: /q, /joinqueue, /joinq. Omit the server argument to use the default-queue-server.

/leavequeue [server|all]blockyqueue.command.leavequeue

Leave a specific queue or all queues. Aliases: /queueleave, /qleave, /leave.

/send <player> <server>blockyqueue.admin.send

Send a player to a server via the proxy. Also supports /send <from-server> <to-server> to move all players from one server to another.

Permissions

Node	Default	Description
blockyqueue.use	true	Base permission for BlockyQueue.
blockyqueue.admin	op	All admin commands.
blockyqueue.admin.reload	op	Reload the plugin.
blockyqueue.admin.send	op	Use the /send command.
blockyqueue.command.queue	true	Use /queue.
blockyqueue.command.leavequeue	true	Use /leavequeue.
blockyqueue.express	false	Grant express queue status (shown in messages as the express string).
blockyqueue.priority.<n>	false	Set queue priority. Higher numbers are placed earlier. Requires LuckPerms.
blockyqueue.queue.<server>	true	Permission to queue for a specific server. Only checked when require-queue-permission is true.