FastWorldGen

FastWorldGen

A planning-first, region-batched world pre-generation plugin for Paper 1.21.11.

FastWorldGen follows a strict pipeline — PLAN → OPTIMIZE → BATCH → GENERATE → VERIFY — so you always see exactly how many chunks will be generated, and how many already exist, before any generation begins. Nothing is generated during planning; existing chunks are never touched unless you explicitly pass --fresh.

License: FastWorldGen is closed-source — All Rights Reserved (ARR). This repository is provided for documentation and support purposes only; there is no source code to build. Always get the plugin jar from the official Hangar page. See LICENSE for the full terms.

Features

• Plan before you generate. /fwg plan shows total chunks, existing chunks, chunks to generate, and region count before anything happens.
• Region-aware batching. Work is grouped by Minecraft's 32×32 chunk regions and ordered with a locality-aware sweep, keeping disk I/O local instead of jumping around the world.
• Live, detailed logging. Per-region and per-batch completion messages as generation runs, plus a full summary on completion (chunks generated, chunks failed, elapsed time, average chunks/sec). Optional sampled per-chunk logging for close inspection.
• Adaptive throughput. Automatically grows or shrinks how much work is submitted per tick based on observed server tick time (MSPT), so it backs off under load instead of hammering the main thread.
• Pause / resume / cancel, all graceful — in-flight work is allowed to finish safely rather than being interrupted mid-chunk.
• Crash/restart safe. Active-job parameters are persisted to disk; /fwg continue (or automatic resume on startup) re-plans from the world's actual state rather than trusting a possibly-stale completion count.
• Bounded memory. Regions are streamed as compact bitmasks rather than per-chunk objects, and generated chunks are unloaded once a configurable number stay loaded at once.
• Optional world lockdown. While a job is running, can restrict the world being generated (and swap the server-list MOTD to a progress message) so players can't accidentally trigger vanilla chunk generation inside the area FastWorldGen is working on.
• Update checks. Checks Hangar on startup and pings ops (colored, console + on join) when a newer version is available.
• Self-healing configuration. config.yml is checked against the plugin's bundled schema on every enable and /fwg reload: missing keys are restored, wrong-typed values are reset to their default, and unknown key/value pairs are removed, with a backup written first.

Requirements

• A Paper 1.21.11 server (or a Paper-based fork compatible with it)
• Java 21 or newer running the server itself

Nothing else — no build tools, no extra dependencies. FastWorldGen ships as a single jar.

Installation

1. Download the latest FastWorldGen-<version>.jar from Hangar.
2. Drop it into your server's plugins/ folder.
3. Restart the server (a full restart is recommended for first-time installation; /reload is fine for routine use afterward).
4. On first start, FastWorldGen writes its default plugins/FastWorldGen/config.yml. The defaults ship tuned for a high-performance server (dedicated/bare-metal or a well-resourced VPS with cores and fast storage to spare) — see Configuration below if you're on smaller hardware and want to scale the batch sizes or memory limits back down.

That's it — no compiling, no source, nothing to set up beyond that.

Commands

By default, existing chunks are never regenerated. Pass --fresh to force regeneration of the requested area; this is never the default behavior.

Examples

/fwg plan world world radius 5000
/fwg start world world radius 5000 center 0 0
/fwg start world world bounds -5000 -5000 5000 5000 --fresh
/fwg status world
/fwg pause world
/fwg resume world
/fwg cancel world

Permissions

Configuration

plugins/FastWorldGen/config.yml (created on first run) controls batch sizing, adaptive-throughput watermarks, progress reporting intervals, persistence, optional world lockdown during jobs, and safety limits (maximum area size, maximum chunks per plan, maximum in-flight chunk tasks, duplicate-job prevention). Every option is commented in the file itself — edit it directly and run /fwg reload to apply changes.

Tuned for high-performance hardware

The shipped defaults assume a server with cores and fast storage (NVMe/SSD) to spare — higher chunks-per-tick-batch, max-chunks-per-tick-batch, regions-per-batch, and max-inflight-chunk-tasks for more concurrent throughput, plus a higher max-loaded-chunks to keep more generated chunks resident instead of repeatedly reloading them. If you're on a small shared host or a box already tight on memory, scale these down; max-loaded-chunks and max-inflight-chunk-tasks are the two biggest memory knobs, and each has a comment in config.yml noting what to watch (GC pressure, OOM warnings) if you raise or lower it. Adaptive throughput (performance.adaptive-throughput) still backs off under real load regardless of these ceilings, so raising them just raises how far it's allowed to scale up when the server has headroom.

Self-healing configuration

On every plugin enable and every /fwg reload, FastWorldGen compares the config.yml on disk against its bundled defaults/schema:

• A missing key is restored using the bundled default value.
• A key whose value has the wrong type (e.g. text where a number is expected) is reset to the bundled default, since a type mismatch would otherwise misbehave wherever that value is used.
• A key that isn't part of the schema at all — a typo, a leftover from an older version, a manual addition that FastWorldGen doesn't read — is removed.

If a repair actually changes anything, a timestamped config.yml.bak-<epoch-ms> backup of the pre-repair file is written next to config.yml first, and a summary of what was restored, reset, or removed is logged to console.

Optional: world lockdown during jobs

If a player manually walks into the area a job is still generating, vanilla Minecraft will happily generate those chunks itself — it has no idea FastWorldGen "owns" that area. Lockdown (off by default; enable it under lockdown: in config.yml) guards against this by restricting the world while a job is active: an optional server-list MOTD swap to show job progress, optionally denying players from joining or teleporting into the locked world, and optionally kicking anyone already inside the moment lockdown engages. deny-join covers both a brand-new login into a locked default world and an in-progress teleport/portal into any locked world. Every sub-option defaults to off except the MOTD template text itself, which only takes effect once lockdown is enabled.

Persistence and restarts

FastWorldGen records the parameters of an active job (world, area, --fresh flag) to disk. On restart, it does not trust any previously recorded per-chunk completion state — it always re-inspects the world via the PLAN phase to determine what remains, then resumes generation safely from there (/fwg continue [world], or automatically on startup).

Update checking

On enable, FastWorldGen asynchronously checks Hangar (hangar.papermc.io/firesmasher/FastWorldGen) for a newer release. The result is logged to console in color. If an update is available, any operator (or holder of fastworldgen.admin) is sent a colored chat notice shortly after joining. This never blocks startup and failures are silent beyond a single console warning.

Safety notes

• Chunk generation is submitted via Paper's World#getChunkAtAsync, with completions handled on the main server thread, consistent with Paper's supported threading model.
• Backpressure limits (max-inflight-chunk-tasks) bound memory usage during large jobs.
• Area size and total chunk counts are validated against configurable safety limits before any planning work begins, to prevent integer overflow and unbounded memory usage on huge requests.
• Only one job may be active per world at a time by default.

Support

Questions, bug reports, and update notes live on the Hangar listing — that's also always the authoritative source for the current version and changelog.

License

All Rights Reserved (ARR). FastWorldGen is closed-source. You may run the compiled plugin jar on your own server(s); redistribution, modification, decompilation, and creation of derivative works are not permitted without the author's written consent. See LICENSE for the full text.