Joinqueue

JoinQueue

Versions: NeoForge 1.21.1 & 1.21.8

Prevents server crashes and TPS drops caused by many players joining at the same time (e.g., after a restart or during events). The mod puts connecting players into a waiting line during the Configuration Phase, preventing the Main Thread from overloading.

Features
Activation: With default settings the queue is always active (queue_activation_threshold = 0). Set a threshold to only activate above a given online player count. It also force-activates during the grace period after a server restart (default 60s) or whenever TPS drops below 8.0.
TPS Check: Players are only released while the server is stable (TPS ≥ 8.0) and the queue is not paused. Releasing stops automatically during heavy lag.
Release Rate: Players are let in on a timer — by default every 2s (normal) and every 1s (VIP), configurable via ticks_between_joins / ticks_between_joins_vip.
Manual Control: Admins can use /joinqueue pause and /joinqueue resume to stop or start the login process manually, or /joinqueue toggle to enable/disable the whole mod.
Priority & Bypass:
Staff members bypass the queue entirely.
VIP players are moved to the front of the queue and released on a faster timer.
Server-Full Handling: When the server reaches its vanilla player cap, normal players are held in the queue (with a “Server is full” message) until a slot opens, instead of being rejected at the network layer. Staff bypass the limit and VIPs may join over it.
Async Chunk Loading: Loads spawn chunks on background threads (radius configurable, default 3) before a player joins to prevent main-thread freezes. A hold_back_ms safety ceiling (default 1500ms) guarantees release even if chunks are slow.
Queue Screen: Shows players their live position in line, the total queue size, and a custom (configurable) message, including a separate message when the queue is paused.
Minimum Wait & Size Cap: Optional min_queue_seconds forces every player to wait a minimum time, and max_queue_size can cap how many players the queue holds.
Commands

All commands require permission level 2 (OP). Changes are saved automatically and take effect immediately.

Command Description
/joinqueue status Shows master switch, release state, server-ready state, TPS, queue size, threshold and staff/VIP counts.
/joinqueue toggle Enables or disables the entire mod (master switch).
/joinqueue pause Pauses the queue (players accumulate but are not released).
/joinqueue resume Resumes releasing players.
/joinqueue reload Reloads the configuration from config/joinqueue.json.
/joinqueue staff Adds or removes a player from the Staff (bypass) list.
/joinqueue vip Adds or removes a player from the VIP (fast-queue) list.
/joinqueue list Lists all members of the Staff or VIP list.
Technical Details
Runs entirely in the Configuration Phase, before the player fully joins the world.
Uses ConcurrentLinkedDeque and AtomicInteger for thread-safe performance.
TPS is measured via a rolling 40-tick ring buffer using nanoTime.
Extends the server keep-alive timeout (15s → 2min) via a Mixin so queued players are never kicked while waiting.
Released players that never complete the join handshake are dropped after 15s so the line never stalls.
Compatible with Arclight/hybrid servers (chunk preloading is safely skipped there).
Required on both server and client.