Iris/docs/07 - Pregeneration.md

07 - Pregeneration

Pregeneration walks a rectangular (by default square) block radius around a center and forces chunk generation so players do not trigger generation on first visit. Bukkit command /iris pregen (alias pregenerate) drives a single active PregeneratorJob backed by IrisPregenerator and a PregeneratorMethod. Settings under settings.json → pregen and world.globalPregenCache control timeouts, mantle residency, scheduler mode, and optional durable skip-cache.

See also: 03 - Configuration.md, 04 - Commands & Permissions.md, 02 - Getting Started.md, 06 - Worlds & Lifecycle.md, 29 - Client HUD & Protocol.md, 33 - Performance Tuning.md.

Commands

Command	Behavior
/iris pregen start <radius> [world=<world>] [center=0,0] [gui=true] [serial=false]	Start job
/iris pregen stop / x	Request stop; finishes in-flight work then cancels
/iris pregen pause / resume	Toggle pause on the active job
/iris pregen status	Print progress snapshot (chunks, %, speed, ETA, method, failed)

Only one pregen job instance is active. Starting a new job closes the previous instance.

start parameters

Param	Default	Notes
radius	required	Blocks from center on X and Z (radiusX = radiusZ). Must be > 0. Reported span is (radius * 2) by (radius * 2) blocks
world	contextual	Target world (Iris preferred; non-Iris uses hybrid method without engine cache wrapper when no access)
center	0,0	Block X/Z center; me uses player location when supported by director parsing
gui	true	Open desktop pregen GUI when host supports it; headless servers log and continue
serial	false	One chunk at a time via strict serial hybrid method; requires Paper (supportsStrictSerialPregeneration)

If the sender is a player without engine access, Iris warns that the world may not be fully loaded.

Area model

PregenTask builds saturating block bounds center ± radius, converts to chunk and region ranges, and iterates regions in spiral order with per-region chunk order pulled toward the center.

Limit	Value
Max region span per axis	117189 regions (~±30M blocks Minecraft world limit)
Oversized request	IllegalArgumentException at construction (does not hang)

Generation methods

Path	Method
Iris world, parallel	HybridPregenMethod(world, threadCount) with concurrency from settings parallelism
Iris world, serial=true	HybridPregenMethod.strictSerial(world)
Non-Iris world	Hybrid without engine
Cached wrapper	CachedPregenMethod around method when caching enabled and runtime scheduler mode is not Folia

Other method classes (AsyncPregenMethod, MedievalPregenMethod, AsyncOrMedievalPregenMethod) exist for specialized/API paths; the command path uses hybrid.

Cache

Setting	Location	Behavior
Per-job skip cache	World iris/pregen/ via GlobalCacheSVC.createDefault	Records generated chunks/regions so restarts can skip work when wrapper is active
world.globalPregenCache	settings.json	When true, maintains global per-world caches on world init/chunk load; when false, service stays idle after enable
Folia	Runtime scheduler resolved as Folia	Cached wrapper disabled for pregen

Cache write happens on world unload and service disable. Empty cache is used when the service is disabled.

Mantle and heap caps

Pregen applies mantle backpressure and heap high-water checks so tectonic plates do not exhaust memory.

Control	Default / rule
pregen.maxResidentTectonicPlates	Default 96, minimum effective floor 16
Effective plate cap	min(baseCap, heightScaledCap, heapBudgetCap) using world height vs 384 and ~60% of process heap / estimated plate size
Backpressure wait	mantleBackpressureWaitMs default 25 (clamped 5–1000)
Backpressure timeout	mantleBackpressureTimeoutMs default 60000 (clamped 5s–600s)
Hard cap trigger	Loaded plates > effectiveCap * 2 forces wait/evict
Heap high water	Pause generation while heap used ≥ 92%; release at 82%
Heap panic	≥ 96% requests panic reclaim / GC (throttled)
Save interval	saveIntervalMs default 30000 (clamped 5s–900s) during pregen loop

Raising maxResidentTectonicPlates increases memory headroom for speed; lowering reduces peak RAM. See 33 - Performance Tuning.md.

Other pregen settings

Key	Default	Role
runtimeSchedulerMode	AUTO	Influences Folia vs paper-like scheduling for pregen cache and related paths
paperLikeBackendMode	AUTO	Paper-like lifecycle backend selection
chunkLoadTimeoutSeconds	15 (5–120)	Chunk load timeout during pregen
timeoutWarnIntervalMs	500 (≥250)	Warning interval for stalled loads
moddedPregenInFlight	0 → auto max(16, min(48, cpu*2))	In-flight cap for modded pregen adapters

Pause / stop / status

Action	Behavior
Pause	PregeneratorJob.pauseResume() flips pause; generator loop spins while paused or heap high-water
Stop	shutdownInstance() closes pregenerator and interrupts worker asynchronously
Status	progressSnapshot(): percent, generated, total, chunks/s, ETA, elapsed, method name, paused flag, failed count, world name

Failed chunks are counted separately and shown in status when non-zero.

HUD / GUI / protocol

Surface	Behavior
Desktop GUI	PregenRenderer when gui=true and GUI host available; colors mark existing, generating, network, generated, cleaned, mantle states
Boss bar / loader HUD	Create and some pregen attach paths use HUD slot claims for progress (creation pregen and studio progress reporters)
Client protocol	IrisProtocolServer.broadcastPregenProgress sends progress to connected Iris client sessions

Client HUD details: 29 - Client HUD & Protocol.md. GUI toggles: settings.gui.useServerLaunchedGuis, maximumPregenGuiFPS.

Performance profile

Starting pregen applies PregenPerformanceProfile to the engine (or global) before the job runs. Studio profile command can also apply the pregen performance profile while measuring pack cost.

Operator notes

• Radius is in blocks, not chunks or regions.
• Re-running pregen over the same area is faster when the chunk cache wrapper is active and cache files under iris/pregen remain.
• Unload/remove of a world with active pregen should stop the job for that world identity when lifecycle hooks call shutdown-for-world.
• Serial mode is for diagnosis/stability on Paper, not peak throughput.