ChunkLoader

ChunkLoader

Admin-controlled circular chunk pre-generation plugin for Paper 1.21.x

What is ChunkLoader?

ChunkLoader lets server admins pre-generate chunks in a perfect circular area around their position — similar to Chunky, but simpler and focused on pure admin control.

No more lag spikes when players explore new areas. Pre-generate your world before opening the server.

Features

• Circular selection — only chunks within exact Euclidean radius are processed (not a square)
• Batch processing — chunks load in small configurable batches, no server freezes
• TPS/MSPT throttling — automatically slows down when your server is under load
• Boss bar progress — live progress bar shown to all online players
• Persistent jobs — progress is saved after every batch; server restarts resume automatically
• Console + chat feedback — percentage, ETA, speed, TPS shown in real time
• Full command set — start, pause, resume, cancel, status, reload

Commands

Aliases: /cl, /cloader

Permissions

Configuration

chunks-per-batch: 10         # Chunks per batch (normal conditions)
batch-delay-ticks: 5         # Ticks between batches (normal)
tps-threshold: 18.0          # Switch to slow mode below this TPS
mspt-threshold: 45.0         # Switch to slow mode above this MSPT
slow-batch-size: 3           # Chunks per batch (stressed server)
slow-delay-ticks: 20         # Ticks between batches (stressed server)
progress-interval-seconds: 5 # How often to print progress (0 = disable)

How It Works

1. Stand where you want the center of generation to be
2. Run /chunkloader <radius> — e.g. /chunkloader 100
3. ChunkLoader computes every chunk within the circular radius (not a square)
4. Chunks are loaded in batches using Paper's async chunk API — zero main thread blocking
5. Progress is displayed on a boss bar visible to all players
6. If the server restarts, the job automatically resumes from where it left off

Circular Shape

/chunkloader 3 processes approximately:

      █ █ █
    █ █ █ █ █
  █ █ █ █ █ █ █
  █ █ █ █ █ █ █
  █ █ █ █ █ █ █
    █ █ █ █ █
      █ █ █

Only chunks whose distance from the center satisfies √(dx² + dz²) ≤ radius are included.

Requirements

• Paper 1.21.x (1.21.4 recommended)
• Java 21+

Spigot / Bukkit are not supported — this plugin uses Paper-specific async chunk loading APIs.

Installation

1. Download ChunkLoader-1.0.0.jar
2. Place it in your server's plugins/ folder
3. Restart the server
4. Configure plugins/ChunkLoader/config.yml as needed
5. Run /chunkloader <radius> in-game