Migration

Migration guide

This page maps the four analyzed worldgen consumers to WorldgenLib seams. It is a migration plan, not a claim that their external repositories have already been rewritten. The current library analysis gives every observed server-side worldgen mechanism a destination. Actual source changes and in-game runs still belong to each consumer's repository and owner.

General migration sequence

1. Keep the consumer's client-only rendering code. WorldgenLib covers the server world-generation boundary.
2. Register all hooks, landforms, and region-map slots in StartServerSide.
3. Remove the consumer's duplicate GenMaps, GenTerra, post-process, or BlockLayers ownership only after its replacement hooks are ready.
4. Use a full adapter during an incremental migration when the algorithm cannot yet be decomposed. Replace it with atomic hooks when the pieces are stable.
5. Run the consumer's own tests and a clean server world before releasing.
6. Record the selected order values and any incompatible-provider policy.

The StartServerSide registration deadline is important. The host freezes registries and hook lists at InitWorldGen.

Rivers-Mod

Existing responsibility	WorldgenLib destination
Custom river landform variant	LandformRegistry.Register("rivers:riverlandform", variant)
Valley blending	Step 2, modifying ColumnContext.LandformWeights
Water selection	Step 5, modifying ColumnContext.WaterBlockId
SDF or ellipsoid channel carving	Step 10 with ColumnCarvingContext
Flow vectors or river distance	Step 10 for column data, TerrainFinalize for request-wide data
BlockLayers raise damping	RegisterBlockLayersRaiseModifier
Client flow rendering	Keep in the consumer mod

Use AfterVanillaMin + 50 as the initial terrain and BlockLayers order. Keep the river landform code namespaced unless compatibility with an existing saved world requires the established code.

Remove the StartServerSide takeover prefix, the full GenTerra replacement, and the BlockLayers transpiler after the new hooks produce the intended result. RegisterFullTerrainGeneration is available as a temporary terminal bridge if the original carving algorithm still needs the complete request.

VSRiverGen

Existing responsibility	WorldgenLib destination
Removal of vanilla WorldgenHandlers delegates	Remove the delegate-removal code
Existing game:riverlandform lookup	LandformRegistry.GetIndex("game:riverlandform")
Valley blending	Step 2 and, when required, Step 7
Water type	Step 5
SDF channel carving	Step 10
BlockLayers raise damping	RegisterBlockLayersRaiseModifier

VSRiverGen and Rivers-Mod have overlapping river semantics. Treat them as alternative providers unless their owners define how landform indexes, flow data, and carving interact.

Watersheds

Existing responsibility	WorldgenLib destination
GenTerra replacement	Steps 4, 7, and 10, or the full terrain adapter
Custom GenMaps chain	The nine map hooks or the full region adapter
Stream and watershed maps	RegionMapRegistry plus RegionContext.GetMap
Forked terrain sampler	TerrainSampler and SamplingModifiers
Stream-aware BlockLayers pass	Full BlockLayers adapter
Request-wide data	ChunkContext.CustomData and TerrainFinalize

Use AfterVanillaMin + 60 for erosion and stream terrain effects as the starting point. Use generator wrappers at the map stages when Watersheds needs to wrap the vanilla chain. A custom region algorithm that remains indivisible can use RegisterFullMapRegionGeneration while the map pieces are migrated.

The ignoreRivers sampler argument is retained for call-site compatibility. The current canonical sample has no built-in river field, so Watersheds should apply its stream transform through SamplingModifiers or its own ordered adapter.

Terra Prety

Existing responsibility	WorldgenLib destination
Ocean map smoothing	RegisterMapGenerator(MapGeneratorStep.Ocean, ...)
Landform map smoothing	RegisterMapGenerator(MapGeneratorStep.Landform, ...)
Upheaval padding change	RegisterMapPadding for MapGeneratorStep.Upheavel
Post-map continental upheaval	RegisterMapsRegionFinalize
Terrain carving and coast work	Steps 4, 7, and 10, or the full terrain adapter
Disable sea-level rise	RegisterBlockLayersSeaLevelFilter
Force requests	ForceLandformAt, ForceClimateAt, RequireLandAt, and ForceRandomLandArea

Use BeforeVanillaMin through BeforeVanillaMax for map-generator wrappers that must alter the input to the vanilla chain. Start normal terrain effects at AfterVanillaMin + 50; use AfterVanillaMin + 70 for post-placement carve work and AfterVanillaMin + 60 for the BlockLayers filter.

Remove the delegate-removal code, factory prefixes, and BlockLayers transpiler after the corresponding registrations are active. Keep any visual or client asset code in Terra Prety.

Migration checklist

• The consumer checks WorldgenLibAPI.IsLoaded and reports a missing dependency clearly.
• Registration happens in StartServerSide before InitWorldGen.
• Every custom code is namespaced and stable across releases.
• Every region map declares bounded dimensions and a format version.
• Every hook has a documented order and leaves unrelated coordinates unchanged.
• Parallel column hooks do not depend on callback arrival order.
• Full adapters return true only after handling the complete request.
• The old replacement, delegate-removal, and transpiler code is removed from the active path.
• A clean generated world, an existing world, and the consumer's own regression cases have been checked.
• The migration result is reported as a consumer-specific runtime result, not as library seam coverage.