diff --git a/ROADMAP.md b/ROADMAP.md index 61e4489..71dddff 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -101,6 +101,9 @@ Recommended views: - [x] Ash Underpass Gate gameplay packet documented for mission state, room-by-room objectives, combat and objective authority boundaries, reward outcomes, UI/audio needs, implementation packets, and evidence requirements. +- [x] The Garden personalization and visible-memory packet documented for + memorial tags, proof objects, notice wall entries, NPC reactions, data + ownership, fixed slots, implementation packets, and monetization guardrails. - [x] Alpha economy, balance, playtest, art, audio, and content direction documented for TIME, SECOND, reward defaults, reinhabitation pressure, playtest success metrics, visual tone, UI color language, audio placeholders, @@ -401,7 +404,8 @@ prototype. selected account/soul progress survives. - [ ] Add the first Garden personalization slice: trophy placement, memorial wall, clinic/rest corner, visitor notes, and NPC reactions, with no - construction timers or pay-to-win furniture. + construction timers or pay-to-win furniture. Track in + [#256](https://github.com/DOS/Second-Spawn/issues/256). - [ ] Build the alpha level blockout from `docs/design/27-alpha-level-design.md`: Central Garden Court, Clinic / Body Hall, Training Lane, Signal Mast, Ash Underpass Apron, diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 052e46e..fb28757 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -53,6 +53,7 @@ - [Dayton Demo Region Design (Historical)](design/49-dayton-demo-region-design.md) - [Dayton Real-Map Slice Design](design/50-dayton-real-map-slice-design.md) - [The Garden Hub Design](design/51-the-garden-hub-design.md) +- [The Garden Personalization and Memory Design](design/55-the-garden-personalization-and-memory-design.md) - [Permanent NPC Story and Characteristics](design/21-permanent-npc-story-characteristics.md) - [Faction Architecture](design/22-faction-architecture.md) diff --git a/docs/design/26-alpha-game-design-document.md b/docs/design/26-alpha-game-design-document.md index 5866ec0..286276f 100644 --- a/docs/design/26-alpha-game-design-document.md +++ b/docs/design/26-alpha-game-design-document.md @@ -25,6 +25,9 @@ Companion execution docs: - [54-ash-underpass-gate-gameplay-design.md](54-ash-underpass-gate-gameplay-design.md) defines the first Gate mission's state machine, rooms, objectives, authority boundaries, rewards, and evidence checklist. +- [55-the-garden-personalization-and-memory-design.md](55-the-garden-personalization-and-memory-design.md) + defines Garden visible memory, memorial tags, proof objects, fixed slots, + NPC reactions, and personalization guardrails. - [30-alpha-ux-flow.md](30-alpha-ux-flow.md) defines the first alpha UX flow from HUD to dialogue, Body Hall, Mission Board, outcome, agent report, and reinhabitation. diff --git a/docs/design/33-alpha-production-backlog.md b/docs/design/33-alpha-production-backlog.md index faf2099..4234768 100644 --- a/docs/design/33-alpha-production-backlog.md +++ b/docs/design/33-alpha-production-backlog.md @@ -119,6 +119,9 @@ Required work: | Signal Mast | Scout Ash Underpass | Reveals clue or reduces expected risk display. | | Memorial Wall | Show body loss concept | Can display placeholder record or empty state. | +Personalization and memory follow +[55-the-garden-personalization-and-memory-design.md](55-the-garden-personalization-and-memory-design.md). + Cut line: - No construction timers unless needed for a smoke of world-simulation time. diff --git a/docs/design/38-alpha-design-decision-register.md b/docs/design/38-alpha-design-decision-register.md index 9589b0f..f1f9e01 100644 --- a/docs/design/38-alpha-design-decision-register.md +++ b/docs/design/38-alpha-design-decision-register.md @@ -143,6 +143,7 @@ When a design question appears during implementation: | `29-alpha-questline-and-encounter-design.md` | First quest and encounter. | | `54-ash-underpass-gate-gameplay-design.md` | Detailed first Gate mission state, room, objective, and evidence contract. | | `30-alpha-ux-flow.md` | Player-facing UX flow. | +| `55-the-garden-personalization-and-memory-design.md` | Garden visible memory, memorial, proof, decor, and NPC reaction guardrails. | | `31-alpha-economy-balance-and-playtest-plan.md` | TIME, SECOND, reward, playtest, and balance. | | `32-alpha-art-audio-and-content-direction.md` | Presentation, UI tone, audio, and content guardrails. | | `33-alpha-production-backlog.md` | Build order and epic backlog. | diff --git a/docs/design/51-the-garden-hub-design.md b/docs/design/51-the-garden-hub-design.md index 7a1329f..7c09126 100644 --- a/docs/design/51-the-garden-hub-design.md +++ b/docs/design/51-the-garden-hub-design.md @@ -23,6 +23,9 @@ without copying a gacha lobby: - the player can inspect, talk, prepare, repair, remember, and decide risk - the hub stays compact enough for a vertical slice +Detailed personalization and visible-memory rules live in +[55-the-garden-personalization-and-memory-design.md](55-the-garden-personalization-and-memory-design.md). + --- ## 2. Identity @@ -330,4 +333,3 @@ Clinic line: ```text Your body is stable enough to stand. Do not confuse that with stable. ``` - diff --git a/docs/design/55-the-garden-personalization-and-memory-design.md b/docs/design/55-the-garden-personalization-and-memory-design.md new file mode 100644 index 0000000..729912b --- /dev/null +++ b/docs/design/55-the-garden-personalization-and-memory-design.md @@ -0,0 +1,413 @@ +# The Garden Personalization and Memory Design + +*Status: Alpha design packet* +*Created: 2026-05-26* +*Source of truth level: Player-facing personalization, memorial, trophy, and +visible-consequence contract for The Garden alpha hub.* + +--- + +## 1. Purpose + +The Garden must not become a static menu room. It should change after Gate +runs, body loss, NPC relationship shifts, and offline-agent activity. + +This document defines the first small personalization and memory slice: + +- what the player can place or inspect +- what changes after mission outcomes +- what NPCs may react to +- what stays cosmetic or light-utility +- what the backend must own +- what Unity can safely show first + +This is not a construction-timer system, not housing monetization, and not a +power-progression layer. + +--- + +## 2. Design Goal + +The alpha goal is simple: + +> The player returns from Ash Underpass and The Garden remembers. + +The player should see at least one of these after a run: + +- a memorial tag appears +- a recovered object is placed +- a notice board line changes +- an NPC comment changes +- a facility status line changes +- an offline-agent report references a safe Garden action + +The player should feel that The Garden belongs to a living roster, not a blank +private base. + +--- + +## 3. Scope + +### Alpha In Scope + +| Feature | Alpha Target | +| ---- | ---- | +| Memorial Rail | Shows body loss, retired bodies, and mission-return tags. | +| Trophy / Proof Shelf | Shows one recovered Ash Underpass proof object. | +| Notice Wall | Shows mission notices and outcome snippets. | +| Clinic Corner | Shows current body injury or stabilization state. | +| Repair Row Marker | Shows one repair/salvage material or readiness state. | +| Visitor Note | One short NPC or offline-agent note after outcome. | +| NPC Reaction Hook | One focus NPC line can reference the visible change. | + +### Alpha Out Of Scope + +- free-form furniture placement +- construction queues +- paid boosts +- player-to-player home visits +- large decor inventory +- edit-mode UI +- collision-heavy props that disrupt navigation +- gacha or loot-box decor +- stat bonuses from furniture + +--- + +## 4. Personalization Types + +### Memorial Tags + +Purpose: + +- Make body loss visible. +- Separate body death from normal respawn. + +Examples: + +| Tag | Trigger | Player Read | +| ---- | ---- | ---- | +| `body_lost_ash_underpass` | Body dies during Ash Underpass. | This body did not return. | +| `body_retired_low_time` | Body retired or replaced after low TIME. | This body survived but cannot keep running. | +| `mission_partial_return` | Player extracts after proof. | Proof mattered even without full clear. | + +Alpha presentation: + +- A rail, string, board, or small tag cluster. +- Text is short: body name, mission, status, time. +- No large cinematic needed. + +### Proof Objects + +Purpose: + +- Give successful runs a visible artifact. +- Connect inventory, mission, and hub memory. + +Examples: + +| Object | Trigger | Placement | +| ---- | ---- | ---- | +| Signal Spike | Proof collected from Signal Split. | Trophy / Proof Shelf | +| Burnt Route Tag | Partial extract. | Notice Wall or Memorial Rail | +| Tollkeeper Mark | Full clear. | Proof Shelf, locked until boss path exists | + +Rule: + +Proof objects should not grant combat power in alpha. They can unlock dialogue, +mission intel, or a visible report. + +### Notice Wall Entries + +Purpose: + +- Make The Garden's civic layer readable. +- Support public-safe quest and outcome text. + +Entries: + +- active mission notice +- partial proof returned +- full clear posted +- missing body tag +- clinic warning +- route reopening rumor + +The notice wall can be a UI panel first and a world prop later. + +### Facility Status Marks + +Purpose: + +- Show that Garden actions happened. +- Avoid hiding facility state inside debug panels. + +Examples: + +| Facility | Status Mark | +| ---- | ---- | +| AMB Clinic Annex | `Body stable`, `Injury observed`, `Low TIME watch` | +| Repair Row | `Supply prepared`, `Scrap shortage`, `Tool ready` | +| Training Lane | `Drill complete`, `Target reset`, `Body not ready` | +| Signal Mast Path | `Route clue confirmed`, `Signal unstable`, `Sweep pending` | + +--- + +## 5. Data Ownership + +All durable Garden memory should be server-owned. + +Minimum data shape: + +| Field | Purpose | +| ---- | ---- | +| `garden_state_id` | Current hub or shard state. | +| `visible_memory_id` | Durable visible memory entry. | +| `source_event_id` | Ledger, outcome, facility, or mission event that created it. | +| `display_slot` | Memorial rail, proof shelf, notice wall, clinic, repair, signal, visitor note. | +| `visibility` | Public, player-only, debug-only, or locked. | +| `title` | Short player-facing label. | +| `summary` | One short sentence. | +| `related_body_id` | Optional body that caused or owns the memory. | +| `related_actor_id` | Optional NPC who can react. | +| `related_mission_id` | Optional mission source. | +| `created_at` | Server timestamp. | +| `expires_at` | Optional for temporary notices only. | + +Client rule: + +- Unity can display visible memory entries. +- Unity cannot create durable memory entries locally. +- LLM NPCs can suggest reactions but cannot create memory entries directly. + +--- + +## 6. Placement Slots + +Alpha should use fixed slots, not free placement. + +| Slot | Count | Content | +| ---- | ---- | ---- | +| Memorial Rail | 3-5 | dead/retired/returned body tags | +| Proof Shelf | 1-3 | recovered proof objects | +| Notice Wall | 3-6 | mission notices and outcomes | +| Clinic Corner | 1 | current body medical status | +| Repair Row Marker | 1 | repair or material state | +| Signal Mast Marker | 1 | route clue or sweep state | +| Visitor Note | 1 | NPC or offline-agent note | + +Why fixed slots: + +- faster Unity implementation +- no placement collision bugs +- readable from top-down camera +- easier server validation +- easier GitBook and issue handoff + +--- + +## 7. First Alpha Flow + +Recommended first implementation: + +1. Player accepts `Ash Underpass Signal`. +2. Notice Wall shows active mission notice. +3. Player returns with partial proof. +4. Outcome Report writes `proof_collected` and `partial_extract` ledgers. +5. Server creates one visible memory entry. +6. Proof Shelf shows `Signal Spike`. +7. Echo or Spark can comment on the returned proof. +8. Visitor Note records one short next recommendation. + +Death path: + +1. Player body dies in Ash Underpass. +2. Outcome/death flow writes body-loss event. +3. Memorial Rail shows body tag. +4. Vell or Echo can comment after reinhabitation. + +--- + +## 8. NPC Reactions + +NPC reactions should be compact and grounded. + +| NPC | Reacts To | Example Direction | +| ---- | ---- | ---- | +| Echo | mission proof, failed return, full clear | duty, access, body count | +| Spark | route proof, safer path, visitor note | rumor becoming fact | +| Vell | injury, low TIME, body loss | medical concern and dignity | +| Iron | salvage, repair, returned tools | scarcity and worker safety | +| Whisper | signal proof, route clue, sweep result | technical uncertainty | + +Rules: + +- NPCs may reference visible memory entries. +- NPCs must not reveal hidden body-transfer lore just because a tag appears. +- NPC comments should be one or two lines in alpha. +- Relationship changes must be server-owned and small. + +--- + +## 9. UI Surfaces + +### Garden Memory Panel + +Optional first UI surface: + +| Field | Example | +| ---- | ---- | +| Location | Memorial Rail | +| Title | `Signal Spike Returned` | +| Summary | `Proof from Ash Underpass is tagged and waiting for review.` | +| Source | `Ash Underpass Signal` | +| Related body | `Sentinel 0101` | +| Related NPC | `Spark` | + +### World Prop Interaction + +Minimum interaction: + +```text +Inspect +``` + +Optional commands: + +- Pin +- Hide +- Read related outcome +- Ask nearby NPC + +Do not add drag/drop placement in alpha. + +--- + +## 10. Economy and Monetization Guardrails + +Allowed: + +- cosmetic trophies +- memorial tags +- mission proof objects +- social NPC reactions +- light clue visibility +- morale flavor +- recoverable story context + +Not allowed in alpha: + +- furniture stats +- paid placement slots +- speed-up timers +- exclusive paid memorials +- decor gacha +- PvP advantage +- combat buffs from home objects + +If later decor has utility, it must be small, server-owned, visible, and not +required for alpha combat viability. + +--- + +## 11. Implementation Packets + +### Packet P1: Visible Memory Data + +Output: + +- Server-owned visible memory entry shape. +- Read RPC or profile payload section for current Garden visible memory. +- Tests for creating entries from trusted server events only. + +### Packet P2: Garden Memory Panel + +Output: + +- Unity panel or debug surface that lists visible memory entries by slot. +- No local creation of durable entries. + +### Packet P3: Proof Shelf And Memorial Rail + +Output: + +- Fixed-slot world props or UI rows. +- Partial extract proof object. +- Body death or retired body tag. + +### Packet P4: NPC Reaction Hook + +Output: + +- Focus NPC prompt context includes compact visible memory refs. +- NPC can comment on one visible memory entry. +- PromptTrace redacts private state. + +### Packet P5: Evidence Pack + +Output: + +- Screenshots before and after Ash Underpass. +- Ledger ids for the source event. +- Public-safe text showing what changed. + +--- + +## 12. Evidence Checklist + +- [ ] The Garden before-run screenshot. +- [ ] Notice Wall active mission entry. +- [ ] Outcome Report after partial extract. +- [ ] Proof Shelf visible memory entry. +- [ ] Memorial Rail body-loss entry if death path is tested. +- [ ] NPC reaction line referencing visible memory. +- [ ] Backend event id or ledger id for the source event. +- [ ] No Unity-side creation of durable memory state. +- [ ] No stat boost or paid decor behavior. +- [ ] Public-safe evidence pack contains no provider secrets or private + PromptTrace. + +--- + +## 13. Public Copy + +Notice Wall after proof: + +```text +Signal proof returned. Ash Underpass remains unstable. +``` + +Proof Shelf: + +```text +Signal Spike +Tagged from Ash Underpass. Still warm. +``` + +Memorial Rail: + +```text +Body did not return. +Name held. Debt not erased. +``` + +Visitor Note: + +```text +Spark says the route sounded different after you came back. +``` + +--- + +## 14. Open Questions + +These do not block alpha: + +1. Should players eventually choose which trophies are visible? +2. Should other players visiting The Garden see public memory only? +3. Should some visible memories decay after a season? +4. Should memorial text be editable by players, and if so how is moderation + handled? +5. Should NPC-authored visitor notes persist forever or rotate by recent + relationship state? +