From 0ba5341f0e4eb125c7a236c72a995ea6b4361afe Mon Sep 17 00:00:00 2001 From: Mike McGhen Date: Tue, 21 Jul 2026 12:58:32 -0400 Subject: [PATCH] Move design docs into the repo (docs/DESIGN.md, docs/SPEC.md) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The why-document and production spec now live and version alongside the code they govern, instead of loose in the Unity POC folder — which is how the original design docs got lost. Co-Authored-By: Claude Fable 5 --- README.md | 9 +- docs/DESIGN.md | 589 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/SPEC.md | 269 ++++++++++++++++++++++ 3 files changed, 863 insertions(+), 4 deletions(-) create mode 100644 docs/DESIGN.md create mode 100644 docs/SPEC.md diff --git a/README.md b/README.md index 78b650b..7dcb715 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # Soul World Sim — MVP -Godot 4.6 (.NET / C#) world simulation for the soul reincarnation game. +Godot 4.7 (.NET / C#) world simulation for the soul reincarnation game. -- **Design rationale**: `H:\Projects\Game\Game\DESIGN.md` (the *why*) -- **Production spec**: `H:\Projects\Game\Game\SPEC.md` (the *what*, with 2026-07-21 amendments) -- **Mechanics reference**: the Unity POC at `H:\Projects\Game\Game` (soul/debris/imprint systems, proven Feb 2026) +- **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 diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..9011476 --- /dev/null +++ b/docs/DESIGN.md @@ -0,0 +1,589 @@ +# Soul Game — Design Document (Reconstructed) + +> Reconstructed July 2026 from the code, code comments, and git history of the +> February 2026 proof of concept, plus the world design re-stated from memory +> in July 2026 (marked as such). The original planning documents were lost. +> +> **Companion document**: `SPEC.md` in this folder (July 21, 2026) — the production spec: +> engine choice, constrained-emergence NPC philosophy, materials/building/ +> transport systems, MVP scope (South town world-sim), and phased roadmap. +> This file is the *why*; SPEC.md is the *what to build first*. + +--- + +## Premise + +A game about the impact of souls on the world — and the world's impact back on them. + +The player is a soul that lives, dies, and reincarnates in a small mountain town. +The soul itself never changes and is never harmed. What changes is what layers +over it: **debris**, accumulated through how the soul regards itself, how it +regards others, and how others perceive it. The thicker the layers, the less of +the soul's light reaches the world. + +There is no HUD, no morality meter, no labels. The player discovers every rule +by living with its consequences across multiple lives. + +--- + +## The Soul + +The soul is **a radiating source with gravitational mass**. It is invariant: +a stable `SoulId` persists across every reincarnation, along with a count of +lives completed. + +Debris accumulates from three sources: + +| Source | Direction | What it is | +|---|---|---| +| **Self-regard** | internal | contempt, fear, shame, inflation — how the soul sees itself | +| **Others-regard** | internal | treating people as resources, extractive attention, blindness to others' personhood | +| **External perception** | external (partly outside the soul's control) | distorted perception from heavily-layered souls landing on this soul's atmosphere | + +Key decisions: + +- **Debris does not corrupt the soul. It layers over it.** At total encasement + the soul beneath is unchanged — its light is just unreachable from outside. +- Total debris is the average of the three sources; **radiation strength** is + its inverse, and determines how strongly the soul imprints on the world. +- Debris exists as discrete **pieces**, each with a weight (0–1) recording how + structurally embedded it is. Weight comes from how long it was held, how + load-bearing it became, and how deliberately it was built — repeated harm + weighs more than thoughtless harm. + +## Death and Reincarnation + +Death is the hinge of the whole game. The soul does not die — only the body does. + +- **Light debris (weight < 0.5) clears at death. Heavy debris carries forward.** + The player discovers this by watching what survives reincarnation. +- The body resets to fresh living tissue; the player respawns; `LivesCompleted` + increments. The soul is unchanged at either extreme. +- The soul saves to disk after death processing (not before), so reincarnation + has cross-session weight. The next life starts with exactly what survived. +- Death comes from old age, driven by world time (~30 in-game days for the + player in the POC). R key is an editor-only test trigger. +- **Life length is deliberately not nailed down** — the POC's 30 days / + 2-minute days are prototype values only, not a design decision. + +## The Feedback Circuit + +The central mechanic — the "impact of souls" — is a closed loop run by the +`SoulFieldSystem`: + +``` +Souls imprint on objects → objects carry the field forward → +objects press on nearby souls → those souls imprint differently. +``` + +- **Passive imprinting**: souls constantly imprint on objects within their field + radius (~3 units), low intensity, requiring minimum sustained proximity. + Strength falls off with distance. Clear souls leave positive contributions; + debried souls leave negative ones. +- **Deliberate imprinting**: intentional engagement (the E key, or NPC + interactions) imprints much more strongly. **Intentionality is the + multiplier** — the weight is in the act, not in which button was pressed. + Moral weight lives in the soul's debris state at the moment of contact. +- **Objects press back**: an object's accumulated net field nudges nearby souls' + external-perception debris — positive fields ease it down, negative fields + press it up. Being surrounded by clear-soul objects makes it slightly easier + to radiate. +- **Souls press on each other**: two souls in proximity exert atmospheric + pressure both directions simultaneously; the net effect depends on their + relative debris states. Being near someone who radiates clearly makes it + easier for others to radiate too. +- **The civilizational field is emergent, not zoned.** A place's character is + the sum of what its objects carry. There is no separate regional field value. + +### Moral consequence rules + +- **Darkening another person generates others-regard debris** in the initiator, + proportional to the harm — "the act of darkening someone deepens the + blindness that caused it." This is the only debris that can become heavy + through a single deliberate act. +- **Self-regard debris fires on knowing engagement with harm**: engaging with a + negative field while already significantly compromised (total debris > 0.3 — + below that, the soul may genuinely not know) marks the soul internally. + Same rules for player and NPCs. +- **Harm is easier than healing — by design.** A positive object field can + displace the lightest external-perception piece from a soul's history, but + clearing force is deliberately weaker than accumulation. And only + external-perception debris clears this way: *what the external world put + there, the external world can take back*. Self-regard and others-regard + debris require different, deeper forces of matching specificity — removal + demands an equal and opposite force of the same type. +- Receiving contact presses back at **half strength** — receiving is less + forceful than initiating. + +--- + +## The World Schema + +Every entity in the world — objects, organic matter, spaces, people — carries +the same schema. **No entity is exempt.** + +1. **Composition** — material layers (a knife: iron core → wooden handle → + leather wrap), state (intact/worn/broken/alive/decomposing/…), and structure + (hollow, open, capacity, portable) — the perceptually obvious facts any + observer can read without knowing what the object "is for." +2. **Time** — age in days plus a history of significant events (created, + broken, repaired, changed hands, sustained use). +3. **Soul field** — the layered record of every soul that had sustained contact + with it, oldest imprint deepest, summed into a net field strength. + +### Capability is computed, not stored + +What a thing can do follows from what it is made of, its state, and its +surroundings — dry wood is combustible, a hollow open low-porosity vessel holds +liquid, the same object in different environments has different capabilities. + +### Perception is gated by knowledge + +Capability being physically present is not enough — **the observer must have +encountered enough of the world to perceive it as available.** Knowledge has +two layers: + +- *Known capabilities* — which possibilities the observer can perceive at all. +- *Capability→need meaning* — which of those the observer has personally + connected to their own needs ("I know hollow things hold liquid, and I know + that helps with water"). **The object never tells the observer what it is. + The observer assigns meaning through experience.** Two observers can assign + different meanings. Meaning is learned — through community knowledge at + birth, direct discovery, or watching others. + +--- + +## NPCs — People, Not Systems + +An NPC is a person: a soul in a body moving through the world, running the +**same soul rules as the player** — same imprinting, same debris accumulation, +same interaction logic as the player's E key. + +### Needs drive everything + +Three needs — rest, water, nourishment — deplete over time. An urgent need +overrides everything and pulls the NPC to the nearest source. + +**Soul debris makes life physically harder**: depletion scales up with total +debris (a burdened soul wears faster) and restoration scales down (the same +well gives less to a burdened soul). + +### Roles emerge; they are not assigned + +An early design had waypoint routes and named roles. This was deliberately +removed: when no need is urgent, NPCs simply seek the nearest soul or entity +and engage with it. *Where they end up, what they return to, who they +consistently encounter — that is who they become. A person who ends up near +the well becomes someone who tends the well. The role follows from the life, +not the other way around.* Only intrinsic qualities distinguish NPCs: soul +state, pace, and how long they linger. + +### Discovery and social learning + +Finding a need source is three-phase: (1) community-known sources everyone +grew up with (the well, the stalls, the houses); (2) if those fail, +alternatives scored from personal knowledge; (3) genuine experiment — try the +hollow open thing, record the failure or learn from the success. Successful +discoveries are broadcast to nearby observers; NPCs also pick up **social +cues** ("someone was here for a reason") by watching each other, and failed +experiments aren't repeated for a while. + +### Memory — echoes, not recognition + +NPCs carry **emotional echoes** of past interactions, keyed to the player's +SoulId — so they survive the player's reincarnations even though the body +changes. *The NPC does not know who the player is or was. What persists is a +felt warmth or coldness they cannot explain.* Echoes fade very slowly; a +single interaction doesn't define a relationship, but consistent behavior +across encounters does. The expression is behavioral only: a warm echo makes +an NPC linger up to twice as long with the player; a cold one makes them +leave up to twice as soon. No label, no announcement — **the dwell time is +the whole expression.** + +### Mortality + +NPCs age and die on their own schedules. When one dies, a flat stone grave +marker is left where they fell — a physical trace that persists. + +--- + +## Time and Daily Rhythm + +A world clock drives everything: configurable real-seconds-per-day, days → +seasons → years, and entity/body aging on each day tick. The day has three +phases that shape town life: + +- **Morning (0–7)** — everyone pulls toward home; brief stops. +- **Day (7–18)** — full need-driven behavior. +- **Evening (18–24)** — everyone drifts to the communal gathering point by the + market. + +--- + +## The Player Experience + +- **One interaction key (E), no UI, no labels.** Pressing E near an entity + imprints the soul on it and lets the entity's field press back. Near an NPC, + E prioritizes the person — soul-to-soul deliberate contact. +- **The camera is the only "meter."** Alignment distance drifts very slowly + with total debris — a clear soul's camera closes in; an encased soul's + camera pulls back. *The change is felt across lives, not within a frame.* +- **F toggles first-person task focus.** Originally automatic (camera pulled + in after interactions), changed to player-controlled because *the game + cannot reliably know when the player wants first-person detail.* +- WASD + mouse look, third-person follow camera, R (editor) = test death. + +--- + +## The World — Four Towns + +> This section is the world design as re-stated from memory in July 2026. +> It extends beyond what the POC implements. + +### The reincarnation loop, at world scale + +Every time the player dies they come back, and **no ordinary NPC remembers +them** — recognition dies with the body. But **their actions carry beyond +their life**: + +- **Structures the player helps build persist in the world** across lives. + The world is the player's real save file. +- **NPCs hold memories of past versions of the player based on their + impact** — not who they were, but what they did. (In the POC this exists + as warmth echoes keyed to the SoulId: a felt warmth or coldness the NPC + cannot explain.) + +Rules of rebirth: + +- **Rebirth location is a random point in the world.** The player does not + choose it, and it is not steered by their soul state. Over many lives, + randomness alone guarantees the player encounters all four towns and the + blended spaces between them. +- **The player chooses nothing at rebirth.** +- **Residual soul carries over** — something left of the soul that + transcends the past life, beyond the heavy-debris carryover. +- The player is not reborn as a baby (that would eat up too much play + time), but the world still perceives their age — see Reincarnators below. + +### Reincarnators — the old world + +The player is a **reincarnator**: a soul that **remembers its lives**. This +is what makes them different — not power, but continuity of memory. + +- **The player is not the only one.** Other reincarnators exist in the + world. +- Reincarnators are viewed as **the old world** — beings from a time when + consciousness was tied to energy rather than physical form. +- The player skips childhood on rebirth, but **NPCs view and respect their + age** — the world perceives the age of the soul, not the body. An old + soul is treated as old, whatever it looks like. +- Ordinary NPCs still never recognize the player across lives; only impact + echoes persist for them. + +### Soul recognition — "who you were, not who you are" + +Some ordinary people — unaware the player is a reincarnator, unable to +explain what they're sensing — **recognize the player's soul**. They do +not know who the player was in a past life. But **they can tell who the +player *was*** — the character of the person, not the identity. A felt +familiarity with the shape of a soul. + +- This sensitivity **stems mostly from the northern town** — a culture + that keeps shrines to generational soul objects has spent generations + practicing the reading of imprints. Attunement to souls is their + inherited craft, even if they'd never name it that. +- Distinct from reincarnator recognition (which is knowing) and from + impact echoes (which are feeling): this is *perceiving* — a north-trained + person meeting a returned soul senses "you were someone gentle" or "you + were someone to be careful of," with no idea why. +- Design rule for dialogue and behavior: these people respond to the + player's *past* nature, never their past identity. No names, no events, + no "you're the one who…" — only character. + +### Residual soul — impact dictates rebirth + +> Working direction (July 2026): neither carried clarity nor accumulating +> essence — **the impact your soul had on the world dictates the amount of +> soul you are reborn with.** + +The world is the arbiter of the soul itself. A life's impact is measured by +the world's own ledger — imprints left, structures raised, lives touched — +and the next life begins with soul in proportion. + +Decided: **it is both — the nature of your soul and the impact it had on +the world** together dictate what you are reborn with. Significance and +clarity are still two readable axes, but neither alone is the verdict: + +- **Impact on the world** = how much you mattered (significance). +- **The nature of the soul** = how you mattered (clarity/debris). A tyrant + is reborn vast and heavy; a kind soul who touched nothing is reborn + clear but faint — and the fullest rebirth belongs to a soul that was + both clear and consequential. + +This is what the graves already say — tended (positive impact), run down +(negative impact), *overgrown* (none). The overgrown grave is the saddest: +the world's punishment for an unlived life is that there is less of you +next time. + +Implications to design deliberately: + +- **Stakes and endings**: if soul can shrink toward zero, a soul that stops + mattering may eventually fade into the world rather than return to it — + and a soul of immense accumulated impact may transcend the loop. Whether + fading is a fail state or a bittersweet ending, and whether transcendence + is the game's end, is the largest open question in the design. +- **Flywheel risk**: if amount of soul scales presence (field radius, + imprint strength), influence compounds and faint souls may struggle to + ever matter. Likely mitigation: judge impact *relative to soul size*, so + a faint soul moving one person is weighed as generously as a vast soul + moving a town. +- **Respect is presence, not seniority**: what NPCs perceive in a + reincarnator is amount of soul. An ancient soul who squandered ten lives + commands little. East-town fakers are specifically faking presence. + +### Reincarnator archetypes (per SPEC.md — post-MVP) + +Fellow reincarnators **do** recognize souls across lives — resolved. Three +archetypes: + +- **Positive reincarnators** — recognize souls, use that insight to help + the world grow. +- **Selfish reincarnators** — recognize souls, exploit that insight for + personal gain. +- **Unaware sensitives** — ordinary NPCs who feel a soul's familiarity + without consciously recognizing what they're perceiving: *"I don't know + where I've met you before, but I know that I have."* (This confirms the + "cannot explain" reading of soul recognition; the north-town framing — + a culture whose traditions preserve a folk explanation — remains a + flavor layer on top.) + +Open questions still standing: + +- How each town's culture treats a visibly old soul (reverence, courtship, + imitation, simple acceptance) — a natural axis of town differentiation. +- Fading vs. transcendence as ending states (see above). + +The world begins set off with four main areas, each a civilizational field +made concrete — the emergent sum of what its people's souls have imprinted +on its objects, homes, and land over generations. + +### North — the generational town (positive) + +Based in a positive respect for generations. Older generations help the +younger and pass on knowledge, strengthening the community; younger +generations help the older out of the kindness that was shown to them — +reciprocity running on gratitude, not obligation. + +- Homes may keep **shrines to soul objects** — objects imprinted across + generations of clear souls (the SoulField imprint stack made sacred). +- **Personality shows within the home rather than being displayed on the + outside.** What matters here is interior, not performed. + +### West — the materialist town (negative) + +People are more connected to material objects than to community. A sense of +greed and gluttony that **isn't loud when the player first steps into town** +— it shows over time, as the player watches the townspeople's priorities. + +- Houses **show personality on the outside while being almost identical on + the inside** — the inversion of the north town. What matters is the + perception of material wealth, not the life inside. +- People do things for some small margin of return, whether they are aware + of it or not. + +### South — the nature town (positive) + +Connected with the world around them. They take only what they need from the +land and are rewarded by nature for it. A mutual respect for all living +things, shown equally in how they treat neighbors and wildlife. + +- **No animal is scared of people, because they have nothing to be scared + of.** The townspeople have a strong relationship with the animals. +- Relationships with the outside world grow organically — trade routes are + set up only where necessary, and are never the focus. +- **Almost no currency circulates.** An unsung pay-it-forward system helps + the world around the town grow. +- This is where flora and fauna are most abundant — the land itself is the + town's positive field made visible. + +### East — the selfish town (negative) + + + +Focused entirely on self-gain. At first it may appear that townspeople do +things for others out of the kindness of their heart, but **there is always +an ulterior motive**. People lie and deceive — and because everyone here +does it, it is so normal that no one bats an eye. + +- People **rise into power almost overnight**: they have been scheming and + plotting so long that once the plan comes together, no one can stop them. +- Once in power, they manipulate others for personal gain — false promises, + going back on their word. +- **Key nuance (from SPEC.md): this is not oppression that people resent.** + Everyone in the east operates by the same rule, so no one feels wronged — + the system is stable because it is mutually, openly selfish. Personal + gain carries no guilt here. +- Relationships are structured to trap: contracts and employment built for + ongoing obligation and dependency. + +### How the towns work mechanically + +The four towns are the four corners of the debris model lived out at +civilizational scale: + +- The two positive towns differ in *where* clarity points: north inward + (community, generations) and south outward (land, living things). +- The two negative towns differ in *how* debris presents: west accumulates + it openly through objects (material attachment — others-regard debris + toward things), east conceals it behind performed kindness (deception — + others-regard debris toward people). +- Both negative towns share the same first impression rule: **the darkness + is never loud on arrival.** It is discovered the same way every system in + this game is discovered — by living there and watching what people + actually do over time. +- Interior/exterior of homes is a readable design language: north hides its + wealth of meaning inside; west performs wealth outside and is hollow + inside. + +### The poles and the return flow + +The four towns are the poles of the world's positive and negative energy. +The flow runs in two phases: + +1. **Outflow** — energy flows from the poles first, blending across the + rest of the world (the geography-as-blend-space idea below). +2. **Return** — as the world evolves, those energies eventually flow back + to the towns that produced them. Over time each pole **organically + becomes its own shadow of the past**: the north's reverence can return + to it as calcified tradition, the south's harmony as insularity, the + west and east reaping the cultures they exported. + +No town is a static backdrop — the poles are subject to the same feedback +circuit as everything else. This is the "no entity is exempt" rule at +civilizational scale: the towns' shadows are not authored, they are earned +by the simulation over time, shaped in part by what the player's lives +contributed to the flow. + +### Design hypothesis — geography as a blend space + +> Status: hypothesis, suggested by the mountain town's culture following +> its map position; the outflow phase above is its mechanism. + +If a settlement's character follows from where it sits between the four +corner towns, then geography itself is a blend space: any place in the +world interpolates between the four fields based on its position. The +mountain town is the first data point — northwest-leaning-north, so mostly +generational with a faint material streak that shows as personality +creeping out of its homes. + +This fits the existing principle that the civilizational field is emergent, +not zoned: the four towns wouldn't be four biomes with borders, but four +poles of a continuous field the player learns to read. It would also give +every future settlement, waypoint, or ruin a free first draft of its +culture — position implies disposition — with authored detail layered on +top where it matters. + +--- + +## The Player Fantasy + +> Direction, still being shaped: whatever energy the player puts into the +> world is how the world rewards them. + +The player is not a special class of being — **they can do everything an +NPC can do**. Live, work, build, form relationships, satisfy needs, grow +old. The frame is a life-RPG in the spirit of Fable (touchstone: the new +Fable, slated for early 2027): a life lived in a reactive world, except +here the reaction runs on the soul simulation rather than scripted +reputation, and the ledger spans many lives instead of one. + +There is no quest log standing in for motivation. The pull is the same as +the systems: a player who keeps playing realizes the results of their +actions — the world mirrors their energy back, and that mirror (graves, +animals, echoes, what their structures became) is the reward and the +consequence. What the hour-to-hour verbs are beyond the NPC verb set is +the open question to develop next. + +--- + +## The Mountain Town — Starting Slice + +### Place in the world + +The mountain town sits **roughly northwest of the center of the world, +leaning more toward north** — and its culture follows its position on the +map. Its people recognize the generational values of the positive town to +the north, but their slight westward lean means they **ever so slightly +value the material world as well**. + +This shows as **personality creeping out of their homes** — not malicious, +not the west town's performed wealth, but noticeable to the trained eye. On +the interior/exterior design language, the mountain town sits between the +north (personality fully inside) and the west (personality fully outside): +a first, gentle hint of the gradient the player will later read across the +whole world. As the starting area, it teaches the player to notice these +things before either extreme is encountered. + +### Layout (as built in the POC) + +A small town with real spatial logic: market at the center, a residential ring +of five houses (A–E), the well by house B, farm to the south, mountains in the +distance, player spawning at the south edge facing north into town. Seven +interactable objects carry entity data; well/stalls/houses are community need +sources; houses are neutral — named A–E, no role labels. + +Five people, distinguished only by soul state, pace, and dwell: + +| | Archetype | Soul state | Movement | Life | +|---|---|---|---|---| +| A | **The Worker** | light debris (0.10/0.10/0.15) | working pace, lingers at each stop | 180 days | +| B | **The Keeper** | most radiant (0.05/0.05/0.08) | gentle, settles long — *the well becomes theirs through repetition, not assignment* | 210 days | +| C | **The Elder** | light-moderate | very slow, lingers longest | 220 days — **starts at day 200; they will die during the player's first life. Their death is the player's first lesson in impermanence.** | +| D | **The Young Restless One** | moderate (0.15/0.15/0.20) | fast, short stops — *covers more ground than anyone, settles at none of it* | 160 days — restlessness wears the body faster | +| E | **The Quiet One** | highest external-perception debris (0.28) — *most aware of how others see them; the ache is present* | medium pace | 190 days | + +--- + +## Design Principles (as practiced in the POC) + +1. The soul is never the thing that changes — only its covering. +2. No labels, no meters, no tutorializing. Systems are discovered by living + with them; the reveal is in what survives death. **Never labeled, always + expressed**: the world interprets the player's life in its own way and + answers through itself — + - Southern animals, unafraid by nature, grow easily scared of a player + carrying a negative score. + - The player's grave from a past life is the world's verdict on that + life: tended and cared for if they mattered, left overgrown if they + made no impact, run down if the impact was negative. + - These are readings, not read-outs — the world decides for itself how + to interpret a life. +3. Moral weight lives in the state of the soul at the moment of contact and + in the intentionality of the act — not in which button was pressed. +4. Harm is easier than healing, always and by design. +5. Everything runs the same rules. NPCs are not scripted characters; they are + souls under the same physics of regard. +6. Identity is emergent — for objects (meaning assigned by observers), for + people (roles grown from lived patterns), and for places (fields summed + from objects). +7. Feedback is embodied, not displayed: the camera's distance, an NPC's dwell + time, what a well gives you. + +--- + +## Status (February 2026) + +Unity 6 / URP proof of concept, built Feb 23–26, 2026. Verified working: +the full feedback circuit (imprints accumulate on in-range objects, distant +objects receive none), soul-to-soul pressure, reincarnation with heavy-debris +carryover and disk persistence, the alignment camera, need-driven emergent NPC +behavior with discovery/social learning, NPC memory echoes across player +lives, the daily rhythm, and the mountain town slice (`MountainTownSlice` +scene; `SoulSpreadTest` is the earlier test bench). Scenes are rebuilt by +editor tools: **Tools > Game > Build Mountain Town** / **Build Test Scene**. + +Lost design docs referenced by the git history ("five NPCs whose soul debris +states and routes reflect the design documents") covered at least the NPC +archetypes and the town layout; those decisions survive in +`SceneBootstrapper.cs` and are captured above. diff --git a/docs/SPEC.md b/docs/SPEC.md new file mode 100644 index 0000000..2f1af31 --- /dev/null +++ b/docs/SPEC.md @@ -0,0 +1,269 @@ +# 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