gRPC Protocol

Channel on localhost:50051. Single .proto source of truth at proto/heartwood/v1/heartwood.proto.

15 RPCs

Connection

RPC	Direction	Description
Handshake	C# → Go	Initial connection: world ID, server info, registered species list
Heartbeat	C# → Go	Every 10s: current game time → Go runs population ticks, returns directives

Chunk Lifecycle

RPC	Direction	Description
ChunkLoaded	C# → Go	Chunk entered player range: send existing VS entities in chunk, receive spawn directives
ChunkUnloaded	C# → Go	Chunk left player range: send final entity states for persistence

Entity Sync

RPC	Direction	Description
SyncEntities	C# → Go	Every 5s: all managed entity positions/states → receive spawn/despawn directives
EntityEvent	C# → Go	Event-driven: entity died, was attacked, etc.

World Data

RPC	Direction	Description
UpdatePlayers	C# → Go	Player positions (used for spawn distance checks)
ExportTerrain	C# → Go	Chunk terrain data for habitat patch building

Queries

RPC	Direction	Description
QueryEntities	C# → Go	Get entities near a position
QueryPopulation	C# → Go	Get population state for a region
QueryTerrain	C# → Go	Get terrain data for a chunk

Climate/Habitat

RPC	Direction	Description
ExportRegionData	C# → Go	Climate data for a region (temperature, rainfall, forest cover)
QueryPatches	C# → Go	Get habitat patches near a position

Settlements

RPC	Direction	Description
SyncSettlements	C# → Go	Settlement data for NPC village population modeling

Streaming

RPC	Direction	Description
EventStream	Go → C# (server-streaming)	Push ecosystem events to connected clients in real time

Reconnect recovery

When the bridge reconnects after a disconnect:

1. Scans all loaded VS entities for heartwood:uuid tags
2. Re-registers found entities with Go
3. Sends immediate full entity sync
4. Re-exports terrain and region data for all loaded chunks
5. Backfills ChunkLoaded for all currently-loaded chunks