Architecture Overview

Heartwood is split into three processes that communicate over gRPC and HTTP.

Vintage Story (game process)
  └── Heartwood C# mod (gRPC client)
        │  gRPC on localhost:50051
        ▼
Heartwood Go server (24/7 simulation)
  ├── gRPC service (15 RPCs)
  ├── Population simulation engine
  ├── Entity & region stores
  ├── PostgreSQL persistence (optional)
  └── Web UI server (localhost:8080)
        │  HTTP/SSE
        ▼
Browser (real-time dashboard)

Responsibilities

Go server (source of truth)

• Runs population simulation ticks (every 10s heartbeat)
• Maintains entity store, region data, habitat patches
• Evaluates spawn rules — decides what should exist where
• Returns spawn/despawn directives to the game

C# bridge mod (VS side)

• Sends chunk load/unload events with entity state
• Materializes entities in-game from Go directives
• Syncs entity positions every 5s
• Suppresses native VS spawning for managed species

Key principle: VS entities are ephemeral views of the Go data model. The Go server is always authoritative. If VS and Go disagree about entity state, Go wins on the next sync.

Graceful degradation

All gRPC calls are wrapped in try/catch. If the Go server is unreachable:

• Heartwood logs a warning and marks itself disconnected
• VS runs normally with vanilla spawning
• When the server comes back, Heartwood reconnects on the next heartbeat and performs full state recovery

Sections

• gRPC Protocol — the 15 RPCs, message flow
• Population Simulation — logistic growth, habitat patches, predator-prey
• Entity Lifecycle — materialization, UUID tagging, sync loop