Getting Started

Getting started

What you install

WorldgenLib is a server-only Vintage Story code mod.

Setting	Value
Mod ID	worldgenlib
Display name	WorldgenLib
Current product version	0.1.0
Side	Server
Client required	No
Server required	Yes
Declared game dependency	Vintage Story 1.22.0 in the mod metadata

Place the built WorldgenLib mod directory in the server Mods directory. Keep the matching WorldgenLib.VintageStory.dll and modinfo.json together. Consumer mods that use the API must also be installed on the server and must declare their dependency on WorldgenLib through their own mod metadata.

The public repository currently contains documentation while the implementation is being prepared for a public source release. For development, use an artifact built from the matching WorldgenLib revision.

Register a first hook

Consumer registration belongs in StartServerSide. Check that WorldgenLib is loaded before registering. The following hook lowers the terrain threshold near a fixed line:

using Vintagestory.API.Common;
using Vintagestory.API.Server;
using WorldgenLib;

public sealed class MyWorldgenMod : ModSystem
{
    private const string ModId = "my-worldgen-mod";

    public override bool ShouldLoad(EnumAppSide side)
        => side == EnumAppSide.Server;

    public override void StartServerSide(ICoreServerAPI api)
    {
        if (!WorldgenLibAPI.IsLoaded)
        {
            api.Logger.Warning("WorldgenLib is not loaded; world-generation hooks are disabled.");
            return;
        }

        WorldgenLibAPI.RegisterStep7(
            ModId,
            OrderBands.AfterVanillaMin + 20,
            LowerThresholdNearRiver);
    }

    private static double LowerThresholdNearRiver(
        ChunkContext chunk,
        ref ColumnContext column,
        int posY,
        double threshold)
    {
        if (Math.Abs(column.WorldX) > 3 || posY >= chunk.SeaLevel)
            return threshold;

        return threshold - 0.15;
    }
}

The exact delegate signature depends on the step. Read Terrain-Hooks before selecting a hook. A Step 7 hook runs once per voxel threshold, so keep it cheap and side-effect free.

Registration deadline

Registration is open while server mods run their startup methods. WorldgenLib freezes its hook lists at the InitWorldGen boundary. A registration made after that point throws InvalidOperationException. Register landforms and region-map slots during startup as well.

Do not call the public registration methods from a terrain-generation callback. Generation is the execution phase, not the configuration phase.

Build setup for a consumer

A consumer project needs references to the Vintage Story assemblies used by its target installation and a project or binary reference to WorldgenLib.VintageStory. The reference consumer follows this shape:

<ItemGroup>
  <ProjectReference Include="..\WorldgenLib\WorldgenLib.VintageStory.csproj" />
</ItemGroup>

For a released consumer, use the WorldgenLib binary that matches the API version declared by the consumer. Do not copy Vintage Story engine DLLs into the mod output. The game supplies those assemblies at runtime.

Load and failure behavior

WorldgenLib runs on the server. If a required runtime seam is unavailable for the installed Vintage Story build, it disables itself rather than running a partial canonical generator. If an individual consumer hook throws during generation, WorldgenLib logs the failure and disables that consumer's registrations for the rest of the session. The other registrations continue.