API Reference

Full reference for the public Heartwood C# API. Source of truth: heartwood/API/ in the vs_mods repository.

IHeartwoodAPI

Main interface returned by HeartwoodModSystem.API.

public interface IHeartwoodAPI
{
    IAddonHandle RegisterAddon(AddonDescriptor descriptor);
    IHeartwoodEventBus Events { get; }
    IReadOnlyList<EcoEntityRecord> QueryEntities(BlockPos center, int radiusBlocks);
    RegionPopulationSnapshot QueryPopulation(BlockPos pos);
}

IAddonHandle

Returned by RegisterAddon(). Used to register species and query ecosystem state.

public interface IAddonHandle
{
    void RegisterSpecies(SpeciesDescriptor descriptor);
    void RegisterSpawnRule(SpawnRuleDescriptor descriptor);
}

IHeartwoodEventBus

Subscribe to ecosystem events.

public interface IHeartwoodEventBus
{
    event Action OnConnected;
    event Action OnDisconnected;
    event Action<EcoEntityRecord> OnEntitySpawned;
    event Action<string> OnEntityDespawned; // uuid
}

AddonDescriptor

public class AddonDescriptor
{
    public string ModId { get; set; }
    public string DisplayName { get; set; }
    public string Version { get; set; }
}

SimulationTier

public enum SimulationTier
{
    Abstract    = 0, // population only, no entities materialized
    Standard    = 1, // full lifecycle, entities spawn/despawn
    Navigating  = 2, // Standard + home navigation
    Persistent  = 3, // Navigating + individual persistence
}

TrophicLevel

public enum TrophicLevel
{
    Producer    = 0, // plants (future)
    Herbivore   = 1,
    Omnivore    = 2,
    Predator    = 3,
    Apex        = 4,
    Decomposer  = 5,
}