Soul_Game/docs/DESIGN.md

# 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)

<!-- TODO: direction needs confirming — originally stated as "west" but the
     materialist town already holds west. -->

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.