Quickstart: Register Your First Species

This guide walks you through creating a minimal Heartwood addon that registers one species with the ecosystem.

Prerequisites

• A working Vintage Story code mod (.csproj targeting net10.0)
• Heartwood installed and the heartwood.csproj referenced

1. Add the Heartwood reference

In your .csproj, reference Heartwood without bundling its DLLs:

<ItemGroup>
  <ProjectReference Include="../heartwood/heartwood.csproj">
    <Private>false</Private>
  </ProjectReference>
</ItemGroup>

2. Register in StartServerSide()

WARNING

Always register in StartServerSide(), not Start() or AssetsLoaded(). The world isn't loaded yet in earlier phases.

using Heartwood;
using Heartwood.API;

public class MyAddonModSystem : ModSystem
{
    public override double ExecuteOrder() => 0.1; // run after Heartwood (0.05)

    public override void StartServerSide(ICoreServerAPI api)
    {
        var hw = api.ModLoader.GetModSystem<HeartwoodModSystem>();
        if (hw?.API == null)
        {
            api.Logger.Warning("[myaddon] Heartwood not found, skipping registration");
            return;
        }

        var handle = hw.API.RegisterAddon(new AddonDescriptor
        {
            ModId = "myaddon",
            DisplayName = "My Addon"
        });

        handle.RegisterSpecies(new SpeciesDescriptor
        {
            SpeciesId = "myaddon:wolf",
            VsEntityCodes = new[] { "game:wolf-male", "game:wolf-female" },
            Tier = SimulationTier.Standard,
            TrophicLevel = TrophicLevel.Predator,
            BaseCarryingCapacity = 20,
            GrowthRatePerDay = 0.05,
            HabitatAffinities = new Dictionary<string, float>
            {
                { "ColdForest", 1.0f },
                { "TemperateForest", 0.8f },
            }
        });
    }
}

3. Test it

1. Start the Heartwood server: make run-dev
2. Launch VS with your addon
3. Run /heartwood status — should show "Connected"
4. Run /heartwood population — your species should appear

Next steps

• SpeciesDescriptor reference — all configuration fields
• Custom behaviors — add AI tasks and entity behaviors