World pre-generation

Generate the chunks around spawn before the server gets busy with /nusa pregen, understand the radius in chunks, and keep TPS safe.

On this page

Pre-generation means creating chunks (pieces of the map) before players explore them. When players then travel far, the server only reads existing chunks from disk instead of generating new terrain in the middle of play. It helps a lot before opening day or a new season.

The radius is measured in chunks

The radius in /nusa pregen is measured in chunks, not blocks. One chunk is 16 × 16 blocks.

Radius (chunks)Roughly from spawnTotal width
32±512 blocksabout 1,040 blocks
64±1,024 blocksabout 2,064 blocks
128±2,048 blocksabout 4,112 blocks
256 (default limit)±4,096 blocksabout 8,208 blocks

The area is a square around the world's spawn chunk containing (2 × radius + 1)² chunks. For example, radius 22 covers 2,025 chunks.

The radius limit is pre-generation.max-radius-chunks. It defaults to 256 chunks and accepts 1 to 2048. Large radii take a long time and a lot of disk space.

How to use it

nusa pregen 64 world
nusa pregen status
nusa pregen pause
nusa pregen resume
nusa pregen cancel
CommandWhat it does
/nusa pregen <radius-in-chunks> <world>Starts pre-generation around that world's spawn
/nusa pregen statusProgress: generated, already existing, skipped near players and failed
/nusa pregen pausePauses without losing the position
/nusa pregen resumeContinues from the last position
/nusa pregen cancelStops the job
/nusa pregen helpCommand summary

A safe routine before opening:

  1. Start the server with no players (or at a quiet time).
  2. Run nusa pregen 64 world in the console.
  3. Watch nusa pregen status until it says FINISHED.
  4. Repeat for other worlds if needed, for example nusa pregen 32 world_nether.

Only one pre-generation job can run at a time, and only loaded worlds can be chosen. Required permission: nusaspigot.command.pregen (OP by default).

Keeping TPS safe

Pre-generation backs off by itself when the server is busy. It stops starting new work when TPS drops below minimum-tps or average MSPT goes above max-average-mspt, and continues once the server recovers. Chunks around online players are skipped for now, so players are not disturbed.

pre-generation:
  minimum-tps: 18.0
  resume-tps: 19.0
  max-average-mspt: 40.0
  max-in-flight: 2
  requests-per-tick: 1
  max-radius-chunks: 256
  player-buffer-chunks: 2
KeyDefaultMeaning
minimum-tps18.0Pause when TPS drops below this
resume-tps19.0Continue once TPS is back at this value
max-average-mspt40.0Pause when average MSPT goes above this
max-in-flight2Chunks processed at the same time. Raise it during maintenance with no players
max-radius-chunks256The largest radius allowed
player-buffer-chunks2Extra safety distance around players that is skipped

Save changes in nusa-global.yml, then do a full restart. Every key is explained in the Configuration reference.

Next steps

Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…