Soul_Game/docs/SPEC.md

# Soul Reincarnation World Simulation — Full Design Spec

## Project Vision
An organic world-building simulation where the player lives multiple lifetimes. Every soul — player and NPC alike — carries a persistent imprint that shapes the world's development. Four founding towns, each built on a distinct human philosophy, seed a world that grows entirely from NPC behavior rather than scripted events. Darkness and light are never art-directed — they emerge from what the inhabitants actually do.

---

## 1. The Four Founding Towns

### 1.1 North — The Generational Town
**Philosophy:** Reverence for lineage. Older generations pass down knowledge; younger generations support elders out of genuine care, not obligation.
- Values: family, inherited wisdom, inherited material wealth
- Material culture: heirlooms and importance kept **inside** the home (private, emotionally weighted) rather than displayed outside
- Knowledge transfer: strong, intentional teaching between generations
- Building style: family compounds that grow additions per generation
- Soul tendency: knowledge/skills absorbed faster from elders; strong intergenerational bonds

### 1.2 West — The Materialistic Town
**Philosophy:** Worth is measured in visible possessions.
- Values: status, display, differentiation from neighbors
- Material culture: wealth shown **outside** the home (opposite of North) — facades, ornamentation, visible property
- Decision-making: choices weighted toward highest material payoff over emotional cost
- Building style: ostentatious, competitive, "keeping up with the neighbors"
- Soul tendency: low emotional attachment to objects, high attachment to status signaling

### 1.3 South — The Nature Town
**Philosophy:** Take only what you need; live in reciprocity with the land.
- Values: sustainability, trust, communal care
- Economy: no currency — pay-it-forward / gift economy, kindness assumed
- Material culture: smaller fields but higher yield because land is cared for; bountiful, untouched-looking landscape as a direct reflection of behavior
- World feedback: flora/fauna respond to the town's harmony — animals trust people, land stays lush
- Soul tendency: generosity, low waste, cooperative default behavior
- **This is the MVP town**

### 1.4 East — The Selfish Town
**Philosophy:** Personal gain above all else, with no guilt attached.
- Values: individual advancement via deception, manipulation, romanticized narratives that mask exploitation
- Key nuance: this is **not** oppression that people resent — everyone in East operates by the same rule, so no one feels wronged; the system is stable because it's mutually, openly selfish
- Contracts/dependency: relationships (e.g. employment) are structured to trap people in ongoing obligation
- Building style: enterprises and personal wealth infrastructure
- Soul tendency: fast accumulation, fast betrayal, high individual mobility at others' expense

---

## 2. Soul Imprint System

Every entity in the world — player, NPC, and eventually inanimate objects — carries a soul imprint that accumulates across a lifetime and persists into the next one.

> **Amendment 2026-07-21:** the imprint is a **triad, not a scalar** — three fields from DESIGN.md's debris model: `self_regard`, `others_regard`, `external_perception` (total = their average; radiance = its inverse). Several settled designs (residual-soul rebirth verdict, the self-regard awareness threshold, "what the world put there the world can take back") depend on the three sources being separable. MVP behavior may read only the total, but the data model carries the triad from day one to avoid a migration later.

- Soul imprint shapes **how** an entity resolves decisions where logic alone doesn't determine an answer (e.g., which of several valid transport carts to use is decided by the emotional/soul history attached to each cart)
- Objects can carry residual imprint from repeated use/interactions (a cart everyone's had bad experiences with becomes "tainted" and is avoided in favor of a neutral/positive one)
- Reincarnation carries the player's (and eventually NPCs') soul forward; some NPCs can sense a familiar soul across lives without understanding why ("I don't know where I've met you before, but I know that I have")

**Reincarnator archetypes** (old-world philosophy holders, post-MVP):
- **Positive reincarnators** — recognize souls, use that insight to help the world grow
- **Selfish reincarnators** — recognize souls, exploit that insight for personal gain
- **Unaware sensitives** — regular NPCs who feel a soul's familiarity without consciously recognizing what they're perceiving

---

## 3. World Feel / Identity (Emergent, not art-directed)

Core design rule: light and dark are **outcomes of systems**, not choices made in an art pass.
- Selfish/materialistic dominance → hierarchy, scarcity, broken trust → world reads darker
- Nature/generational dominance → abundance, equality, trust networks → world reads lighter
- This should be "felt not seen" — driven by systemic conditions (resource distribution, trust state, trade fairness) rather than a lighting/palette toggle
- Aesthetic base: medieval, with a possible modern-hybrid layer to explore later (deprioritized until core systems prove out)

---

## 4. NPC Behavior Philosophy

**Design constraint established through discussion:** full free-form emergent reasoning (NPCs "inventing" novel solutions from scratch, e.g. discovering that firewood can also start a fire with no prior rule for it) is explicitly **out of scope** for now — this is effectively open-ended AI research, not a buildable side-project feature.

**Chosen approach instead: Constrained Emergence**
- The engine defines the possibility space (what methods/tools/materials exist and what they're valid for)
- Soul philosophy decides **which** valid option an NPC picks, not **whether** a solution exists
- Example: heavy-good transport requires a cart; capacity is determined by cargo volume vs. cart size (may require 2 wagons or a bigger one); **which** cart/route is chosen is filtered through soul imprint (avoid a bad-experience cart, prefer a trusted one, etc.)
- This produces behavior that *feels* discovered/organic without requiring true free-form reasoning

**No inventory abstraction:**
- Rejected: abstract "inventory slot" item systems
- Wanted: NPCs interacting with the physical world in a way that reads as real (carrying logs, using ladders, construction that looks physically sequential) — achieved via constrained systems (task states + resource pools + placement rules), not full physics simulation

---

## 5. Knowledge System (Post-MVP, designed now)

**Rejected approach:** knowledge as a physical pick-up-able object in the world.

**Chosen approach: proximity/social diffusion**
- Knowledge spreads fastest near its source (e.g., NPCs near a blacksmith absorb smithing-adjacent knowledge faster)
- Slower diffusion via conversation/social contact outside the source location
- **Not** randomly assigned — inherited/absorbed according to soul philosophy ("genetics" reframed as soul calibration): a soul type determines what knowledge an NPC naturally gravitates toward and how efficiently they absorb it
- Knowledge capacity: each NPC has a capped capacity (randomized per NPC); knowledge types consume different amounts of that capacity; technically-minded soul types spend less capacity on logical/technical knowledge, more on social/organic knowledge, and vice versa
- Explicitly deferred from MVP due to scope (spreading knowledge for "everything from picking up a cup to building a house" was identified as unbounded scope)

---

## 6. Materials & Building System

**Materials (MVP set — deliberately not a full "periodic table"):**
- Wood (from regenerating trees)
- Stone (static deposits)
- Clay (near water)
- Water (unlimited at source tiles)
- Metal (post-MVP: requires ore discovery + smithy, not an "unlock tree" — availability is purely discovery-driven, no artificial gating)

**Building philosophy:**
- Buildings are modular: base structure + composable upgrade slots (loft, stable, extension, reinforcement, etc.)
- Modules are, in principle, infinitely stackable (e.g., an NPC could build 37 stables) but every module costs real resources pulled from the shared world pool — excess ambition creates real scarcity/competition, which is how East-style hoarding naturally produces friction elsewhere
- Material upgrades (wood → stone → metal) happen because an NPC discovered/obtained the material, not because of a tech-tree unlock
- Construction reads as physically sequential (foundation → walls → roof, NPCs pathing to place the "next" component) without simulating true physics

---

## 7. Transport & Logistics (Constrained Emergence example)

- Heavy/bulky goods require a transport method (cart, wagon)
- Capacity is a real constraint: cargo volume vs. vehicle capacity determines whether an NPC needs a bigger wagon or multiple trips/wagons
- **Which** available vehicle/route an NPC chooses is filtered through soul imprint history attached to that object (avoid "tainted" carts, prefer trusted ones)
- This is the reference pattern for how **all** similarly ambiguous "how would they figure that out" problems should be resolved in this system: define the valid option space mechanically, let soul imprint pick among valid options

---

## 8. MVP Scope (Buildable Now)

**Goal:** prove the core loop — constrained-emergent behavior + soul philosophy.
- 1 town only: **South (Nature)** — simplest philosophy, clearest success signal
- 15 NPCs dropped directly into the world (no scripted town layout)
- No hunger/needs system yet
- No animals yet
- No knowledge transfer yet (single soul type, so not yet needed)
- No currency (matches South's actual philosophy anyway)

**MVP Systems:**
1. World generation: grid with wood/stone/clay/water placement
2. NPC data: soul_type (nature only), position, state, inventory, fatigue, health, soul imprint triad (see §2 amendment), personality_modifier
3. State machine: GATHERING, BUILDING, TRADING, RESTING, SOCIALIZING
4. Building system: modular structures, multi-NPC contribution, resource cost, physically-sequential construction
5. Trade system: generous/voluntary exchange, no currency, soul-imprint influenced
6. Resource system: sustainable harvest/regen logic (South never over-takes)
7. Visualization: top-down 2D Godot view + basic debug/stat UI

**Explicitly out of MVP** (deferred, but designed above for continuity):
- Other 3 towns/soul types
- Knowledge diffusion system
- Animals
- Metal/advanced materials
- Reincarnation/player system
- Procedural world/town expansion beyond the seed town

**Key design intent for MVP:** build the underlying systems (world, NPC, state machine, building, trade, resource) as **soul-type-agnostic** as possible, so that adding West/North/East later is primarily a matter of dropping in new soul_type behavior weights — not rebuilding the engine. This is the reason to prototype with one modular system rather than one hardcoded "nature town."

---

## 9. Technical Architecture

**Engine:** Godot 4.x
**Language:** C# (leverages existing C#/.NET background)

**Suggested project structure:**
- `World.cs` — world generation, resource placement, resource pools
- `NPC.cs` — NPC data + state machine
- `SoulProfile.cs` — soul_type behavior weights (generosity, sustainability, community bias, etc.) — designed to be swappable per soul type
- `Building.cs` — building definitions, modular upgrade slots, construction progress
- `TradeSystem.cs` — trade evaluation and execution
- `GameManager.cs` — main loop, tick/day/night time system
- `Visualization.cs` — rendering + debug UI
- `SaveSystem.cs` — world-state serialization to JSON *(Amendment 2026-07-21: added to MVP — "the world is the save file" means persistence cannot be a Phase 4 afterthought; a trivial save/load round-trip keeps the architecture honest from the start)*

**Time system:**
- 1 tick = 1 in-game minute, 1440 ticks = 1 day
- Day/night cycle drives activity bias (gather/build by day, rest/socialize by night)

**Performance target:** 60 FPS with 15 NPCs on MVP map size (256×256 grid)

---

## 10. NPC State Machine (Pseudocode)

Every tick, per NPC:

1. Check fatigue/health → force RESTING if fatigue > 80 or health < 30
2. Scan local radius for resources, NPCs, buildings
3. Evaluate current state and soul-weighted priorities:

**GATHERING**
- If under capacity and resource nearby: move + harvest sustainably (South: cap harvest ~50% of node to avoid depletion)
- If inventory has surplus: → TRADING
- If fatigued: → RESTING

**BUILDING**
- If a building is in progress nearby: contribute materials/labor
- Else if materials available: start a new (communal-first) building
- Else: → SOCIALIZING

**TRADING**
- If a nearby NPC's need matches your surplus: trade (South: generous ratio, no currency), adjust soul_imprint_value upward
- Else: → GATHERING or RESTING

**RESTING**
- Recover fatigue/health; when fatigue < 40 → GATHERING

**SOCIALIZING**
- Build bonds, chance to spontaneously help a nearby NPC, then → GATHERING after N ticks

4. Fatigue delta per state: Gathering/Building +2, Trading +1, Resting −5, Socializing −2
5. Day/night biases which states are preferred

---

## 11. Testing Protocol (MVP)

**Baseline:**
- Single NPC survives a full 24-hour cycle without errors
- 15 NPCs spawn without crash/performance issues
- Building construction completes end-to-end
- Trade executes and updates both parties' inventories correctly

**Behavioral validation (the actual point of the MVP):**
- South NPCs do NOT over-harvest (resource nodes stay healthy over time)
- NPCs voluntarily help each other build
- Sharing emerges without being explicitly scripted per-NPC
- A visible "community" cluster forms organically
- Resource totals stay in a stable band over multiple day cycles

**Stress:**
- 30 continuous in-game day cycles with no crash/drift
- Frame rate holds 60 FPS throughout

**Amendments 2026-07-21:**
- Baseline: save world state to JSON, reload it, and the simulation continues identically (round-trip test).
- Stretch (end of MVP) — **the contrast test**: drop 3 east/selfish-weighted NPCs into the South town and observe friction. If the same engine produces visibly different society from behavior weights alone, the four-town thesis is validated a full phase early. This is the real proof of constrained emergence — a single generous soul type succeeding is partly baked into its weights.

---

## 12. Development Timeline (Part-time side project)

- **Week 1:** World generation + NPC base class + core state machine
- **Week 2:** Building system (modular, multi-NPC contribution)
- **Week 3:** Trade system + soul-imprint-weighted decision logic + polish
- **Week 4:** Testing protocol, bug fixing, UI/debug view

Estimated LOC for MVP: ~2,000–3,000 (C#)
Dependency: Godot 4.x

---

## 13. Roadmap Beyond MVP

**Phase 2 — Soul Diversity:**
- Add West, North, East soul types (behavior weights only, engine unchanged)
- Knowledge diffusion system (proximity/social spread, soul-weighted)
- Basic animal presence (South town trust mechanic)
- Modular building upgrades expanded (loft, stable, extensions, etc.)

**Phase 3 — World Depth:**
- Procedural town/world expansion beyond the four seed towns
- Metal-tier materials (ore discovery + smithy, no tech-tree gating)
- Inter-town trade routes and relationships
- Object-level soul residue (tainted vs. trusted tools/buildings)

**Phase 4 — Player & Reincarnation:**
- Player character integrated into the simulation
- Reincarnation mechanic: player lives multiple lifetimes, soul imprint persists
- Reincarnator NPC archetypes (positive/selfish/unaware-sensitive)
- Full world-state persistence across player lifetimes