Technical wiki

One page per thing the engine is made of: what it is for, the interfaces it exposes, what it consumes, what consumes it, and which API endpoints surface it. Written for someone who will build on it or change it. The design rationale lives in PLAN.md; these pages point at the sections and say what is.

Status

Phase 1 is designed and being built. Pages are designed · Phase 1 with the issue that builds them; they flip to built as increments land. Numbers and names are the design's; where the code deviates, the plan is fixed first (CLAUDE.md → REDESIGN PROTOCOL), then the page.

The shape of the engine in one paragraph

A universe is one graph: nodes (places, people, things, factions, rules) with typed attributes and component tags, joined by typed edges (contains, connected_to, knows, member_of). Systems are stateless plugins that read a frozen view of that graph each tick and produce intents — proposed changes — which a resolver applies in one batch per phase: deltas sum, sets win by priority, a node has exactly one container. Three phases a tick: Environment (physics), Agency (decisions), Event (reactions). Agency systems publish scored options on a bus and a DecisionSystem that knows nothing about any action arbitrates. The engine owns the clock, keeps a causal trace of every intent, decision and event outside the graph, and can answer why for any of them. Everything is deterministic from a seed. Everything is hot-toggleable except the engine itself.

How it connects

Page	What it shows
The tick	Snapshot → systems → batch → resolve, three times, then the trace.
From perception to Explain this	Perception writes → publishers score → decision arbitrates → action intends → resolver applies → trace records → Explain renders.
Clients, API, engine	Two processes, one API, two routes; what each reads and writes.

Engine

	Page	Issue
	The graph — nodes, edges, attributes, generations, kinds	#28
	Intents and the resolver — intent types, batching, conflict policy, bounds	#28
	Tick pipeline and systems — phases, ISimulationSystem, registry, hot-toggle	#29
	Clock and simulation time — ticks_per_day, world_time, rates with the unit in the key	#29
	Views, snapshots and the ring buffer — the zero-copy view, keyframes + replay	#28, #32
	Option bus — IOptionPublisher, Option, needs, the action registry	#35
	Causal trace — records, queries, storage tiers	#31
	Harness — Harness.Run, the report, milestone tests	#33, #42
	Player actions — queue, PlayerActionSystem, guard rails	#39
	Persistence — tick-atomic JSON saves, the trace's warm store	#32
	Scenarios and templates — data files, variance, the faction node and seeded facts	#32
	Determinism — StableHash, DeterministicMath, digests, the golden test	#30

Systems

Overview · DayNight · Heat · Fire · Growth · Perception · Hunger · Decision · Action · Lifecycle

Reference

API · World vocabulary · Trace records · Data files and the rate grammar · CLI

Changes: Phase 1 · Bridge: Concept index · Start: Getting started