Buffering for Performance¶

Quick Start: Scale up for big servers.

This guide sets up a deep buffer of pregenerated cells, so back to back matches always start on ready terrain. The short version: raise the buffer to 30-100, let the interval preloads fill it over a few hours, and gate the heavy work to intermissions.

How the pieces fit¶

Three systems cooperate, each on its own schedule:

1. Fetching keeps stored-cells-buffer valid cells ahead of match starts. A buffered cell is valid, not necessarily pregenerated yet.
2. Chunk preloads pregenerate the oldest buffered cell that still needs it, roughly every interval-seconds while Chunky is idle. A cell counts as preloaded only at 100 percent.
3. Matches take the oldest buffered cell. Since preloads run oldest-first, that cell is pregenerated whenever any buffered cell is.

Read Preloading Cells for the full reference; this guide only covers the performance setup.

1. Size the buffer¶

Each buffered cell costs roughly 15-30MB on disk, depending on the preload radii. For a buffer of 50, plan for about 1-1.5GB plus headroom.

world-engine:
  preloading:
    cell-fetch:
      stored-cells-buffer: 50
      increment-when: ALWAYS

• Start with 30 and grow toward 100 if matches still outrun the preloads. Bigger is not always better: every slot is disk and pregeneration time.
• Watch how many buffered cells are preloaded after a busy evening; if the count sits at zero, the buffer is too deep for your hardware, or matches run too hot for the preload schedule below.

Keep world-engine cell cleanups enabled, and restart the server on a routine schedule so the cleanup cycles run. Without cleanups, used cells pile up next to the buffer and eat the disk you budgeted.

2. Gate the heavy work to intermissions¶

Pregeneration and fetching both cost disk IO. On a busy server, run them only while no match is running:

world-engine:
  preloading:
    cell-fetch:
      increment-when: NO_MATCH_RUNNING
    chunk-preload:
      run-when: NO_MATCH_RUNNING

With either policy set, a starting match pauses Chunky and the last ending match resumes it, so an in-flight task never steals from gameplay. A pause you set yourself is never resumed by the plugin.

3. Tune the preload radii¶

The overworld radius defaults to 100 blocks around the cell center; the nether preloads the corresponding area (coordinates divided by 8) and defaults to 60. Larger radii cost more time and disk per cell. Keep the nether smaller: matches reach it less often.

world-engine:
  preloading:
    chunk-preload:
      shape: CIRCLE
      interval-seconds: 30
      overworld:
        radius: 100
      nether:
        radius: 60

4. Fill the buffer once¶

Initially it can take around 30 minutes to 2 hours for enough cells to preload to fill the buffer. This is normal: Chunky generates every chunk the first time. Plan the first fill during a quiet window, or before opening the server.

A few notes for the first fill:

• Set continue-on-restart: true in Chunky's own config.yml, so an interrupted task survives reboots instead of restarting.
• Restarts do not lose progress. Chunky skips chunks it already generated, so the engine replays the remaining work cheaply.
• While Chunky is busy, attempts fail quietly and retry (at a third of the interval after a full interval of failures), so your own manual Chunky tasks simply delay the fill instead of breaking it.

5. Verify and maintain¶

After the fill, matches should start on pregenerated cells even during back to back games. If starts feel laggy again, check the usual suspects in order:

1. Is Chunky installed and enabled? Without it the hook stays quiet and cells start unprepared (one console warning).
2. Is the buffer deep enough for your match rate? Raise stored-cells-buffer toward 100.
3. Is something else keeping Chunky busy? Manual tasks and the match pause both show up as idle gaps in the fill.
4. Is the disk full? Confirm cleanups run and restarts happen.

One last rule of thumb: fetch and preload budgets multiply. A buffer of 100 with a 100 block overworld radius asks far more from the disk than a buffer of 30 with 60. When in doubt, shrink the radii before you shrink the buffer.