From 6744370e208d3230cc7bc2fdd6215e7de2207029 Mon Sep 17 00:00:00 2001 From: JOY Date: Sat, 23 May 2026 02:21:19 +0700 Subject: [PATCH] docs: add alpha questline and ux flow --- CHANGELOG.md | 7 + ROADMAP.md | 14 + docs/SUMMARY.md | 2 + docs/design/02-vertical-slice-spec.md | 5 + docs/design/03-systems-index.md | 19 +- docs/design/12-game-design-document.md | 8 + docs/design/26-alpha-game-design-document.md | 19 +- docs/design/27-alpha-level-design.md | 8 + ...29-alpha-questline-and-encounter-design.md | 374 ++++++++++++++++++ docs/design/30-alpha-ux-flow.md | 326 +++++++++++++++ 10 files changed, 772 insertions(+), 10 deletions(-) create mode 100644 docs/design/29-alpha-questline-and-encounter-design.md create mode 100644 docs/design/30-alpha-ux-flow.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 193743d..51fc2f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,13 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots. and Ash Underpass blockout; and `docs/design/28-character-body-and-roster-design.md` defines character, body, roster, hostile body candidate, voice, memory, and relationship rules. +- Alpha questline, encounter, and UX documentation: + `docs/design/29-alpha-questline-and-encounter-design.md` defines `Check The + Ash Underpass Signal`, the focus cast, quest steps, mission card fields, + Tollkeeper Shell, rewards, failure states, and server-owned event ids; and + `docs/design/30-alpha-ux-flow.md` defines the first alpha UI flow from HUD + through dialogue, Body Hall, facilities, Mission Board, Gate HUD, outcome + report, offline-agent report, and reinhabitation. - Nakama now has a server-owned prototype Relay Yard facility action lane: `secondspawn_yard_status`, `secondspawn_yard_action_start`, and `secondspawn_yard_action_complete` expose Clinic stabilization, Training diff --git a/ROADMAP.md b/ROADMAP.md index 8049ef6..9ababb8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -91,6 +91,10 @@ Recommended views: - [x] Alpha GDD spine documented: playable alpha loop, first 60-minute flow, Relay Yard scope, Ash Underpass Gate scope, character/body roster rules, hostile body candidate constraints, UI surfaces, and backlog trace. +- [x] Alpha questline, encounter, and UX flow documented for `Check The Ash + Underpass Signal`, the Tollkeeper Shell encounter, mission card, outcome + report, dialogue flow, Body Hall, Gate HUD, offline-agent report, and + reinhabitation presentation. - [x] Backend tests for Nakama runtime behavior and model-backed fallback. - [x] Unity project baseline upgraded to Unity `6000.5.0b9`. - [x] Local Nakama runtime smoke-tested with the current TypeScript module. @@ -257,6 +261,14 @@ prototype. `docs/design/26-alpha-game-design-document.md`: mission risk, expected TIME, reward, recommended role, SECOND result, TIME spent, injury, memory, relationship, and ledger rows. +- [ ] Implement `Check The Ash Underpass Signal` from + `docs/design/29-alpha-questline-and-encounter-design.md`: signal notice, + Yard NPC clue, body check, Gate entry, signal objective, extract-or-push + choice, and outcome report. +- [ ] Replace remaining debug-only core-loop surfaces with the alpha UX flow in + `docs/design/30-alpha-ux-flow.md`: Main HUD, focused dialogue, Body Hall, + facility panel, Mission Board, Gate HUD, outcome report, offline-agent + report, and reinhabitation flow. - [x] Define the first Town/Yard building slice: clinic, body hall, workshop, signal tower, mess hall, memorial wall, market stall, and timer rules as world-simulation time, not pay-to-skip friction. @@ -269,6 +281,8 @@ prototype. - [x] Define the alpha docs/design lane: `26-alpha-game-design-document.md`, `27-alpha-level-design.md`, and `28-character-body-and-roster-design.md`. +- [x] Define the alpha questline, encounter, and UX docs: + `29-alpha-questline-and-encounter-design.md` and `30-alpha-ux-flow.md`. - [x] Add server-owned permanent NPC seed/list and prototype interaction RPCs. - [x] Add a Unity Play Mode debug panel for permanent NPC seed/list and NPC-to-NPC interaction smoke testing. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index f065e36..0f7a89c 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -11,6 +11,8 @@ - [Alpha Game Design Document](design/26-alpha-game-design-document.md) - [Alpha Level Design](design/27-alpha-level-design.md) - [Character, Body, and Roster Design](design/28-character-body-and-roster-design.md) +- [Alpha Questline and Encounter Design](design/29-alpha-questline-and-encounter-design.md) +- [Alpha UX Flow](design/30-alpha-ux-flow.md) - [Game Concept](design/00-game-concept.md) - [Game Pillars](design/01-pillars.md) - [Vertical Slice Spec](design/02-vertical-slice-spec.md) diff --git a/docs/design/02-vertical-slice-spec.md b/docs/design/02-vertical-slice-spec.md index 833e693..0144767 100644 --- a/docs/design/02-vertical-slice-spec.md +++ b/docs/design/02-vertical-slice-spec.md @@ -52,6 +52,9 @@ Execution references: and Ash Underpass blockout. - [28-character-body-and-roster-design.md](28-character-body-and-roster-design.md) defines body eligibility, roster roles, and character authoring. +- [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) + defines the first questline and encounter plan. +- [30-alpha-ux-flow.md](30-alpha-ux-flow.md) defines the alpha UI flow. --- @@ -205,6 +208,8 @@ When slice is complete, decision tree: - Alpha GDD: [26-alpha-game-design-document.md](26-alpha-game-design-document.md) - Alpha level design: [27-alpha-level-design.md](27-alpha-level-design.md) - Character and body design: [28-character-body-and-roster-design.md](28-character-body-and-roster-design.md) +- Alpha questline and encounter design: [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) +- Alpha UX flow: [30-alpha-ux-flow.md](30-alpha-ux-flow.md) - Pillars: [01-pillars.md](01-pillars.md) - Concept: [00-game-concept.md](00-game-concept.md) - ADRs (current): [docs/adr/](../adr/) diff --git a/docs/design/03-systems-index.md b/docs/design/03-systems-index.md index e12c2a6..8a8a68d 100644 --- a/docs/design/03-systems-index.md +++ b/docs/design/03-systems-index.md @@ -48,6 +48,11 @@ The first alpha execution spine is: 3. [28-character-body-and-roster-design.md](28-character-body-and-roster-design.md) for body eligibility, roster, hostile body candidates, voice profiles, and character authoring. +4. [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) + for the first questline, encounter, Tollkeeper Shell, rewards, and failure + states. +5. [30-alpha-ux-flow.md](30-alpha-ux-flow.md) for the first alpha UX flow and + required player-facing surfaces. Use these files when creating GitHub issues, technical designs, or Unity blockout tasks for the alpha. @@ -65,8 +70,8 @@ blockout tasks for the alpha. | 5 | Zone scene management (1 zone vertical slice) | Core | MVP | Prototype | (TDD pending) | NetworkRunner | | 6 | Combat (ARPG action) | Gameplay | MVP | Not started | [26-alpha-game-design-document.md](26-alpha-game-design-document.md), [27-alpha-level-design.md](27-alpha-level-design.md) | Player Controller, Networked state | | 7 | NPC dialogue and human-believable NPC agent model | Gameplay | MVP | Design | [13-human-believable-npc-agent-model.md](13-human-believable-npc-agent-model.md), [16-npc-society-multi-agent-architecture.md](16-npc-society-multi-agent-architecture.md), [21-permanent-npc-story-characteristics.md](21-permanent-npc-story-characteristics.md) | api.dos.ai model service (phase 2 ready), Profile persistence | -| 8 | Quest system (linear, 3-5 quests slice scope) | Gameplay | VS | Not started | [26-alpha-game-design-document.md](26-alpha-game-design-document.md), [27-alpha-level-design.md](27-alpha-level-design.md) | NPC dialogue, persistence | -| 9 | Dungeon instance (1 dungeon, 1 boss) | Gameplay | VS | Not started | [27-alpha-level-design.md](27-alpha-level-design.md), [15-gate-dungeon-pioneer-charter-system.md](15-gate-dungeon-pioneer-charter-system.md) | Combat, NPC dialogue, Photon | +| 8 | Quest system (linear, 3-5 quests slice scope) | Gameplay | VS | Not started | [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md), [26-alpha-game-design-document.md](26-alpha-game-design-document.md), [27-alpha-level-design.md](27-alpha-level-design.md) | NPC dialogue, persistence | +| 9 | Dungeon instance (1 dungeon, 1 boss) | Gameplay | VS | Not started | [27-alpha-level-design.md](27-alpha-level-design.md), [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md), [15-gate-dungeon-pioneer-charter-system.md](15-gate-dungeon-pioneer-charter-system.md) | Combat, NPC dialogue, Photon | | 10 | Boss LLM dialogue (Convai grounded) | Gameplay | VS | Not started | (TDD pending) | NPC dialogue | | 11 | AI agent for offline players (server-side) | Gameplay | VS | Prototype | [10-character-profile-agent-memory.md](10-character-profile-agent-memory.md) | NetworkRunner, api.dos.ai model service, intent schema | | 43 | NPC body embodiment / reinhabitation | Gameplay / Progression | VS | Concept | [28-character-body-and-roster-design.md](28-character-body-and-roster-design.md), [25-core-loop-v1.md](25-core-loop-v1.md), [12-game-design-document.md](12-game-design-document.md) | Actor profiles, SECOND economy, reinhabitation, body lifecycle, auth | @@ -86,12 +91,12 @@ blockout tasks for the alpha. | 20 | Quest progress persistence | Persistence | MVP | Not started | (TDD pending) | Profile, Quest system | | 21 | Level/stat persistence | Persistence | MVP | Prototype | [14-character-stat-and-relationship-system.md](14-character-stat-and-relationship-system.md) | Profile | | 22 | Auth (Nakama + DOS Chain wallet, Supabase sidecar if useful) | Persistence | MVP | Prototype | (TDD pending - reuse DOS.Me pattern as identity bridge reference) | Nakama, thirdweb | -| 23 | HUD (combat, level/stats, TIME) | UI | VS | Prototype | (deferred template `_deferred/hud-design.md`) | Combat, Profile | +| 23 | HUD (combat, level/stats, TIME) | UI | VS | Prototype | [30-alpha-ux-flow.md](30-alpha-ux-flow.md) | Combat, Profile | | 24 | Inventory UI | UI | VS | Not started | (deferred template `_deferred/ux-spec.md`) | Inventory persistence | -| 25 | NPC dialogue UI | UI | VS | Not started | (deferred) | NPC dialogue | -| 26 | Quest tracker UI | UI | VS | Not started | (deferred) | Quest system | -| 27 | Reincarnation UI | UI | VS | Not started | (deferred) | Reincarnation flow | -| 28 | AI agent activity log UI | UI | VS | Not started | (deferred) | AI agent | +| 25 | NPC dialogue UI | UI | VS | Not started | [30-alpha-ux-flow.md](30-alpha-ux-flow.md) | NPC dialogue | +| 26 | Quest tracker UI | UI | VS | Not started | [30-alpha-ux-flow.md](30-alpha-ux-flow.md) | Quest system | +| 27 | Reincarnation UI | UI | VS | Not started | [30-alpha-ux-flow.md](30-alpha-ux-flow.md) | Reincarnation flow | +| 28 | AI agent activity log UI | UI | VS | Not started | [30-alpha-ux-flow.md](30-alpha-ux-flow.md) | AI agent | | 40 | Gameplay ledger (reward, BodyTime, combat, quest audit) | Persistence / Meta | MVP | Prototype | [23-gameplay-ledger-technical-design.md](23-gameplay-ledger-technical-design.md) | Profile, TIME / SECOND economy, Combat, Quest | | 29 | Audio (SFX, ambient, music - placeholder for slice) | Audio | VS | Not started | (deferred template `_deferred/sound-bible.md`) | - | | 30 | Chat (Nakama channel first, Supabase Realtime sidecar only if useful) | Narrative / UI | VS | Not started | (TDD pending) | Nakama | diff --git a/docs/design/12-game-design-document.md b/docs/design/12-game-design-document.md index cc704f3..e399f67 100644 --- a/docs/design/12-game-design-document.md +++ b/docs/design/12-game-design-document.md @@ -32,6 +32,12 @@ The alpha-specific playable target is now split into focused build documents: - [28-character-body-and-roster-design.md](28-character-body-and-roster-design.md) defines the character/body/roster model, body eligibility rules, hostile body candidates, and alpha roster authoring template. +- [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) + defines the first questline, encounter roles, Tollkeeper Shell, rewards, and + failure states. +- [30-alpha-ux-flow.md](30-alpha-ux-flow.md) defines the first alpha UX flow + across HUD, NPC dialogue, Body Hall, facilities, Mission Board, Gate HUD, + outcome report, offline-agent report, and reinhabitation. Use those files as the execution spine for the first alpha. This larger GDD remains the broad product source, but implementation tasks should reference @@ -1578,6 +1584,8 @@ Useful source documents: - [26-alpha-game-design-document.md](26-alpha-game-design-document.md) - [27-alpha-level-design.md](27-alpha-level-design.md) - [28-character-body-and-roster-design.md](28-character-body-and-roster-design.md) +- [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) +- [30-alpha-ux-flow.md](30-alpha-ux-flow.md) --- diff --git a/docs/design/26-alpha-game-design-document.md b/docs/design/26-alpha-game-design-document.md index f0d28a9..4866e27 100644 --- a/docs/design/26-alpha-game-design-document.md +++ b/docs/design/26-alpha-game-design-document.md @@ -13,6 +13,19 @@ This document defines the first playable alpha target for SECOND SPAWN. It turns the current design direction into a concrete player loop, content set, level structure, character model, UI surface list, and backlog map. +Companion execution docs: + +- [27-alpha-level-design.md](27-alpha-level-design.md) defines the Relay Yard + and Ash Underpass blockout. +- [28-character-body-and-roster-design.md](28-character-body-and-roster-design.md) + defines body, roster, hostile body, voice, memory, and relationship rules. +- [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) + defines the first questline, encounter roles, Tollkeeper Shell, rewards, and + failure states. +- [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. + Alpha means: - The core game loop is playable without debug panels. @@ -416,7 +429,7 @@ Open backlog items that directly feed alpha design: | Issue | Design Impact | | ---- | ---- | | #143 Gate mission selection | Needs mission card fields from this doc and level design doc. | -| #144 Gate outcome report | Needs reward, TIME, injury, memory, relationship, and ledger fields. | +| #144 Gate outcome report | Needs reward, TIME, injury, memory, relationship, and ledger fields from the UX and questline docs. | | #145 NPC spacing | Supports readable Relay Yard alpha layout. | | #146 Animation action registry | Required for talk, attack, hit, death, and weapon stance. | | #147 Combat target selection | Required for ARPG hit validation. | @@ -425,8 +438,8 @@ Open backlog items that directly feed alpha design: | #150 Auth state UI | Required for clean playtest readiness. | | #151 WebGL demo lane | Optional alpha distribution lane. | | #152 Local health check | Required to make agent-driven iteration reliable. | -| #33 First questline | Needs quest beats aligned to this alpha loop. | -| #34 Dungeon and boss plan | Needs the Ash Underpass level design. | +| #33 First questline | Covered by [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md). | +| #34 Dungeon and boss plan | Covered by [27-alpha-level-design.md](27-alpha-level-design.md) and [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md). | | #29 Time-loot rules | Keep design-only until combat validation and anti-abuse are ready. | --- diff --git a/docs/design/27-alpha-level-design.md b/docs/design/27-alpha-level-design.md index 5258f43..56eb0b0 100644 --- a/docs/design/27-alpha-level-design.md +++ b/docs/design/27-alpha-level-design.md @@ -21,6 +21,14 @@ The level exists to prove the game's core promise, not to show final map scale. Every space should teach one part of the loop: living NPC bodies, embodiment, Yard prep, Gate risk, combat, reward, consequence, and continuity. +Quest, encounter, and UX companions: + +- [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) + defines the quest steps, enemy roles, Tollkeeper Shell, rewards, and failure + states for this layout. +- [30-alpha-ux-flow.md](30-alpha-ux-flow.md) defines how the player reads the + mission, Gate HUD, dialogue, outcome, and reinhabitation surfaces. + --- ## 2. Level Pillars diff --git a/docs/design/29-alpha-questline-and-encounter-design.md b/docs/design/29-alpha-questline-and-encounter-design.md new file mode 100644 index 0000000..197abb1 --- /dev/null +++ b/docs/design/29-alpha-questline-and-encounter-design.md @@ -0,0 +1,374 @@ +# Alpha Questline and Encounter Design + +*Status: Alpha design baseline* +*Created: 2026-05-23* +*Source of truth level: First alpha questline, Ash Underpass encounter plan, +and boss design contract. Complements the Alpha GDD and Alpha Level Design.* + +--- + +## 1. Purpose + +This document turns the alpha loop into a concrete first questline and first +Gate encounter. It is intentionally small: one hub questline, one Gate mission, +one elite or boss shell, one outcome report, and enough NPC context to make the +world feel alive. + +Backlog coverage: + +- #33 Build first questline and hub NPC story beat. +- #34 Prototype first dungeon and boss encounter plan. +- #143 Implement Gate mission selection and prototype mission card UI. +- #144 Create Gate outcome report UI. +- #147 Implement combat target selection and ARPG hit validation loop. +- #148 Add enemy and training target lifecycle for vertical slice combat smoke. + +--- + +## 2. Questline Summary + +Working title: `Check The Ash Underpass Signal` + +Logline: + +> The Relay Yard keeps receiving a convoy signal from a collapsed underpass. +> If the signal is real, the route may save bodies. If it is a lure, the next +> crew will die. The player must use their current body to verify it. + +Quest purpose: + +- Teach that NPCs know the Yard and current body. +- Teach that mission intel can come from relationships. +- Teach that Gate entry risks TIME. +- Teach that a server-owned outcome report changes memory and relationships. + +Player-facing objective: + +```text +Verify the Ash Underpass signal and return with proof. +``` + +--- + +## 3. Cast + +Use a small focus cast. Do not make all ten NPCs equally important in the first +quest. + +| Character | Role In Quest | Required Function | +| ---- | ---- | ---- | +| Gate Sentinel 0101 or 0627 | Warns about access and route danger | Starts or frames the route problem. | +| Route Courier 0244 or 0733 | Knows the underpass rumor | Gives optional safer-route clue. | +| Clinic Operator 0320 or 0819 | Reads current body condition | Explains TIME risk and body suitability. | +| Crossline Surveyor 5104 or 1058 | Reads the signal | Connects Signal Tower to Gate mission. | +| Tollkeeper Shell | Gate elite or boss | Tests combat and passage theme. | + +Relationship use: + +- Low trust: NPC gives public facts only. +- Higher trust: NPC gives one useful clue or warning. +- Hostility: NPC may refuse optional detail but must not block the main quest. + +--- + +## 4. Quest Steps + +### Step 1: The Signal Notice + +Location: Signal Tower or Mission Board. + +Player action: + +- Inspect the Ash Underpass mission card. +- See risk, expected TIME exposure, reward, and recommended role. + +Server state: + +- Quest becomes `available`. +- No reward is granted. + +Player learning: + +- Gate missions are selected, not random. +- TIME risk and SECOND reward are visible before entry. + +### Step 2: Ask The Yard + +Location: Central Yard. + +Player action: + +- Talk to one focus NPC about the signal. + +Allowed NPC responses: + +- Gate Sentinel: route warning. +- Route Courier: underpass rumor. +- Clinic Operator: body condition warning. +- Crossline Surveyor: signal verification hint. + +Server state: + +- Record a compact memory or quest clue if the NPC answer is accepted. +- Relationship familiarity can increase slightly. + +Player learning: + +- NPC dialogue can change the mission context. +- NPCs are grounded in body, Yard, route, and relationship. + +### Step 3: Body Check + +Location: Clinic / Body Hall. + +Player action: + +- Confirm current body can attempt the mission. +- Optional: use Clinic stabilization if TIME is low. + +Server state: + +- Facility action may spend or reward bounded SECOND/TIME according to its + existing server-owned rules. +- Quest can advance to `ready_to_enter`. + +Player learning: + +- The current body is not abstract. It has condition and TIME. + +### Step 4: Commit At The Gate Apron + +Location: Gate Exterior Apron. + +Player action: + +- Confirm mission entry. + +Server state: + +- Record mission attempt id. +- Record current body id, party, entry time, expected TIME exposure, and + selected clues. + +Player learning: + +- Gate entry is an accountable event. + +### Step 5: Verify The Signal + +Location: Ash Underpass Gate. + +Player action: + +- Reach the signal node. +- Fight or avoid basic hostile pressure. +- Interact with the node. + +Server state: + +- Objective `signal_verified` is set only after validated interaction. +- Optional clue changes possible route or encounter text. + +Player learning: + +- Objectives are server-owned. +- Combat and mission state are linked. + +### Step 6: Choose Extract Or Push + +Location: Signal Split or Toll Plaza Arena. + +Player action: + +- Extract after proof for partial reward, or push into the Tollkeeper encounter + for full clear. + +Server state: + +- Partial extract: smaller reward, no boss clear. +- Full clear: larger reward, clear record, boss memory hook. + +Player learning: + +- Greed and survival matter. +- Not every run must be full clear. + +### Step 7: Outcome Report + +Location: Relay Yard. + +Player action: + +- Read outcome report. +- See which NPCs react. + +Server state: + +- Write gameplay ledger rows. +- Update quest state, reward state, memory, and relationship summaries. +- Do not let LLMs or clients self-report success. + +Player learning: + +- The world remembers what happened. + +--- + +## 5. Mission Card Fields + +The mission board should eventually read from server-owned mission data. + +| Field | Example | +| ---- | ---- | +| Mission id | `ash-underpass-signal` | +| Title | `Ash Underpass Signal` | +| Rank | F or E | +| Objective | Verify signal and extract proof | +| Expected TIME exposure | `TIME risk: 6m to 10m` | +| Reward | `Reward: 180-420 SECOND` | +| Recommended role | Sentinel, Courier, or Surveyor | +| Known hazard | Hostile response near signal node | +| Optional intel | Safer side path if discovered | +| Clear type | Partial extract or full clear | +| Entry requirement | Alive body, enough TIME, mission accepted | + +UI copy should stay short. Details can expand in a panel. + +--- + +## 6. Encounter Plan + +### Basic Hostile: Ash Stray + +Purpose: + +- Basic melee pressure. +- Teaches target selection, range, dodge, and hit validation. + +Behavior: + +- Approach. +- Attack. +- Short recovery. +- Reset if player exits room. + +Server requirements: + +- Valid target id. +- Range and cone validation. +- Alive state. +- Damage cap. +- Defeat event. + +### Support Hostile: Signal Jack + +Purpose: + +- Adds positional pressure without complexity. + +Behavior: + +- Keeps distance. +- Sends weak ranged pressure or signal pulse. +- Low HP. + +Server requirements: + +- Ranged line-of-sight validation. +- Interrupt or defeat state. + +### Elite / Boss: Tollkeeper Shell + +Purpose: + +- First memorable Gate authority. +- Represents passage, debt, route control, and the price of crossing. + +Combat phases: + +| Phase | Trigger | Behavior | +| ---- | ---- | ---- | +| Hold | Start | Guards the signal path and uses heavy telegraphed strikes. | +| Toll | 70 percent HP | Marks a zone or demands distance, creating movement pressure. | +| Break | 35 percent HP | Calls two basic hostile actors or activates hazards. | +| Collapse | Defeat | Opens full-clear extraction and memory hook. | + +LLM usage: + +- One pre-fight line or phase line is allowed if model-backed and grounded. +- The line cannot alter HP, rewards, clear state, or objective state. +- If model service fails, use no line or a short deterministic warning. Do not + block combat. + +Example boss line: + +```text +No body crosses on borrowed time without paying the route. +``` + +--- + +## 7. Rewards and Consequences + +Outcome report fields: + +| Field | Partial Extract | Full Clear | Failure / Body Death | +| ---- | ---- | ---- | ---- | +| SECOND | Small reward | Larger reward | None or insured minimum if designed | +| TIME | Spent or damaged | Spent, possible bonus | Body TIME reaches zero or body dies | +| Quest | Signal proof complete | Gate clear complete | Attempt failed or partial clue retained | +| Memory | NPCs learn the route is real | NPCs remember clear | NPCs remember body loss | +| Relationship | Small trust gain | Larger respect/trust gain | Grief, fear, blame, or caution | +| Ledger | Reward and objective rows | Reward, clear, boss rows | Death, loss, attempt rows | + +Reward guardrails: + +- `luck` can bias capped rolls only after the server approves the reward path. +- LLMs cannot invent rewards. +- The client cannot submit reward amounts. +- Repeat rewards require cooldowns or attempt ids. + +--- + +## 8. Failure States + +| Failure | Player Experience | Server State | +| ---- | ---- | ---- | +| Extract early | Player keeps body and partial information | Partial outcome, no full clear | +| Objective failed | Player returns with no proof | Attempt failed, possible small memory | +| Body death | Current body lost | Death event, reinhabitation flow | +| Timeout | Gate pressure forces extraction or failure | Attempt timed out | +| Model unavailable | NPC line or boss line missing or fallback | Gameplay continues | + +Do not make model failure fail the mission. The model is presentation and +intent selection. Mission authority is backend and Fusion server state. + +--- + +## 9. Implementation Notes + +Data contracts needed later: + +- `MissionDefinition` +- `MissionAttempt` +- `MissionObjectiveState` +- `EncounterActorState` +- `OutcomeReport` +- `RewardGrant` +- `RelationshipDelta` +- `MemoryDelta` +- `ClearRecord` + +Minimum server-owned event ids: + +- `mission_accepted` +- `mission_entered` +- `objective_verified` +- `enemy_defeated` +- `boss_defeated` +- `mission_extracted` +- `mission_failed` +- `body_died` +- `reward_granted` + +These event ids should feed the gameplay ledger and the outcome report. diff --git a/docs/design/30-alpha-ux-flow.md b/docs/design/30-alpha-ux-flow.md new file mode 100644 index 0000000..1bedab5 --- /dev/null +++ b/docs/design/30-alpha-ux-flow.md @@ -0,0 +1,326 @@ +# Alpha UX Flow + +*Status: Alpha design baseline* +*Created: 2026-05-23* +*Source of truth level: First playable alpha UX contract. Visual styling can +change, but the information architecture should remain stable.* + +--- + +## 1. Purpose + +This document defines the first alpha UX flow for the core loop. It focuses on +what the player needs to see and do, not final art polish. + +The alpha UX must make five things obvious: + +1. Who am I inhabiting? +2. How much TIME does this body have? +3. What can I do in the Yard? +4. What risk and reward does the Gate offer? +5. What changed when I returned? + +--- + +## 2. Screen Flow + +```text +Main HUD + -> Nearby NPC Dialogue + -> Body Hall + -> Yard Facility Panel + -> Mission Board + -> Gate HUD + -> Outcome Report + -> Offline Agent Policy / Return Report + -> Death / Reinhabitation if needed +``` + +The player should not need debug panels for the alpha demo. + +--- + +## 3. Main HUD + +Required information: + +- Current body display name. +- Body role. +- Level. +- HP. +- Energy. +- TIME as readable duration. +- AI state if offline-agent or local agent control is active. +- Compact objective tracker. +- Small FPS display can stay in debug builds. + +Recommended layout: + +- Top-left: body card and vitals. +- Top-right: active objective tracker. +- Bottom-left or bottom-center: chat and dialogue surfaces when active. +- Bottom-right: optional action hints. + +Do not show raw backend field names in alpha UI. `BodyTime` is internal. Use +`TIME`. + +--- + +## 4. NPC Nameplate + +Required information: + +- Display name. +- Level. +- Role or profession. +- AI status. + +Status colors: + +| Status | Meaning | Color Direction | +| ---- | ---- | ---- | +| DOS.AI | Model-backed response available | calm green or white | +| queued | Waiting for model or scheduler | muted blue or white | +| fallback | Degraded deterministic response | amber | +| error | Request failed | red | +| listening | Focused dialogue target | pale blue or white | + +Rules: + +- Hide or reduce focused NPC overhead plate during bottom dialogue mode. +- Avoid truncating important names without tooltip or expanded panel. +- Keep status short. + +--- + +## 5. Focused Dialogue Panel + +Purpose: + +- Let the player talk to one nearby NPC. +- Show readable message history. +- Keep movement keys from controlling the character while typing. + +Behavior: + +- Press `E` near an NPC to enter dialogue mode. +- Player and NPC stop free movement and face each other. +- `Esc` exits dialogue mode. +- `Enter` sends message when the input field is focused. +- Message send is disabled while a direct NPC reply is pending unless queued + multi-turn support is explicitly implemented. + +Layout: + +- NPC title at top. +- Status line below title: answering, listening, retrying, failed. +- Message area with speaker bubbles. +- Player input row at bottom. + +Message alignment: + +- NPC messages on the left. +- Player messages on the right. +- Each bubble width should fit content up to a max width, not fill the whole + panel by default. + +Text size: + +- Use larger readable alpha text than debug IMGUI. +- Avoid tiny text at QHD and 4K. + +--- + +## 6. Body Hall Panel + +Purpose: + +- Explain embodiment and current body state. + +Required sections: + +| Section | Shows | +| ---- | ---- | +| Current Body | Name, role, level, TIME, lifecycle, body grade, source actor. | +| Stats | Eight core stats and derived HP/energy. | +| Memory | 1-3 compact body history notes. | +| Eligibility | Whether another body can be inhabited, cost, constraints. | +| Warnings | Injury, low TIME, faction hostility, hostile-body constraints. | + +Starter flow: + +- The first alpha can begin with the current body already inhabited, but the + panel must still explain that this is an existing body. +- Later, it can support explicit body selection before first control. + +--- + +## 7. Yard Facility Panel + +Purpose: + +- Convert Yard building from debug buttons into readable actions. + +Required alpha actions: + +- Clinic stabilization. +- Training Yard focus drill. +- Signal Tower sweep. + +Each action card shows: + +- action name +- short result +- cost or requirement +- duration if any +- current status +- claim or complete button + +Rules: + +- Actions are server-owned. +- UI cannot grant rewards directly. +- If an action is idempotent or already running, the UI should show that + state instead of starting duplicates. + +--- + +## 8. Mission Board + +Purpose: + +- Let the player choose the Gate mission with clear risk and reward. + +Mission card fields: + +- title +- rank +- objective +- expected TIME exposure +- reward range in SECOND +- recommended body role +- known hazards +- available intel +- start button + +Example: + +```text +Ash Underpass Signal +Rank F +Objective: Verify signal and extract proof. +TIME risk: 6m to 10m +Reward: 180-420 SECOND +Recommended: Sentinel, Courier, Surveyor +``` + +Rules: + +- Mission start creates a server-owned attempt. +- Mission card can show unknowns, but it should not lie about known cost. +- Hidden objectives require clues, not random UI surprises. + +--- + +## 9. Gate HUD + +Required information: + +- Current objective. +- Current body HP, energy, TIME. +- Enemy target HP if a target is selected. +- Clear feedback for miss, out-of-range, blocked, target defeated. +- Extract status or return path. + +Gate HUD should be quieter than the Yard HUD. Combat readability wins over +NPC chatter. + +--- + +## 10. Outcome Report + +Purpose: + +- Make consequences legible. + +Sections: + +| Section | Shows | +| ---- | ---- | +| Result | Partial extract, full clear, failure, or body death. | +| Rewards | SECOND gained, items, clear record, if any. | +| TIME | TIME spent, TIME gained, body condition. | +| Body | injury, lifecycle, level/stat change, death or survival. | +| Memory | new memory summaries. | +| Relationships | trust, fear, respect, debt, hostility changes. | +| Ledger | compact audit rows for debug and trust. | +| Next | recommended Yard action, next mission, or reinhabitation. | + +Rules: + +- The report reads server-owned state. +- The player should be able to understand what caused each reward or penalty. +- Do not hide body death in a small toast. + +--- + +## 11. Offline Agent Policy and Return Report + +Policy options for alpha: + +- Observe only. +- Safe Yard work. +- Safe training. +- Stop below TIME threshold. + +Return report fields: + +- time away +- actions attempted +- model-backed decisions vs fallback +- rewards or no rewards +- TIME spent +- risk stops +- NPC memories or relationship changes + +The report should make offline agent continuity visible without encouraging +unbounded AFK farming. + +--- + +## 12. Death and Reinhabitation Flow + +Required information: + +- The current body died or was retired. +- What was lost. +- What carried over. +- SECOND cost to continue. +- New eligible body preview. + +Tone: + +- Somber, clear, not punitive UI rage. +- This is a major game identity moment. + +Rules: + +- No quick respawn button that hides the cost. +- No LLM-generated body unlock. +- No client-owned body replacement. + +--- + +## 13. Alpha UX Acceptance Checklist + +- [ ] A playtester can identify current body, role, and TIME in 5 seconds. +- [ ] A playtester can start focused NPC chat without moving accidentally while + typing. +- [ ] A playtester can find Body Hall, Facility actions, and Mission Board + without debug instructions. +- [ ] Mission risk and reward are visible before Gate entry. +- [ ] Combat hit and miss reasons are visible enough for debugging and play. +- [ ] Outcome report explains rewards, TIME, memory, and relationship changes. +- [ ] Death flow reads as body loss and reinhabitation, not normal respawn. +- [ ] Fallback or error AI status is visible and does not masquerade as a + successful model-backed NPC brain.