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