Lazy Chunk Load

Lazy Chunk Load

The vanilla chunk loading system schedules a massive number of chunks around the player all at once, causing instant server CPU overload and TPS collapse. Lazy Chunk Load improves this process: it controls chunk loading speed like a faucet — automatically turning down when the CPU is busy and opening up when idle — so exploring new terrain no longer stutters.

What This Mod Does

🚶 Anti-Lag Exploration

With this mod installed, the server automatically adjusts chunk loading frequency based on current CPU usage. Full speed when usage is low, automatically slows down when usage spikes — TPS stays rock-solid throughout.

• It doesn’t make chunk loading faster — it makes it smoother. Trade a bit of instant speed for a stutter-free experience.
• True prevention, not an after-the-fact fix.

🔄 Background Preloading

When you’re standing still, the mod automatically uses idle CPU to preload ungenerated chunks around you.

Priority: chunks under your feet first, then in your line of sight, then to the sides and behind.

• Enabled by default, works while idling.
• Automatically pauses when the CPU is busy — never steals resources.
• Status output to log every 5 seconds.

🛡️ Additional Protections

• Login Warmup: No limits for the first 10 seconds after joining a world, ensuring initial terrain loads quickly.
• Save Safety: Automatically pauses all chunk loading during world saves to prevent save stalling.
• Emergency Bypass: When the player steps on an unloaded chunk, all limits are bypassed and the chunk loads immediately.
• Hotspot Chunk Tracking: Frequently-accessed chunks are marked as hotspots; preload extends their retention time.
• Dimension Whitelist/Blacklist: Restrict preloading scope via dimension_blacklist / dimension_whitelist to avoid wasting CPU in custom dimensions.

Installation

Drop it into your mods folder — no configuration needed to work out of the box. Server-side only; clients do not need to install it.

Singleplayer works perfectly fine too.

| Platform | Supported Versions |
|—|—|
| Fabric | 1.21.x |
| Fabric | 26.1+ |
| Forge | 1.20.1 |
| NeoForge | 1.21.1 |

💡 Fully compatible with optimization mods like C2ME, Lithium, and VulkanMod. Does not modify chunk generation algorithms — only adjusts loading rhythm.

🗺️ Automatically detects Chunky pre-generation tasks and lifts CPU limits during generation for full speed; restores automatically when complete.

Monitoring

Every 5 seconds a status line is logged to logs/latest.log:

[LazyChunkLoad] Tick:1200 CPU:45% Sched:3/t Warmup:N Preload:ON Main:OK

| Field | Meaning |
|—|—|
| Tick | Current tick count |
| CPU | CPU usage percentage |
| Sched | Chunks loaded last tick |
| Warmup | Y=Warming up / N=Normal |
| Preload | ON=Active / OFF=Disabled / PAUSED=CPU too high |
| Main | OK=Full speed / SLOW=Throttled |

Configuration

The config file is located at config/lazychunkload.json (auto-generated, takes effect immediately on changes).

If you just want to use the mod normally, you don’t need to read any of this — the defaults are already best practice.

How It Works

1. Checks CPU usage once per tick (1-second cache, near-zero overhead).
2. CPU below 85%: chunks load normally, no restrictions.
3. CPU above 85%: chunk loading frequency is automatically reduced — the higher the CPU, the stronger the limit, but even in the worst case, at least one pass is allowed every 0.2 seconds — ensuring terrain never gets permanently stuck.
4. When you’re standing still: background scanning of ungenerated chunks around you, loaded in prioritized batches.
5. When you’re exploring: stepping on an empty chunk triggers an immediate emergency bypass with no limits applied.