Compatibility and Updates

Compatibility and updates

WorldgenLib sits on narrow Vintage Story world-generation seams. The public contract includes the hook signatures, stable step identifiers, lifecycle deadline, context ownership rules, and the behavior when a seam is unavailable.

Current compatibility

Item	Current value
Library version	0.1.0
Mod ID	worldgenlib
Server side	Required
Client side	Not required
Declared game dependency	Vintage Story 1.22.0 in the mod metadata
Development and server evidence	Vintage Story 1.22.7 reference environment
Complete 1.22.0 through 1.22.7 runtime matrix	Still pending

The dependency declaration and a successful run on 1.22.7 do not prove that every intermediate game binary behaves identically. Test each supported binary before publishing a compatibility claim.

Step registry and remapping

StepRegistry exposes stable IDs for diagnostics and version adaptation. The current step-list version is 2, the product version is 0.1.0, and the implementation reports 25 registered IDs across maps, terrain, post-process, and BlockLayers.

StepRegistry registry = WorldgenLibAPI.GetStepRegistry();
string? current = registry.ResolveStepId("terra:step7-threshold");
string report = registry.GetVersionReport();

When a future library version moves a seam, it can add a remap:

registry.AddRemap(
    "terra:old-threshold-step",
    "terra:step7-threshold");

An unknown or removed ID without a remap resolves to null and logs a warning. Consumers should treat that result as a disabled optional feature and report it to the user. Do not assume a numeric step position remains stable across a library update. Use the named API methods and stable IDs in diagnostics.

Runtime seam checks

The BlockLayers raise and sea-level hooks depend on a structural IL seam in the Vintage Story build. WorldgenLib validates that pattern during startup. An unsupported pattern prevents registration of those inline hooks with a clear exception. The terminal full BlockLayers adapter remains a separate option, subject to its own compatibility testing.

Landform integration uses bounded reflection because the relevant vanilla property is internal. Conflict detection also inspects the runtime delegate layout and Harmony patch list. If those required inspection surfaces are missing, detection fails closed for the affected ownership decision instead of silently claiming a clean pipeline.

Conflict behavior

WorldgenLib classifies foreign worldgen changes as advisory or blocking. A blocking takeover of the same canonical pass leaves WorldgenLib's own generation callbacks inactive so two full owners do not write the same request. The startup report records the finding. A foreign patch that does not clearly own the complete pass does not automatically disable every independent hook.

This is a safety boundary, not a general composition proof. Foreign middleware that changes the same vanilla method still needs a compatibility policy and a runtime fixture.

Update checklist

For a Vintage Story or WorldgenLib update:

1. Inspect the new GenMaps, GenTerra, post-process, and BlockLayers method shapes against the supported seams.
2. Run the build and all unit, integration, and server checks.
3. Check the startup report for missing seams, conflicts, and step versions.
4. Run a no-consumer world to compare canonical output.
5. Run each available consumer scenario with a fixed seed.
6. Test a newly created world and a world containing registered region maps.
7. Update the mod dependency, compatibility table, and known limits together.
8. Record any step remap and keep the old ID behavior explicit.

Keep modinfo.json, assembly references, and the documentation on the same version. A build that compiles against a new API is not enough evidence for a worldgen compatibility claim.