API Reference

API reference

All public types are in the WorldgenLib namespace and are provided by the WorldgenLib.VintageStory assembly.

Availability checks

bool loaded = WorldgenLibAPI.IsLoaded;
WorldgenLibMod? instance = WorldgenLibAPI.Instance;

IsLoaded means the mod instance has been created. Registration still has to happen before the InitWorldGen freeze. A call made before the relevant host exists or after the freeze throws InvalidOperationException.

WorldgenLibAPI

Terrain

RegisterStep0(string modId, double order, BorderTaperHook hook)
RegisterStep2(string modId, double order, BuildOctavesHook hook)
RegisterStep4(string modId, double order, VerticalDistortionHook hook)
RegisterStep5(string modId, double order, WaterSelectHook hook)
RegisterStep7(string modId, double order, ThresholdHook hook)
RegisterStep10(string modId, double order, PostPlacementHook hook)
RegisterTerrainFinalize(string modId, double order, TerrainFinalizeHook hook)
RegisterFullTerrainGeneration(string modId, double order, TerrainGenerationHook hook)

See Terrain-Hooks for timing and context fields.

Maps

RegisterMapsGeoprovince(string modId, double order, MapsStepHook hook)
RegisterMapsClimate(string modId, double order, MapsStepHook hook)
RegisterMapsForest(string modId, double order, MapsStepHook hook)
RegisterMapsUpheavel(string modId, double order, MapsStepHook hook)
RegisterMapsOcean(string modId, double order, MapsStepHook hook)
RegisterMapsBeach(string modId, double order, MapsStepHook hook)
RegisterMapsShrub(string modId, double order, MapsStepHook hook)
RegisterMapsBiome(string modId, double order, MapsStepHook hook)
RegisterMapsLandform(string modId, double order, MapsStepHook hook)
RegisterMapsRegionFinalize(string modId, double order, RegionFinalizeHook hook)
RegisterMapGenerator(MapGeneratorStep step, string modId, double order, MapGeneratorHook hook)
RegisterMapPadding(string modId, double order, MapPaddingHook hook)
RegisterFullMapRegionGeneration(string modId, double order, MapRegionGenerationHook hook)
MapLayerBase GetMapGenerator(MapGeneratorStep step)

Map force requests are also available:

ForceLandformAt(ForceLandform landform)
ForceClimateAt(ForceClimate climate)
RequireLandAt(int mapX, int mapZ)
ForceRandomLandArea(int positionX, int positionZ, int radius)

See Map-Hooks for map-stage behavior.

BlockLayers

RegisterBlockLayersRaiseModifier(
    string modId,
    double order,
    Func<int, int, float, IMapChunk, float> modifier)

RegisterBlockLayersSeaLevelFilter(
    string modId,
    double order,
    Func<int, int, IMapChunk, bool> filter)

RegisterFullBlockLayersGeneration(
    string modId,
    double order,
    BlockLayersGenerationHook hook)

See BlockLayers-and-PostProcess.

Post-process

RegisterPostProcessOptOut(
    string modId,
    double order,
    GenTerraPostProcessHost.ChunkPostProcessHook hook)

RegisterCleanupRule(
    string modId,
    double order,
    GenTerraPostProcessHost.CleanupRuleHook hook)

Diagnostics and noise

IReadOnlyList<(string Step, double Order, string ModId)> GetHookReport()
StepRegistry GetStepRegistry()

NewNormalizedSimplexFractalNoise TerrainNoise { get; }
SimplexNoise Distort2dX { get; }
SimplexNoise Distort2dZ { get; }
NormalizedSimplexNoise GeoUpheavalNoise { get; }
float NoiseScale { get; }
int TerrainGenOctaves { get; }

The noise properties are available after world-generation initialization. They expose the active canonical noise instances. Prefer TerrainSampler for a terrain query and avoid depending on engine internals unless a migration requires them.

OrderBands

Orders are per step. The built-in constants are:

Constant	Value	Intended use
BeforeVanillaMin	-100	Lower bound for input rewrites
BeforeVanillaMax	-1	Upper bound before the canonical pass
Vanilla	0	Reserved for the canonical pass
AfterVanillaMin	1	Lower bound for normal effects
AfterVanillaMax	100	Upper bound for normal effects
FinalOverrideMin	1000	Last-word complete replacements

Recommended offsets for the analyzed consumers are in Ordering-and-Composition.

StepId

Stable string IDs are useful for diagnostics and future remapping:

ID	Meaning
terra:step0-border-taper	Border taper preparation
terra:step2-build-octaves	Landform weights and terrain octaves
terra:step4-v-distortion	Vertical distortion
terra:step5-water-select	Water block selection
terra:step7-threshold	Per-voxel threshold
terra:step10-post-place	Post-placement column work
terra:terrain-finalize	Once after all terrain columns
maps:geoprovince through maps:landform	The nine map stages
maps:region-finalize	Once after all maps
postprocess:cleanup-floating	Floating-node cleanup
blocklayers:raise-modifier	Final terrain raise
blocklayers:sea-level-filter	Sea-level-rise decision

StepRegistry.CurrentVersion is 2 and the current implementation reports 25 registered steps, including documentation-only internal terrain steps.