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)

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.