Installation

Installation

PistonQueue requires setup on both your proxy server (BungeeCord/Velocity) and your queue server (Spigot/Paper).

Architecture Overview

Players
   |
   v
[Proxy Server] <-- PistonQueue (main plugin)
   |
   +---> [Queue Server] <-- PistonQueue (bukkit plugin)
   |
   +---> [Main Server] (your actual game server)
   |
   +---> [Source Server] (optional: lobby/auth server)

---

Step 1: Proxy Setup

Download

Download the latest PistonQueue JAR from:

• Modrinth
• GitHub Releases

Place the JAR in your proxy's plugins folder.

BungeeCord Configuration

Edit your BungeeCord config.yml:

Premium (Online Mode) Server

listeners:
- query_port: 25577
  priorities:
  - queue  # Players connect to queue first
  host: 0.0.0.0:25565
  max_players: 9999
  force_default_server: true

player_limit: -1
online_mode: true

servers:
  main:
    motd: '&1Main Server'
    address: 127.0.0.1:25566
    restricted: false
  queue:
    motd: '&1Queue Server'
    address: 127.0.0.1:25567
    restricted: false

Cracked (Offline Mode) Server with Auth

listeners:
- query_port: 25577
  priorities:
  - auth  # Players authenticate first
  host: 0.0.0.0:25565
  max_players: 9999
  force_default_server: true

player_limit: -1
online_mode: false

servers:
  auth:
    motd: '&1Auth Server'
    address: 127.0.0.1:25568
    restricted: false
  main:
    motd: '&1Main Server'
    address: 127.0.0.1:25566
    restricted: false
  queue:
    motd: '&1Queue Server'
    address: 127.0.0.1:25567
    restricted: false

Velocity Configuration

Edit your Velocity velocity.toml:

Premium (Online Mode) Server

[servers]
main = "127.0.0.1:25566"
queue = "127.0.0.1:25567"

try = ["queue"]

[forced-hosts]
# Optional: direct connections
"play.example.com" = ["queue"]

Cracked (Offline Mode) Server with Auth

[servers]
auth = "127.0.0.1:25568"
main = "127.0.0.1:25566"
queue = "127.0.0.1:25567"

try = ["auth"]

[forced-hosts]
"play.example.com" = ["auth"]

---

Step 2: Queue Server Setup

The queue server is a lightweight Spigot/Paper server where players wait before joining the main server.

Download

Use the same PistonQueue JAR - it contains both proxy and bukkit plugins.

Place the JAR in your queue server's plugins folder.

Recommended Setup

1. World: Use a simple world (The End works well) to minimize resource usage
2. RAM: 1-2 GB is sufficient for most servers
3. Plugins:
   • LuckPerms - For permission management
   • ProtocolLib - Enables advanced packet suppression features

Default Bukkit Configuration

The plugin creates a config.yml with sensible defaults:

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

visibility:
  hidePlayers: true
  restrictMovement: true
  forceGamemode:
    enabled: true
    mode: "spectator"

communication:
  disableChat: true
  disableCommands: true

audio:
  playXpSound: true

protections:
  preventExperience: true
  preventDamage: true
  preventHunger: true

# Requires ProtocolLib
protocolLib:
  disableDebug: true
  suppressPackets:
    chunk: true
    time: true
    health: true
    advancement: true
    experience: true
  showFullHead: true

Warning: Making a "playable" queue server is not recommended. It causes performance issues and we do not provide support for such setups.

---

Step 3: Configure PistonQueue

After starting your proxy with PistonQueue installed, a configuration file will be generated.

Key Settings

Edit the generated config file on your proxy:

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

# For cracked/lobby servers
enableSourceServer: false  # Set to true if using auth/lobby
sourceServer: "lobby"

# Queue behavior
alwaysQueue: false  # true = always queue, false = only when full

See the Configuration page for all options.

---

Step 4: Verify Installation

1. Start your proxy server
2. Start your queue server
3. Start your main server
4. Connect to your proxy

You should be placed in the queue server. Use /pq stats to verify the queue is working.

---

Optional: PlaceholderAPI Support

To display queue information on your main/target server:

1. Install PlaceholderAPI on your target server
2. Place the PistonQueue JAR in your target server's plugins folder
3. The plugin will register placeholders automatically

Available placeholders:

• %pistonqueue_online_queue_REGULAR% - Players in regular queue
• %pistonqueue_online_queue_PRIORITY% - Players in priority queue
• %pistonqueue_online_target_REGULAR% - Regular players on target server
• %pistonqueue_online_target_PRIORITY% - Priority players on target server

---

Next Steps

• Configuration - Customize all plugin options
• Commands & Permissions - Learn available commands
• FAQ - Common questions and troubleshooting