WorldSim Engine

An Agentic World-Building Simulation Engine based on a Clockwork Emergence model: deterministic, causal, inspectable, and replayable. Complexity emerges from local agent decisions, constrained information flow, physical movement, markets, factions, and resource scarcity.

Development Stack

• Language: C#
• Runtime: .NET 8+
• Architecture: Hybrid object-oriented domain model (with future migration path for hot paths to ECS/data-oriented storage).
• Serialization: JSON first, MessagePack optional later.
• Milestone 6 rule UI: JSON-authored safe rule IR is the source of truth; the Blueprint Desk now includes deterministic read-only visual block mapping for supported rules, not full node-and-wire editing.

Core Architectural Principles

Determinism

The simulation produces the same output given the same:

• Seed
• Scenario definition
• Rule definition
• Simulation version
• Input event stream

It avoids nondeterministic behavior by using ordered collections, explicit sorted iteration, and strong deterministic tie-breakers (e.g., primary score desc, submission tick asc, entity id asc). Randomness is restricted to seeded world generation and non-core flavor variation.

Strong Typed IDs

Instead of raw integers or strings, strong typed IDs are used throughout the domain model (e.g., AgentId, NodeId, EdgeId, etc.) to guarantee type safety and stable ordering.

Inspectability and Replayability

Every important decision made by agents is logged and replayable, supporting explainable systems without agent omniscience.

Getting Started

Prerequisites

• .NET 8 SDK or later.

Building and Testing

To build the project:

dotnet build WorldSim.slnx

To run the unit tests:

dotnet test WorldSim.slnx

Project Structure

• WorldSim.Engine: The core simulation engine logic, including deterministic time simulation, strong typed IDs, pathfinding, utility scoring, and agent behaviors.
• WorldSim.Engine.Tests: Unit tests verifying determinism, movement, economy interactions, and utility logic.

Development Roadmap

Milestone	Description	Status
Milestone 1: Deterministic Toy World	Tick loop, nodes, edges, agent movement, basic utility scoring, one resource/need.	Completed
Milestone 2: Physical Roads and Congestion	Edge occupancy, travel progress, max capacity, waiting, and rerouting.	Completed
Milestone 3: Local Knowledge and Rumors	Perception limits, memory records, confidence decay, and rumor sharing.	Completed
Milestone 4: Markets and Scarcity	Bids, asks, price discovery, production, consumption, resource sinks.	In Progress
Milestone 5: Factions and Directives	Faction identity, overlay graph, abstract resources, utility modifiers.	Not Started
Milestone 6: User Rules and Visual Logic	Safe rule IR, JSON-authored rules, deterministic visual block mapping; Roslyn-backed validation and full visual editing remain future work.	In Progress
Milestone 7: Debugging and Replay Tooling	Thought logs, CSV/JSON export, replay files, visual overlays.	Not Started