SimSandbox

About

SimSandbox is an experimental simulation engine inspired by Songs of Syx – an isometric sim game with an incredible agent AI system. Built from scratch to understand the architecture of sim game engines where emergent behavior arises from simple rules.

Currently running agents with basic needs (hunger), an economic system (farmers, food production), resource gathering (trees, stone), and a building construction system. All orchestrated through a custom bitset ECS driven by a deterministic 30 Hz tick loop on a dedicated thread.

Architecture

A key design decision: simulation and rendering on separate threads.

┌──────────────┐   ◄─────   ┌──────────────┐
│ Render Thread│            │ Sim Thread   │
│ (MonoGame)   │ snapshot   │ (30 Hz fixed)│
│ 60-144 Hz    │───────────►│              │
└──────────────┘            └──────────────┘
         ▲                          │
         │ reads                  ┌─┴──────────┐
         └──── snapshot ──────────│ World (ECS)│
                              │  + TileMap   │
                              │  + Pathfinder│
                              └──────────────┘

Key design decisions:

1. Fixed timestep 30 Hz – sim ticks at a constant interval, render runs at its own pace. Communication via double-buffered snapshot – atomic reference swap under a lock, render reads lock-free.

2. Bitset ECS in ~200 lines – zero dependencies. Each component = T[] indexed by entity index + BitArray tracking who has what. Simple to understand, cache-friendly in linear iterations.

3. Generation counter in EntityId – protection against use-after-free when slots are reused.

4. Save versioning from day 1 – first field of the file is int version. Bump version + migration function on every structural change.

5. Components as struct + [MemoryPackable] – zero allocations in the hot loop, automatic binary serialization, value semantics.

What works

• Bitset ECS with generation counters, entity create/destroy, queries with 1-4 components
• Pathfinding system – A* with PriorityQueue<T, P> and corner-cutting prevention, path cache per ECS component
• Procedural map generation – 4 tile types (Grass/Floor/Wall/Door), random rect + flood-fill validation
• Building and construction system – home 4×4, storage 6×6, farm 4×4, build ordering and auto-place
• Agent AI – spawned in homes (2/home), wander with 70% home bias / 30% random map exploration
• Hunger and economy FSM – Idle → GoingToStorage → Eating → ReturningHome; farmers produce food (GoingToWork → Working → DeliveringFood), Hunger interrupts as needed
• Capacity-limited storage – 50/100 starting, consumption per Eating, transport by farmer
• Visuals – 16×16 pixel-art sprites, red dot over hungry agents, HUD with food bars and stats
• Versioned save/load – MemoryPack binary format, 5 versions, fail-fast on older saves

What’s missing

• Multithreaded sim (AI phase still single-threaded)
• Flow fields, hierarchical pathfinding
• Sleep, thirst, fun – hunger only for now
• Game over through starvation (next phase scope)
• Builder mode / pause / speed control / bitmap UI
• Multi-step production chains (wood, stone, etc.)

Tech Stack

• .NET 8 + MonoGame 3.8
• MemoryPack – fast binary serialization via source generators
• Custom bitset ECS – ~200 lines, zero dependencies
• A* with .NET 6+ PriorityQueue + path cache in ECS component
• Pixel-art through MGCB content pipeline
• IM-GUI – lightweight custom HUD implementation

Next steps

• Multithreaded AI phase – Parallel.For on agent slices, lock-collect-apply pattern
• Flow fields – BFS from storage, gradient per tile, O(N) instead of A* per agent
• Utility AI – scoring Need.Hunger² + Need.Thirst + Need.Fun, emergent behavior for free
• Resource system – trees, stone, production chains (wood → building → more farmers)

Why I’m doing this

Songs of Syx is one of the best simulation games ever made, and its source code was never published. I wanted to understand how the author built that system – because simple rules + many agents = magic. SimSandbox is my way of getting closer to that understanding.