Architecture

Architecture and lifecycle

Startup sequence

WorldgenLibMod is a server-only ModSystem with an execution order of -1000. Its lifecycle is:

1. AssetsFinalize applies the narrow runtime seams and creates the initial terrain state.
2. StartServerSide creates the map and BlockLayers hosts, registers WorldgenLib callbacks, and starts the post-process host.
3. Consumer mods run their own StartServerSide methods and register hooks.
4. The InitWorldGen callback runs after the vanilla world-generation state is available.
5. WorldgenLib detects blocking takeovers. On a clean path it binds landforms, initializes the map and terrain hosts, freezes every hook list, and initializes sampling.
6. Generation callbacks invoke the hosts. A blocking conflict leaves the native or foreign generation callbacks in control.
7. Dispose unpatches WorldgenLib's Harmony IDs and restores captured vanilla state.

Narrow runtime seams

WorldgenLib does not blindly suppress every vanilla callback. It patches only the boundaries needed to avoid duplicate generation:

• GenMaps duplicate region generation and force forwarding
• GenTerra duplicate terrain generation
• GenTerraPostProcess duplicate cleanup generation
• GenBlockLayers final raise/filter injection and terminal pass entry

Vanilla initialization still runs when the clean path needs it. In particular, native GenMaps initialization can populate required-land state before the ocean map layer is constructed. WorldgenLib forwards force requests and preserves that state rather than replacing it with a disconnected copy.

Conflict gate

ConflictDetector runs before the WorldgenLib hosts take ownership of generation. It examines the known full-replacement mechanisms, including removed world-generation delegates and Harmony patches. A finding is either advisory or blocking.

When a blocking conflict is present:

• WorldgenLib's own map and terrain callbacks become no-ops.
• Vanilla or the foreign generator remains enabled.
• WorldgenLib prints a startup report instead of creating a second canonical pass.

When the detector cannot inspect a required owner or delegate layout, it fails closed for the affected mechanism. A missing inspection capability is not treated as proof that the pipeline is safe.

Required seam validation

The BlockLayers inline seam depends on a structural IL pattern. WorldgenLib checks that pattern before allowing raise or sea-level filter registrations. If the pattern is unavailable, inline registration fails clearly. A complete BlockLayers consumer can still use the terminal adapter if its migration does not depend on the scalar inline seam.

The same principle applies to the other required seams: if the library cannot install the callbacks needed for a safe pass, it disables itself rather than producing partial terrain.

Threading model

GenTerra processes columns in a parallel loop. Request-local scratch arrays are owned by the terrain request, while each column receives stack-scoped context values. Do not put mutable per-world or per-request data in static fields. ChunkContext.CustomData is synchronized during initialization, but the value stored there remains the consumer's responsibility to partition or synchronize.

GenMaps and post-process state are region or column scoped. Persistent region maps use per-region synchronization and bounded serialization.

Unload and reload

WorldgenLib captures and restores the vanilla latitude callback and the GenMaps.upheavelCommonness global it changes. Landforms are rebound when vanilla reloads its landform property before the freeze. A disposed post-process callback checks its registration state, so a stale event delegate becomes a no-op during a hot reload instead of mutating a later world.