Skip to content

Changes in Phase 1 — for developers

designed · Phase 1 · The developer-facing counterpart of the player's What's new. Phase 1 restarts implementation on main against plan iteration 2; the Phase 0 spike (phase-0-mvp) is reference only. Relative to the spike:

Stack

  • .NET 10 LTS. Aspire removed: no AppHost, no ServiceDefaults, no containers. Two processes; scripts/dev.*.
  • No database. JSON saves; the trace's JSONL segments beside them. The vector store is chosen at Phase 5.
  • OpenTelemetry instrumentation kept; no dashboard shipped; the Studio shows timing.

Engine API changes

Area Change Page
ISimulationSystem ComponentQuery removed. Use view.NodesWithComponent; declare components in the manifest. Tick pipeline
TickContext WorldTime (int sim-minutes, engine-owned), PerTick(perDay), Options. Clock
Intent optional Inputs; new SetEdgePropertyIntent. Intents and the resolver
SimulationEvent Id field. Trace records
Option new record: Need, Inputs; IOptionPublisher; BaselineOptions. Option bus
ReadOnlyGraphView now a zero-copy wrapper; Facts(npc), Known(npc, predicate, filter). The graph
Node kinds faction, rule. The graph
knows edges predicates as properties {value, observed_at, provenance}. PerceptionSystem
Trace new: ITraceStore, Explain, History, WhyChanged, TickDigest. Causal trace
SnapshotManager keyframes every 50 ticks + replay instead of a clone per tick. Snapshots
DeterministicMath required for any transcendental call that touches an outcome. Determinism
PlayerActionSystem outside the toggle set; clock guard rails. Player actions

Data and settings

  • Rates stored in sim-time with the unit in the key; string grammar accepted; per-tick literals rejected at load. Data files
  • Settings renamed: DayLengthTicks removed (the clock is ticks_per_day); OutdoorDecayRate → OutdoorEquilibrationPerHour; DecayRate → EquilibrationPerHour; HungerRatePerDay, RegrowPerDay, FuelBurnPerDay.
  • Scenario: factions[] with seeded knowledge; the World node carries ticks_per_day.
  • World schema: depletable attributes require min; salient marks fact-worthy attributes.

Behavioural changes vs the spike

  • DecisionSystem scores nothing; the whole-map food gradient is gone; movement toward food is over known locations to remembered food.
  • Water lives in the vessel (water_carried on the actor was the spike's duplication bug).
  • food_value cannot go negative; eat is meals and bites.
  • DayNightSystem no longer writes world_time.
  • Propagation has no hop cap.

HTTP API

Added GET /worlds/{id}/history/{nodeId} and GET /worlds/{id}/explain/change/{nodeId}/{attr}/{generation}; snapshots/{tick} reconstructs from keyframes. API

Process

Milestones are [Trait("milestone","phase-N")] tests; milestone.yml runs a test filter. One branch per issue (p1/<issue>-<slug>), PR to main with evidence per criterion; new systems inactive by default. Issues #28–#42 on milestone 2.