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.0 through 1.22.7 server environments
Versioned server lifecycle matrix	8 of 8 versions, or 24 of 24 checks, passed
Canonical byte-level worldgen parity	8 of 8 versions, seed 42, byte-identical WGLP streams at the canonical boundaries
Full persisted-save parity	Not claimed: runtime-owned and process-sensitive save state is excluded

The dependency declaration and the completed matrix support the server lifecycle, startup-load, and canonical worldgen-output contracts across the audited range. Full persisted-save equality is a separate contract because raw saves include state that is not stable across processes.

Version matrix

Each row rebuilt WorldgenLib and its parity test project against the selected Vintage Story assemblies, then ran the three headless server scenarios. The same seed-42 run compared two vanilla captures with one WorldgenLib capture using the canonical WGLP stream.

Vintage Story	Build	Server scenarios
1.22.0	passed, 0 warnings and 0 errors	3 of 3
1.22.1	passed, 0 warnings and 0 errors	3 of 3
1.22.2	passed, 0 warnings and 0 errors	3 of 3
1.22.3	passed, 0 warnings and 0 errors	3 of 3
1.22.4	passed, 0 warnings and 0 errors	3 of 3
1.22.5	passed, 0 warnings and 0 errors	3 of 3
1.22.6	passed, 0 warnings and 0 errors	3 of 3
1.22.7	passed, 0 warnings and 0 errors	3 of 3

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 and compare the canonical WGLP output against an unmodified vanilla server; a lifecycle pass is not sufficient for this check.
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.