Network Features

Network Features

All settings are in paperproxy.toml. /pp reload applies most changes without a restart.

Server groups

[groups]
lobby = ["lobby-1", "lobby-2"]

Players are sent to the member with the fewest players. Full or offline members are skipped. You can use the group name wherever a server is expected: /hub, /send, the queue.

Queues

[queue]
enabled = true
interval-seconds = 2
timeout-minutes = 10
rejoin-after-restart = true

Full or offline servers get a queue. Players see their position in the action bar. paperproxy.queue.priority.<0-100> moves players forward, paperproxy.queue.bypass joins full servers directly. With rejoin-after-restart, players who were moved away by a server restart are sent back once it is online.

/hub

[hub-command]
target = "lobby"
aliases = ["hub", "lobby"]

Limbo

When a server restarts or crashes and no other server can take its players, they stay connected in the last world they saw, with a countdown, and are sent back as soon as the server (or another member of its group) is online.

[limbo]
enabled = true
max-wait-seconds = 300
kick-messages = ["server closed", "restarting", "server is restarting", "server stopped"]

A lost connection always counts as a restart. A kick only counts when its message contains one of kick-messages, so bans and AFK kicks are passed on as before.

Parties

/party invite|accept|leave|kick|disband|list|chat and /pc <message>. Members follow their leader from server to server.

[party]
enabled = true
max-size = 8
follow-leader = true

Parties live on one proxy and end when the proxy restarts. Plugins can use them through the Developer API.

Planned restarts

[restart]
times = ["04:00"]
warn-seconds = [600, 300, 60, 30, 10, 5, 4, 3, 2, 1]

/pp restart <seconds> [reason] plans one by hand, /pp restart cancel stops it. Players get chat warnings and a title for the last seconds. Your start script or panel has to start the proxy again.

Restart without kicks

[shutdown]
transfer-to = "play.example.net:25565"

When the proxy stops, 1.20.5+ clients are handed to this address instead of being disconnected.

/send

/send <player|all|current> <server|group> and /send server <from> <server|group>.

Maintenance and health checks

/pp maintenance on|off [server] for the whole network or one server, with a whitelist. Health checks skip offline servers and tell staff with paperproxy.notify.health.

Other

• Hidden commands: [tab-complete] hidden-commands = ["server", "plugins"] removes them from tab completion. paperproxy.tabcomplete.bypass still sees them.
• Query passthrough: [query] passthrough-server = "lobby-1" answers server queries with the map, version and plugins of that backend.
• Ping cache: [ping-cache] seconds = 5 against server list floods.
• ViaVersion: /pp via install downloads ViaVersion from Modrinth, [versions] allows client versions per server.