Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PaperMC/Paper/llms.txt

Use this file to discover all available pages before exploring further.

Paper’s chunk system is one of its most significant performance improvements over vanilla Minecraft. The Moonrise chunk system provides multi-threaded chunk loading, generation, and I/O operations.

​
Chunk System Architecture

​
Moonrise Worker and I/O Pools

Paper uses two separate thread pools for chunk operations:
  1. Worker Pool: Handles chunk generation, lighting calculations, and general processing
  2. I/O Pool: Manages disk read/write operations for chunk data
Both pools are defined in ca.spottedleaf.moonrise.common.util.MoonriseCommon: 
public static final BalancedPrioritisedThreadPool WORKER_POOL
public static final BalancedPrioritisedThreadPool IO_POOL
The thread pools use a queue hold time of 20ms for workers and 25ms for I/O operations, balancing responsiveness with throughput.

​
Configuration Options

​
Global Chunk Loading Settings

File: config/paper-global.yml 
chunk-loading-basic:
  player-max-chunk-send-rate: 75.0
  player-max-chunk-load-rate: 100.0
  player-max-chunk-generate-rate: -1.0

​
player-max-chunk-send-rate

Maximum chunks per second sent to each player.
  • Default: 75.0
  • Unit: chunks per second
  • Recommendation: 50-100 for most servers
Set to -1 to disable the limit. Higher values improve player movement responsiveness but increase network usage.

​
player-max-chunk-load-rate

Maximum chunks per second loaded for each player (includes checking if chunks are already generated).
  • Default: 100.0
  • Unit: chunks per second
  • Impact: Affects teleportation speed and world exploration
This setting affects chunk generation rate since loading always checks if generation is needed first.

​
player-max-chunk-generate-rate

Maximum chunks per second generated for each player.
  • Default: -1.0 (unlimited)
  • Unit: chunks per second
  • Use case: Prevent lag spikes during rapid world exploration

​
Advanced Chunk Loading Settings

chunk-loading-advanced:
  auto-config-send-distance: true
  player-max-concurrent-chunk-loads: 0
  player-max-concurrent-chunk-generates: 0

​
auto-config-send-distance

Matches server send distance to client view distance settings (if smaller).
  • Default: true
  • Benefit: Prevents unnecessary chunk sends to clients with low view distance

​
player-max-concurrent-chunk-loads

Maximum simultaneous chunk load operations per player.
  • Default: 0 (auto-configured based on player count)
  • Manual values: Set to -1 for unlimited, or positive number for fixed limit
Auto-configuration adjusts concurrency based on server load and player count. Manual tuning is rarely necessary.

​
player-max-concurrent-chunk-generates

Maximum simultaneous chunk generation operations per player.
  • Default: 0 (auto-configured)
  • Impact: Limits CPU usage during world generation

​
Thread Pool Configuration

File: config/paper-global.yml 
chunk-system:
  io-threads: -1
  worker-threads: -1

​
io-threads

Number of threads dedicated to chunk I/O operations.
  • Default: -1 (auto-configured, minimum 1)
  • Recommendation: 1-2 threads for most servers
  • Storage consideration: More threads benefit NVMe SSDs over HDDs
For servers on NVMe storage with 16+ CPU cores, consider setting this to 2 for improved I/O parallelism.

​
worker-threads

Number of threads for chunk generation and processing.
  • Default: -1 (auto-configured based on CPU cores)
  • Auto-calculation:
    • 4 cores or less: 1-2 worker threads
    • More than 4 cores: (cores / 2) / 2
    • Can be overridden with -DPaper.WorkerThreadCount=N JVM flag
Example auto-configuration:
CPU CoresWorker Threads
4 or less1-2
82
164
328
Setting too many worker threads can cause thread contention and reduce performance. Start with auto-configuration.

​
Per-World Chunk Settings

File: config/paper-world-defaults.yml 
chunks:
  auto-save-interval: default  # Inherited from server.properties
  max-auto-save-chunks-per-tick: 24
  fixed-chunk-inhabited-time: -1
  prevent-moving-into-unloaded-chunks: false
  delay-chunk-unloads-by: 10s

​
auto-save-interval

How often chunks are saved to disk.
  • Default: Inherits from server.properties (6000 ticks / 5 minutes)
  • Format: Duration (e.g., 5m, 300s, or ticks as integer)
Frequent autosaves cause I/O spikes. Increasing the interval reduces stuttering but increases data loss risk on crashes.Recommended values:
  • Small servers (< 20 players): 6000 (5 min)
  • Large servers (50+ players): 12000 (10 min)

​
max-auto-save-chunks-per-tick

Maximum chunks saved per server tick during autosave.
  • Default: 24
  • Impact: Spreads autosave I/O across multiple ticks
Higher values complete autosaves faster but cause larger lag spikes. Lower values spread out the I/O cost.

​
delay-chunk-unloads-by

Delay before unloading chunks after all players leave the area.
  • Default: 10s
  • Benefit: Prevents chunk reload thrashing when players move in/out of areas
delay-chunk-unloads-by: 10s  # Keep chunks loaded for 10 seconds

​
entity-per-chunk-save-limit

Limit specific entity types saved per chunk to prevent chunk save lag. 
chunks:
  entity-per-chunk-save-limit:
    arrow: -1         # Unlimited
    ender_pearl: -1
    experience_orb: -1
    fireball: -1
    small_fireball: -1
    snowball: -1
Set to a positive number to limit entities of that type. Useful for preventing projectile buildup in chunks.

​
Optimization Strategies

​
1. Rate Limiting for Exploration

Prevent chunk generation lag during rapid exploration: 
chunk-loading-basic:
  player-max-chunk-generate-rate: 10.0  # Limit to 10 chunks/sec per player

​
2. View Distance Tuning

File: config/spigot.yml 
world-settings:
  default:
    view-distance: 8
    simulation-distance: 6
Each view distance increase loads exponentially more chunks:
View DistanceChunks LoadedPerformance Impact
6169Low
8289Medium
10441High
12625Very High
Recommendation: Use 6-10 for most servers.

​
3. Pregenerate Worlds

Pregenerate chunks to eliminate runtime generation lag: 
# Using Chunky plugin
/chunky radius 5000
/chunky world world
/chunky start
Benefits:
  • No generation lag during gameplay
  • Consistent TPS
  • Better for PvP and minigame servers

​
4. Optimize Chunk I/O

Use NVMe storage: 5-10x faster than SATA SSDs for chunk operations Region file cache (config/paper-global.yml): 
misc:
  region-file-cache-size: 256  # Default
Increase for servers with large world sizes or many dimensions: 
misc:
  region-file-cache-size: 512  # For large servers

​
Monitoring Chunk Performance

​
Using Spark

Profile chunk system performance: 
/spark profiler start --thread *
# Wait 60 seconds
/spark profiler stop
Look for:
  • Paper Worker threads - chunk generation time
  • Paper I/O Worker threads - disk I/O bottlenecks

​
Timings

/timings on
# Play for 5 minutes
/timings report
Review “Chunks” section for load/generation times.

​
Troubleshooting

​
Slow Chunk Loading

Symptoms: Chunks load slowly during teleportation or flight Solutions:
  1. Check player-max-chunk-load-rate (increase to 150-200)
  2. Verify storage performance (NVMe recommended)
  3. Increase worker-threads if CPU usage is low

​
Chunk Generation Lag

Symptoms: TPS drops when exploring new areas Solutions:
  1. Set player-max-chunk-generate-rate to 5-10
  2. Pregenerate the world
  3. Reduce view distance temporarily

​
Autosave Lag Spikes

Symptoms: Regular lag spikes every 5 minutes Solutions:
  1. Increase auto-save-interval to 10+ minutes
  2. Reduce max-auto-save-chunks-per-tick to spread I/O
  3. Upgrade to faster storage (NVMe)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us