Developer API Overview

Heartwood is a platform mod — it provides the simulation infrastructure, but it doesn't add any creatures itself. Addon mods like Wingspan, Fauna, and Settlement are thin adapter layers that register creatures from other mods (vanilla VS, Critters, MoreAnimals, etc.) with the Heartwood platform.

This means:

• You don't need to create entities or assets — just register existing ones
• Any mod author can write an addon to bring their creatures into the ecosystem
• Heartwood stays compatible with any creature mod

Addon Architecture

Creature source mods:       VS Vanilla, Critters, MoreAnimals, ...
                            (provide entities, models, textures, drops)
                                         │
Your addon (adapter layer):              │
  └── Registers species                  │
  └── Adds new AI tasks/behaviors        │
                                         │
Heartwood (core bridge)    — gRPC bridge, chunk lifecycle, entity sync

Key interfaces

Interface	Location	Purpose
IHeartwoodAPI	heartwood/API/IHeartwoodAPI.cs	Main entry point
IAddonHandle	heartwood/API/IAddonHandle.cs	Returned by RegisterAddon()
SpeciesDescriptor	heartwood/API/SpeciesDescriptor.cs	Species configuration
IHeartwoodEventBus	heartwood/API/IHeartwoodEventBus.cs	Event subscriptions

Getting the API

In your mod's StartServerSide():

var hw = api.ModLoader.GetModSystem<HeartwoodModSystem>();
if (hw?.API == null) return; // Heartwood not installed — graceful skip

→ Quickstart: Register your first species