Joinqueue

Minecraft 版本： 1.21.8 1.21.9 1.21.10 1.21.11

平台： neoforge

标签： management optimization utility

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.