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 <add|remove> Adds or removes a player from the Staff (bypass) list. /joinqueue vip <add|remove> Adds or removes a player from the VIP (fast-queue) list. /joinqueue list <staff|vip> 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.