# Soul World Sim — MVP

Godot 4.7 (.NET / C#) world simulation for the soul reincarnation game.

- **Design rationale**: [docs/DESIGN.md](docs/DESIGN.md) (the *why*)
- **Production spec**: [docs/SPEC.md](docs/SPEC.md) (the *what*, with 2026-07-21 amendments)
- **Experiment log**: [FINDINGS.md](FINDINGS.md) (the four soak runs and what they proved)
- **Mechanics reference**: the Unity POC at `H:\Projects\Game\Game` (separate repo; soul/debris/imprint systems, proven Feb 2026)

## MVP goal

Prove constrained emergence + soul philosophy with one town: 15 nature-souled
NPCs dropped into a 256×256 world with no scripted layout. Success is
behavioral (SPEC §11): no over-harvesting, voluntary cooperation, an organic
community cluster, stable resource bands — then the contrast test (3 selfish
NPCs dropped in) to prove weights alone change the society.

## Structure

| File | Role |
|---|---|
| `scripts/GameManager.cs` | main loop, tick system (1 tick = 1 in-game minute), day/night |
| `scripts/World.cs` | 256×256 grid, resource nodes, sustainable harvest, daily regen |
| `scripts/NPC.cs` | NPC data + 5-state machine (gather/build/trade/rest/socialize) |
| `scripts/SoulProfile.cs` | soul types, behavior weights, **imprint triad** (SPEC §2 amendment) |
| `scripts/Building.cs` | modular, physically-sequential, multi-NPC construction |
| `scripts/TradeSystem.cs` | generous no-currency exchange, imprint consequences |
| `scripts/Visualization.cs` | top-down debug view (designer sees all meters; the player never will) |
| `scripts/SaveSystem.cs` | world-state JSON round-trip (persistence is first-class) |

## Build weeks (SPEC §12)

1. World gen + NPC base + state machine ← *scaffold is here*
2. Building system
3. Trade + soul-imprint-weighted decisions
4. Testing protocol + save round-trip + debug UI