CleanJoin

CleanJoin is a performance mod for busy NeoForge servers, built around the moment a login wave hits: chunk loading, entity tracking and packet serialization all landing on the main thread in the same tick, dragging TPS down and tripping the watchdog.

It does its work server-side. Installing it on clients as well is optional and adds a smoother arrival on the player's end — clients without it connect and play normally.

On the server

Chunk preloading. When a player joins, the chunks around their arrival point are pulled in asynchronously instead of on demand, so the first seconds of movement and any follow-up teleport land on chunks that are already there. On Bukkit hybrids CleanJoin also reads EssentialsSpawn and Multiverse-Core configs to work out where a plugin is about to move the player, and preloads there instead of at the login position.

Paced entity sync. Vanilla hands a joining player every entity in view range inside a single tick — on a populated base that is the spike everyone feels. CleanJoin holds that burst back and releases it over the next two seconds, ordered by what actually matters: other players, hostile mobs and projectiles first, then everything else, with item frames, armour stands, dropped items and XP orbs last. Whatever the player is riding, and anyone riding it with them, is never delayed. Dimension changes are paced the same way.

Async mob AI throttling. Passive mobs that no player is near have their AI suspended until someone comes back within range, which takes their pathfinding and goal selection out of the tick loop during peak load. The distance analysis runs off the main thread on Java 21 virtual threads; only the flag itself is written back, on the main thread. Named, leashed and ridden mobs, mounts and villagers are never touched, and everything CleanJoin suspends is restored on chunk unload and on shutdown — nothing is left frozen in your save.

Every threshold, radius and rate is configurable in config/cleanjoin-server.toml, and each of the three systems can be turned off on its own.

On the client (optional)

Adding CleanJoin to the client does not change TPS — it changes the join second, the gap between "Joining world" and the first smooth frame:

• Sync overlay. A vanilla-styled fade with a progress bar while the world streams in, instead of a frozen frame.
• Chunk mesh throttling. Caps how often chunk meshes are rebuilt during the join. This is the stutter people actually report as "lag when joining".
• Particle suppression. New particles are dropped for the duration of the join. A real win on machine-heavy bases.
• Adaptive pacing. The client reports its frame time and the server adjusts how fast it feeds entities — a player at 15 FPS gets a longer, gentler window, a player at 200 FPS is done sooner.

All four can be switched off individually in config/cleanjoin-client.toml.

Compatibility

CleanJoin is built to run on Arclight and other Bukkit hybrids. It detects the Bukkit layer at runtime, routes every write back to game state through the main thread so it cannot race the Bukkit event system, and wraps NMS access defensively so a remapped method degrades to a no-op instead of taking the server down.

Server-only, client-only and both-sides installs are all valid combinations and none of them produce a version mismatch in the server list. Client-only does nothing on its own — the mod needs a server that paces.

One note for hybrid operators: the paced entity sync works by mixing into ChunkMap, which is an area Arclight patches heavily. If entities behave oddly right after a join on a hybrid server, that is the first thing to rule out — set dripFeed.enabled = false and the rest of the mod keeps working.