Preloading Cells¶

Quick Start: Scale up for big servers.

Fetching and pregenerating are two separate sequences. Fetching keeps a buffer of valid cells ahead of match starts; the interval preloads then pregenerate those cells through Chunky in the background. Matches never wait for a preload: they take the oldest buffered cell and teleport.

Why pre-generate: building terrain at high coordinates lags active matches. Doing it during intermissions moves that work out of gameplay.

world-engine:
  preloading:
    cell-fetch:
      stored-cells-buffer: 3
      increment-when: ALWAYS
      buffer-refill-per-attempt: 1
    prepare-timeout-seconds: 30
    chunk-preload:
      enabled: true
      shape: CIRCLE
      interval-seconds: 30
      run-when: ALWAYS
      overworld:
        enabled: true
        radius: 100
      nether:
        enabled: true
        radius: 60

Cell Fetch¶

• stored-cells-buffer is how many fetched cells to keep. Default 3, minimum 1. A buffered cell is simply a fetched cell known to be valid, not necessarily pregenerated yet.
• Matches consume the oldest buffered cell at start (which is pregenerated whenever any buffered cell is, since preloads run oldest-first); if the buffer is empty, the match fetches a fresh cell on the spot instead. Inspect it with /manhunt worldengine cellindex buffer.

increment-when decides when the buffer refills:

• ALWAYS: refill whenever a slot is free, even while matches run.

• NO_MATCH_RUNNING: only refill while no match is running. Use this when fetching is heavy enough to lag active matches.

• buffer-refill-per-attempt caps how many cells one refill pass fetches before yielding the server thread. Default 1, minimum 1, maximum 30. Passes chain across ticks until the buffer is full, and candidate chunks load asynchronously, so even a large buffer never stalls the server the way a bulk preload would. The same bound covers end dimension top-ups.

• The buffer tops up after match end, when an autostart countdown begins, and about once a minute. Cells fetch in the background; a failed fetch retries once after 30 seconds.

Chunk Preloads¶

When the Chunky plugin is installed, buffered cells pregenerate through it automatically: no commands to configure.

• enabled toggles the hook (default true, still needs Chunky). shape picks the pregeneration shape passed straight to Chunky: CIRCLE (the default) or SQUARE.
• Every interval-seconds (default 30, minimum 5, maximum 3600) the engine attempts one preload, but only while Chunky is idle on the wanted worlds. The target is always the oldest buffered cell (smallest index) whose preloaded flag is still false.
• A cell counts as preloaded only once its tasks finish at 100 percent: a pause, a server close, or a refused start never flips the flag. Chunky skips chunks it already generated, so an interrupted cell resumes cheaply on the next attempt.
• While Chunky is busy (your own manual tasks included), attempts fail quietly and nothing starts. After a full interval of failed attempts the engine retries at a third of the configured rate (30 seconds becomes 10) until one succeeds.

run-when decides when preloads run:

• ALWAYS: run on the interval, even while matches run.

• NO_MATCH_RUNNING: only run while no match is running.

• Under either NO_MATCH_RUNNING policy (fetch or preload), a starting match pauses Chunky and the last ending match resumes it, so pregeneration never steals from gameplay. Only a plugin-made pause is ever resumed: a pause you set yourself stays paused. Set continue-on-restart: true in Chunky's own config.yml so an interrupted task survives reboots.

Overworld and Nether¶

Each dimension has its own switch plus radius. Both default to enabled; the overworld radius defaults to 100 blocks around the cell center, the nether to 60.

• The nether task preloads the cell's corresponding area (overworld coordinates divided by 8) in the <world>_nether world, and it runs in parallel with the overworld task, since Chunky supports parallel tasks across worlds.
• The cell counts as preloaded only once both tasks finish: if the nether finishes first, the engine still waits for the overworld before moving on to the next cell. One round accounts for both dimensions rather than two independent tasks.
• When the nether world is not loaded, the round covers the overworld alone and warns once.
• Keep the nether radius smaller than the overworld one: matches reach the nether less often, so the smaller area is the better trade.

Prepare Timeout¶

• prepare-timeout-seconds is the hard fallback for the preparing phase: a match that still prepares after this many seconds is cancelled. Default 30, minimum 0, which waits forever. Raise it for long cinematic films plus a long stagger window.
• Before preparing, a match waits for a running cell fetch, if any; otherwise it teleports to its cell at once. Preloads never gate the start, since they run on their own interval.

For the full performance setup (deep buffers, intermission gating, first fill), see the Buffering Guide.