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.

📝 Full Configuration Reference (click to expand)

Option	Default	Description
cpu_threshold	0.85	CPU usage threshold for throttling (0~1, higher = more lenient)
warmup_ticks	200	How many ticks after login to skip limits (20 ticks = 1 second)
preload_enabled	true	Enable background preloading
preload_radius	64	Preload radius (in chunks)
preload_delay_seconds	1	Seconds of standing still before preloading begins
distance_weight	0.5	Distance priority weight (closer = more priority)
direction_weight	0.4	Direction priority weight (forward-facing = more priority)
aging_weight	0.1	Aging priority weight (long-unloaded = more priority)
direction_multiplier	5.0	Direction bonus multiplier
aging_factor_ms	10000	How many milliseconds count as "aged"
log_loading	false	Log detailed info to console
performance_tips	true	Output debug log when CPU or MSPT exceeds threshold (no longer sent to chat)

There is also a runtime config at config/lazychunkload-runtime.json:

Option	Default	Description
limit_enabled	false	Set to true to completely disable CPU limits (full speed)
tips_disabled	false	Set to true to disable chat performance tips

---

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.