Перейти к содержимому
Mineforgian

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

Загрузки
8K
Подписчики
19
Обновлён
19 июля 2026 г.
Лицензия
MIT

Опубликован 17 июня 2026 г.

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.

Ченджлог

1.3.0Релиз1.20.1 · 19 июля 2026 г.

1.3.0 — 2026-07-19

🆕 New

  • Unload Strategy: Clears internal chunkLastSeen entries under memory pressure using three conditions — far from players, non-hotspot, sufficiently old. Disabled by default; can be enabled in config
  • Hotspot Chunk Tracking: Records frequently-accessed chunks; preload extends their retention, unload protects them first
  • Dimension Whitelist/Blacklist: Restrict preloading scope via dimension_blacklist / dimension_whitelist to avoid wasting CPU in custom plot worlds
  • Stats Collector: Internal StatsCollector tracks preload / throttle-skip / emergency-load counts for diagnostics
  • NeoForge 1.21.1 Platform: Added NeoForge 1.21.1 alongside existing Fabric 1.21.x / Forge 1.20.1
  • Fabric 26.1 Platform: Adapted to MC 26.1's new API (ChunkPos record, removed obfuscation mappings, etc.). Requires JDK 25 to compile

🔧 Optimizations

  • Preload Path Prediction Cache: MovementPredictor.pathAlignment was being called ~200 times/tick/level inside the scan loop, creating ~4800 temporary Vec3 objects per tick. Now caches predictPath once at entry and passes it in batches — temp objects drop from ~4800/tick to ~8/tick
  • Independent 26.1 Core: MC 26.1 API changes were too large (ChunkPos record, GameProfile.getName removed, ServerPlayer.serverLevel removed, ResourceKey.location removed, etc.) — no longer shares source with common, maintained as an independent core copy

🔧 Fixes

  • Fixed performance regression caused by UnloadStrategy default-on: When enabled by default, evictFarChunks cleared chunkLastSeen at ≥85% memory, dropping affected chunks' agingScore from ~1.0 to ~0.63 and degrading preload effectiveness. Default changed to disabled
1.2.0Релиз1.21.1 · 14 июля 2026 г.

Add version for neoforge 1.21.1

1.2.0Релиз26.1.1, 26.1.2, 26.2 · 24 июня 2026 г.

1.2.0 — 2026-06-24

🆕 New

  • Chunky Integration: Automatically lifts CPU limits during Chunky pre-generation for full-speed generation with chat notification; restores limits and notifies when tasks finish
  • More Version Support: Added Fabric support for Minecraft 26.1 and above
1.1.0Релиз1.20.1 · 18 июня 2026 г.

Lazy Chunk Load Changelog

1.1.0 — 2026-06-17

🆕 New Features

  • Stepped CPU Throttling: Main chunk loading now dynamically adjusts its frequency based on CPU usage. Full speed below 85% CPU, progressively slowing down between 85%~100%. At worst, chunks are processed every 0.2s — terrain never gets stuck.
  • Preloading Enabled by Default: Background preloading is now on by default. Idle players will have surrounding chunks generated automatically.
  • Priority-Based Preloading: Chunks are prioritized by three weighted scores — distance (closer first), look direction (ahead first), and aging (long-unloaded first). Chunks under your feet and in front of you load first.
  • F3 Debug Overlay: Press F3 to see CPU usage, chunks loaded per tick, throttle status, and preload state at the bottom-left of the screen.
  • Warmup Protection: No throttling for the first 10 seconds after joining a world, ensuring spawn chunks load quickly.
  • Save Safety: Preloading and throttling are automatically paused during world saves to prevent conflicts.
  • Emergency Pass-Through: If a player steps into an unloaded chunk, all limits are bypassed — the chunk loads immediately.
  • VulkanMod Compatible: F3 overlay silenty disables itself when VulkanMod is present. Core functionality is unaffected.

🔧 Optimizations

  • CPU polling uses a 1-second cache (down from once per tick), virtually zero overhead
  • Preload queue periodically prunes already-loaded chunks to prevent memory bloat
  • Preloading auto-pauses during player movement to avoid competing for CPU

❌ Removed

  • Removed /lazychunkload commands to avoid server permission issues
  • All settings now managed via config/lazychunkload.json and config/lazychunkload-runtime.json

📦 Supported Platforms

Platform Version
Fabric 1.21.x
Forge 1.20.1

1.0.0 — 2026-06-14

  • Initial release
  • Basic CPU monitoring and throttling
  • /lazychunkload status / tips commands
1.1.0Релиз1.21.9, 1.21.10, 1.21.11 · 18 июня 2026 г.

Lazy Chunk Load Changelog

1.1.0 — 2026-06-17

🆕 New Features

  • Stepped CPU Throttling: Main chunk loading now dynamically adjusts its frequency based on CPU usage. Full speed below 85% CPU, progressively slowing down between 85%~100%. At worst, chunks are processed every 0.2s — terrain never gets stuck.
  • Preloading Enabled by Default: Background preloading is now on by default. Idle players will have surrounding chunks generated automatically.
  • Priority-Based Preloading: Chunks are prioritized by three weighted scores — distance (closer first), look direction (ahead first), and aging (long-unloaded first). Chunks under your feet and in front of you load first.
  • F3 Debug Overlay: Press F3 to see CPU usage, chunks loaded per tick, throttle status, and preload state at the bottom-left of the screen.
  • Warmup Protection: No throttling for the first 10 seconds after joining a world, ensuring spawn chunks load quickly.
  • Save Safety: Preloading and throttling are automatically paused during world saves to prevent conflicts.
  • Emergency Pass-Through: If a player steps into an unloaded chunk, all limits are bypassed — the chunk loads immediately.
  • VulkanMod Compatible: F3 overlay silenty disables itself when VulkanMod is present. Core functionality is unaffected.

🔧 Optimizations

  • CPU polling uses a 1-second cache (down from once per tick), virtually zero overhead
  • Preload queue periodically prunes already-loaded chunks to prevent memory bloat
  • Preloading auto-pauses during player movement to avoid competing for CPU

❌ Removed

  • Removed /lazychunkload commands to avoid server permission issues
  • All settings now managed via config/lazychunkload.json and config/lazychunkload-runtime.json

📦 Supported Platforms

Platform Version
Fabric 1.21.x
Forge 1.20.1

1.0.0 — 2026-06-14

  • Initial release
  • Basic CPU monitoring and throttling
  • /lazychunkload status / tips commands

Комментарии

Загружаем…