Skip to content

Configuration

Jump to bottom Edit New page
AlexProgrammerDE edited this page Dec 29, 2025 · 2 revisions

Configuration

PistonQueue's configuration is highly customizable. This page covers all available options.

Proxy Configuration

The main configuration file is located in your proxy's plugins/PistonQueue/ folder.

Server Settings

# Display name for your server (used in messages)
serverName: "&cexample.org"

# Server names (must match your proxy config exactly)
queueServer: "queue"
targetServer: "main"

# Source server settings (for lobby/auth servers)
enableSourceServer: false
sourceServer: "lobby"

# Force players to the target server even if they try to connect elsewhere
forceTargetServer: false

# Load balancing strategy for multiple queue servers (see Queue Groups)
# Options: ROUND_ROBIN, LEAST_PLAYERS, RANDOM
queueLoadBalancing: "LEAST_PLAYERS"

Queue Behavior

# Always queue players, even when the target server isn't full
alwaysQueue: false

# Maximum players allowed on the queue network
queueServerSlots: 9000

# How often to move players from queue to target (milliseconds)
queueMoveDelay: 1000

# Maximum players to move per queue tick
maxPlayersPerMove: 10

Position Messages

# Where to display queue position
positionMessageChat: true
positionMessageHotBar: false
positionPlayerList: true

# Message format (supports color codes and placeholders)
queuePosition: "&6Position in queue: &l%position%"

# How often to send position updates (milliseconds)
positionMessageDelay: 10000

Available placeholders:

  • %position% - Player's position in queue
  • %wait% - Estimated wait time
  • %server_name% - Your server name

Server Down Handling

# Pause the queue if target server goes down
pauseQueueIfTargetDown: true
pauseQueueIfTargetDownMessage: "&6The main server is down. We will be back soon!"

# Kick new players if servers are down
kickWhenDown: false
serverDownKickMessage: "%server_name% &6is down please try again later :("

# Which servers to monitor for downtime
rawKickWhenDownServers:
  - "%TARGET_SERVER%"
  - "%QUEUE_SERVER%"

Recovery Settings

# Send players back to queue if kicked from target
ifTargetDownSendToQueue: true
ifTargetDownSendToQueueMessage: "&cThe target server is offline now! You have been sent to queue while it goes back online."

# Only recover if kick message contains these words (case-insensitive)
downWordList:
  - "restarting"
  - "closed"
  - "went down"
  - "unknown reason"

# Re-queue players if connection fails
recovery: true
recoveryMessage: "&cOops something went wrong... Putting you back in queue."

Kick Message Hiding

# Hide the real kick reason from players
enableKickMessage: false
kickMessage: "&6You have lost connection to the server"

Username Validation

# Validate usernames against a regex pattern
enableUsernameRegex: true
usernameRegex: "[a-zA-Z0-9_]*"
usernameRegexMessage: "&6[PQ] Invalid username please use: %regex%"

Audio Feedback

# Play XP sound when player reaches top 5 in queue
sendXpSound: true

Queue Types

Queue types define different priority levels. Players are assigned to a queue type based on permissions.

queueTypes:
  VETERAN:
    order: 1              # Lower = higher priority
    slots: 20             # Reserved slots on target server
    permission: "queue.veteran"
    header:
      - ""
      - " %server_name% "
      - " Position: &l%position% "
      - ""
    footer:
      - ""
      - " &6Veteran queue status "
      - ""

  PRIORITY:
    order: 2
    slots: 30
    permission: "queue.priority"
    header:
      - ""
      - " %server_name% "
      - " Position: &l%position% "
      - ""
    footer:
      - ""
      - " &6Priority queue status "
      - ""

  REGULAR:
    order: 3
    slots: 50
    permission: "default"   # "default" = no permission required
    header:
      - ""
      - " %server_name% "
      - " Position: &l%position% "
      - ""
    footer:
      - ""
      - " &6Donate for priority: donate.example.com "
      - ""

How Queue Types Work

  1. Order: Lower numbers get processed first. Veterans (order 1) will always enter before Priority (order 2) players.

  2. Slots: Reserved slots ensure each queue type has guaranteed space on the target server. If VETERAN has 20 slots, at least 20 spots are reserved for veterans.

  3. Permission: Players are assigned to the highest priority queue type they have permission for.

  4. Header/Footer: Shown in the tab list while in queue. Supports placeholders and color codes.

Queue Groups

Queue groups allow routing different queue types to different servers. This is advanced functionality for networks with multiple target servers.

queueGroups:
  default:
    queueServers:             # List of queue servers (for load balancing)
      - "queue1"
      - "queue2"
    targetServers:
      - "main"
    sourceServers:
      - "lobby"
    queueTypes:               # Which queue types belong to this group
      - "REGULAR"
      - "PRIORITY"
      - "VETERAN"
    defaultGroup: true        # Is this the default group?

Multiple Queue Servers

PistonQueue supports multiple queue servers per queue group for load balancing. This is useful for large networks where a single queue server might become overloaded.

Configuration:

# Global load balancing strategy
queueLoadBalancing: "LEAST_PLAYERS"

queueGroups:
  default:
    queueServers:
      - "queue1"
      - "queue2"
      - "queue3"
    # ... other settings

Load Balancing Strategies:

Strategy Description
LEAST_PLAYERS Sends players to the queue server with the fewest players (default)
ROUND_ROBIN Distributes players evenly across all queue servers in order
RANDOM Randomly selects a queue server

Notes:

  • All queue servers in a group share the same queue position (players don't move between queue servers)
  • XP sounds are sent to all queue servers that have players
  • If a queue server goes offline, players are automatically distributed to remaining servers
  • The queueServer setting (singular) is still supported for backwards compatibility and will be converted to a single-item list

Shadow Bans

Shadow bans allow you to punish players without them knowing they're banned.

# Shadow ban behavior
shadowBanType: LOOP    # LOOP, PERCENT, or KICK

# For PERCENT type: chance of getting through (1-100)
shadowBanPercent: 10

# Message shown to shadow-banned players (if KICK type)
shadowBanMessage: "&6You have lost connection to the server"

Shadow Ban Types

Type Behavior
LOOP Player stays in queue forever, never connecting
PERCENT Player has X% chance of actually connecting each queue move
KICK Player is kicked when they reach the front of the queue

Permissions Configuration

# Permission to bypass the queue entirely
queueBypassPermission: "queue.bypass"

# Permission for admin commands
adminPermission: "queue.admin"

Bukkit Configuration (Queue Server)

Located in plugins/PistonQueue/config.yml on your queue server.

Location Lock

location:
  enabled: true
  world: "world_the_end"
  coordinates:
    x: 500
    y: 256
    z: 500

Player Visibility

visibility:
  hidePlayers: true           # Hide players from each other
  restrictMovement: true      # Prevent all movement
  forceGamemode:
    enabled: true
    mode: "spectator"
  team:
    enabled: false            # Show player's own name in spectator menu
    name: "%player_name%"

Communication

communication:
  disableChat: true
  disableCommands: true

Audio

audio:
  playXpSound: true    # Play sound on proxy plugin message

Protections

protections:
  preventExperience: true
  preventDamage: true
  preventHunger: true

ProtocolLib Features

These require ProtocolLib to be installed:

protocolLib:
  disableDebug: true          # Hide position from F3 screen
  suppressPackets:
    chunk: true               # Don't send chunk data
    time: true                # Don't send time updates
    health: true              # Don't send health data
    advancement: true         # Don't send advancements
    experience: true          # Don't send experience
  showFullHead: true          # Show full player head in spectator

Placeholders

Tab List Placeholders (Proxy)

Used in queue type header/footer:

Placeholder Description
%server_name% Your server name
%position% Player's queue position
%wait% Estimated wait time

PlaceholderAPI (Bukkit)

Requires PlaceholderAPI and the PistonQueue placeholder plugin on your target server:

Placeholder Description
%pistonqueue_online_queue_<TYPE>% Players in queue for type
%pistonqueue_online_target_<TYPE>% Players of type on target

Replace <TYPE> with your queue type name (e.g., REGULAR, PRIORITY).

PistonMOTD Placeholders

If using PistonMOTD:

Placeholder Description
%pistonqueue_<type>% Queue size for type (lowercase)

Example Configurations

Simple Anarchy Server

serverName: "&c2b2t Clone"
queueServer: "queue"
targetServer: "main"
alwaysQueue: true
enableSourceServer: false

queueTypes:
  PRIORITY:
    order: 1
    slots: 100
    permission: "queue.priority"
  REGULAR:
    order: 2
    slots: 400
    permission: "default"

Lobby-Based Network

serverName: "&bMy Network"
queueServer: "queue"
targetServer: "survival"
enableSourceServer: true
sourceServer: "lobby"
alwaysQueue: false

queueTypes:
  VIP:
    order: 1
    slots: 50
    permission: "queue.vip"
  REGULAR:
    order: 2
    slots: 150
    permission: "default"

High-Capacity Network with Multiple Queue Servers

serverName: "&62b2t Clone"
targetServer: "main"
alwaysQueue: true
queueLoadBalancing: "LEAST_PLAYERS"

queueGroups:
  default:
    queueServers:
      - "queue1"
      - "queue2"
      - "queue3"
    targetServers:
      - "main"
    queueTypes:
      - "PRIORITY"
      - "REGULAR"
    defaultGroup: true

queueTypes:
  PRIORITY:
    order: 1
    slots: 200
    permission: "queue.priority"
  REGULAR:
    order: 2
    slots: 800
    permission: "default"

Discord | GitHub | Modrinth

PistonQueue

Getting Started

Help

Links

Clone this wiki locally