Heartwood

Core ecosystem simulation platform for Vintage Story. Bridges the game to a 24/7 population server that manages persistent wildlife, habitat patches, and cross-mod coordination.

Ecosystem Simulation

Persistent Populations

Wildlife populations are simulated 24/7 by an external Go server using logistic growth models. Animals persist across chunk loads, server restarts, and player sessions.

• Populations grow, decline, and migrate between habitat patches
• Predator-prey dynamics with configurable food webs
• Seasonal presence modifiers per species
• Hunting pressure tracking — overhunting reduces local populations

Habitat Patches

The world is automatically divided into habitat patches based on temperature, rainfall, and vegetation. Species spawn only in habitats that match their ecological niche.

• 16 habitat types from frozen tundra to tropical forest
• Carrying capacity varies by patch size and quality
• Migration corridors connect neighboring patches

Entity Lifecycle

Heartwood manages the full lifecycle of every entity it controls — from spawn to death.

• Entities materialize when chunks load, persist when chunks unload
• UUID-tagged for round-trip identity across sessions
• Spawn suppression — native VS spawning is replaced for managed species
• Age stages, breeding, home establishment, and natural death

Herds, Homes & Settlements

The simulation tracks group behavior, territory, and NPC villages — not just individual entities.

• Herd membership and cohesion managed server-side
• Home/den/nest assignments with establishment and decay
• Settlement data synced for NPC village population modeling

Cross-Mod Platform

Addon Architecture

Heartwood doesn't add any creatures itself. Instead, addon mods register species from other mods (vanilla VS, Critters, MoreAnimals, etc.) with the ecosystem platform.

• Wingspan — registers birds, adds flocking, nesting, birdwatching
• Fauna — registers land animals, adds herding, denning, predator AI
• Settlement — registers NPCs, adds autonomous villages with construction

Any mod author can write their own addon to register species with Heartwood. See the Developer API docs.

Web Dashboard

Built-in web UI at localhost:8080 with real-time visualization.

• Entity map with species color-coding and player tracking
• Habitat patch overlay with population counts
• Population heatmap and migration corridors
• Species registry, event log, and settlement markers
• Optional password authentication for remote access

Commands

Command	Description
/heartwood status	Connection info and tracked entity count
/heartwood population	Population data for your current region
/heartwood spawn-test <code>	Create a test entity (admin only)

Graceful Degradation

If the ecosystem server is unreachable, Vintage Story runs normally with no ecosystem features. When the server comes back, Heartwood reconnects automatically and recovers full state.

Compatibility

Heartwood is a platform mod. It does not add new entities, blocks, or items. Addon mods (Wingspan, Fauna, Settlement) do patch entity behaviors and AI tasks onto existing entities to enable ecosystem features. Works alongside any combination of creature mods.

Requirements

Vintage Story 1.22.0 or newer. Requires the Heartwood ecosystem server running on the same machine.