From 82b6dbecf5eb9af7f7243a941334584c4f1bcaf6 Mon Sep 17 00:00:00 2001 From: JOY Date: Tue, 26 May 2026 07:35:31 +0700 Subject: [PATCH] docs: add Ash Underpass gameplay packet --- ROADMAP.md | 3 + docs/SUMMARY.md | 1 + docs/design/26-alpha-game-design-document.md | 3 + docs/design/27-alpha-level-design.md | 3 + ...29-alpha-questline-and-encounter-design.md | 6 + docs/design/33-alpha-production-backlog.md | 12 + docs/design/34-alpha-acceptance-matrix.md | 4 + .../38-alpha-design-decision-register.md | 1 + .../54-ash-underpass-gate-gameplay-design.md | 653 ++++++++++++++++++ 9 files changed, 686 insertions(+) create mode 100644 docs/design/54-ash-underpass-gate-gameplay-design.md diff --git a/ROADMAP.md b/ROADMAP.md index 3ba32f15..61e44891 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -98,6 +98,9 @@ Recommended views: Underpass Signal`, the Tollkeeper Shell encounter, mission card, outcome report, dialogue flow, Body Hall, Gate HUD, offline-agent report, and reinhabitation presentation. +- [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] 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, diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4ec6eaff..052e46ea 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -19,6 +19,7 @@ - [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) +- [Ash Underpass Gate Gameplay Design](design/54-ash-underpass-gate-gameplay-design.md) - [Alpha UX Flow](design/30-alpha-ux-flow.md) - [Alpha Economy, Balance, and Playtest Plan](design/31-alpha-economy-balance-and-playtest-plan.md) - [Alpha Art, Audio, and Content Direction](design/32-alpha-art-audio-and-content-direction.md) diff --git a/docs/design/26-alpha-game-design-document.md b/docs/design/26-alpha-game-design-document.md index 5b16dde3..5866ec05 100644 --- a/docs/design/26-alpha-game-design-document.md +++ b/docs/design/26-alpha-game-design-document.md @@ -22,6 +22,9 @@ Companion execution docs: - [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. +- [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. - [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/27-alpha-level-design.md b/docs/design/27-alpha-level-design.md index 50de0c44..ad9a8df8 100644 --- a/docs/design/27-alpha-level-design.md +++ b/docs/design/27-alpha-level-design.md @@ -26,6 +26,9 @@ 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. +- [54-ash-underpass-gate-gameplay-design.md](54-ash-underpass-gate-gameplay-design.md) + defines the detailed room contracts, objective state, encounter actors, and + evidence checklist for Ash Underpass. - [30-alpha-ux-flow.md](30-alpha-ux-flow.md) defines how the player reads the mission, Gate HUD, dialogue, outcome, and reinhabitation surfaces. diff --git a/docs/design/29-alpha-questline-and-encounter-design.md b/docs/design/29-alpha-questline-and-encounter-design.md index 80bfe182..13de1c4b 100644 --- a/docs/design/29-alpha-questline-and-encounter-design.md +++ b/docs/design/29-alpha-questline-and-encounter-design.md @@ -14,6 +14,12 @@ 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. +Detailed Gate gameplay packet: + +- [54-ash-underpass-gate-gameplay-design.md](54-ash-underpass-gate-gameplay-design.md) + defines room contracts, mission state machine, objective validation, + encounter actors, outcome rules, and evidence requirements. + Backlog coverage: - #33 Build first questline and hub NPC story beat. diff --git a/docs/design/33-alpha-production-backlog.md b/docs/design/33-alpha-production-backlog.md index 6363d3e1..faf20995 100644 --- a/docs/design/33-alpha-production-backlog.md +++ b/docs/design/33-alpha-production-backlog.md @@ -131,6 +131,12 @@ Goal: > Let the player choose a Gate mission with clear risk, reward, and body > suitability. +Detailed build contract: + +- [54-ash-underpass-gate-gameplay-design.md](54-ash-underpass-gate-gameplay-design.md) + for the Ash Underpass mission definition, attempt lifecycle, state machine, + room flow, and evidence checklist. + Required work: | Task | Acceptance | @@ -153,6 +159,12 @@ Goal: > Prove the action loop with one short Gate route, one hostile type, one signal > objective, and one elite or boss shell. +Detailed build contract: + +- [54-ash-underpass-gate-gameplay-design.md](54-ash-underpass-gate-gameplay-design.md) + for room contracts, encounter actors, combat/objective boundaries, and + partial/full clear rules. + Required work: | Task | Acceptance | diff --git a/docs/design/34-alpha-acceptance-matrix.md b/docs/design/34-alpha-acceptance-matrix.md index 1780a8e5..4fe83252 100644 --- a/docs/design/34-alpha-acceptance-matrix.md +++ b/docs/design/34-alpha-acceptance-matrix.md @@ -11,6 +11,10 @@ This document defines how to decide whether the alpha GDD has been implemented well enough to show to testers. +Gate mission evidence should use +[54-ash-underpass-gate-gameplay-design.md](54-ash-underpass-gate-gameplay-design.md) +as the detailed room, state, objective, and outcome contract. + It is intentionally practical. Each row maps a player-facing promise to: - required proof diff --git a/docs/design/38-alpha-design-decision-register.md b/docs/design/38-alpha-design-decision-register.md index cafd514b..9589b0f4 100644 --- a/docs/design/38-alpha-design-decision-register.md +++ b/docs/design/38-alpha-design-decision-register.md @@ -141,6 +141,7 @@ When a design question appears during implementation: | `27-alpha-level-design.md` | The Garden and Ash Underpass blockout. | | `28-character-body-and-roster-design.md` | Body, roster, hostile body, voice, memory, and relationship rules. | | `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. | | `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. | diff --git a/docs/design/54-ash-underpass-gate-gameplay-design.md b/docs/design/54-ash-underpass-gate-gameplay-design.md new file mode 100644 index 00000000..c8f9b276 --- /dev/null +++ b/docs/design/54-ash-underpass-gate-gameplay-design.md @@ -0,0 +1,653 @@ +# Ash Underpass Gate Gameplay Design + +*Status: Alpha implementation design packet* +*Created: 2026-05-26* +*Source of truth level: Detailed gameplay contract for the first alpha Gate +mission. This complements the broader quest, level, UX, economy, and backlog +docs.* + +--- + +## 1. Purpose + +This document turns `Ash Underpass Signal` into a buildable Gate gameplay +packet. It answers what the player does room by room, what the server owns, +what the Unity client may display, which states the mission can enter, and +what evidence proves the slice works. + +Companion docs: + +- [27-alpha-level-design.md](27-alpha-level-design.md) defines hub and Gate + blockout scale. +- [29-alpha-questline-and-encounter-design.md](29-alpha-questline-and-encounter-design.md) + defines the questline, cast, and Tollkeeper Shell concept. +- [30-alpha-ux-flow.md](30-alpha-ux-flow.md) defines the player-facing screens. +- [31-alpha-economy-balance-and-playtest-plan.md](31-alpha-economy-balance-and-playtest-plan.md) + defines TIME and SECOND tuning defaults. +- [33-alpha-production-backlog.md](33-alpha-production-backlog.md) defines A3, + A4, and A5 implementation order. +- [34-alpha-acceptance-matrix.md](34-alpha-acceptance-matrix.md) defines alpha + readiness gates and evidence rules. + +Non-goal: + +This is not a procedural dungeon system, not a final boss design bible, and not +a live economy spec. It is the smallest Gate that can prove SECOND SPAWN's +alpha loop. + +--- + +## 2. Mission Thesis + +The mission should teach one clear idea: + +> A Gate run is an accountable risk taken by a specific body, not a disposable +> dungeon attempt. + +The player should understand: + +- The current body is risking TIME. +- The mission was selected from The Garden, not randomly spawned. +- NPC intel can reduce uncertainty but cannot replace player action. +- Combat, objective progress, reward, and outcome are server-owned. +- Returning with partial proof is valid. +- Pushing deeper can pay more but risks the body. + +--- + +## 3. Player-Facing Summary + +Mission title: + +```text +Ash Underpass Signal +``` + +Mission card copy: + +```text +A dead transit route is still broadcasting a convoy signal. Verify the source, +bring back proof, and do not let the body run out of TIME. +``` + +Primary objective: + +```text +Reach the signal node and return with proof. +``` + +Optional objective: + +```text +Clear the Tollkeeper Shell before extraction. +``` + +Recommended roles: + +- Sentinel: safer first clear. +- Courier: faster route read and extraction. +- Surveyor: better signal clue and optional side path. + +--- + +## 4. Mission State Machine + +Mission state must be server-owned. Unity may display state but cannot assert +completion, reward, or clear type. + +```text +locked + -> available + -> accepted + -> ready_to_enter + -> attempt_created + -> entered_gate + -> signal_reached + -> proof_collected + -> partial_extract + -> full_clear + -> outcome_recorded +``` + +Failure states: + +```text +attempt_abandoned +body_dead +timed_out +invalidated +``` + +State rules: + +| State | Entered By | Server-Owned Data | +| ---- | ---- | ---- | +| `available` | Signal notice or Garden NPC route hook | Mission id, rank, baseline risk, reward range | +| `accepted` | Player accepts mission | Player id, current body id, accepted time | +| `ready_to_enter` | Body check complete | Current body status, optional clue ids | +| `attempt_created` | Gate entry request passes validation | Attempt id, body id, party placeholder, selected intel | +| `entered_gate` | Fusion instance confirms entry | Gate instance id, entry timestamp, TIME exposure start | +| `signal_reached` | Player enters Signal Split or interacts with marker | Room id, marker id, objective progress | +| `proof_collected` | Validated signal-node interaction | Proof item or objective flag, source event id | +| `partial_extract` | Player extracts after proof | Partial clear flag, reward bracket, memory tags | +| `full_clear` | Tollkeeper Shell defeated and proof collected | Full clear flag, boss memory tag, reward bracket | +| `outcome_recorded` | Outcome report writes ledgers | Reward, TIME spent, injury, memory, relationship refs | + +Invalid state transitions should return a readable reason: + +- `body_not_alive` +- `not_enough_time` +- `mission_not_accepted` +- `attempt_not_found` +- `objective_not_reached` +- `combat_not_validated` +- `already_claimed` + +--- + +## 5. Room Flow + +Target length: + +- First run: 10-15 minutes. +- Experienced repeat: 6-9 minutes. +- Alpha blockout: 4 required rooms plus optional side spur. + +```text +Ash Underpass Apron + -> Threshold Platform + -> Collapsed Service Corridor + -> Signal Split + -> Optional Memory Spur + -> Toll Plaza Arena + -> Extraction Marker / Outcome Report +``` + +### 5.1 Ash Underpass Apron + +Purpose: + +- Last safe confirmation point. +- Lets the player back out before attempt creation. +- Shows expected TIME exposure and current body warning. + +Required interactions: + +- Read mission card. +- Confirm entry. +- Cancel safely. + +Required UI: + +- Current body name and TIME. +- Risk estimate. +- Reward range. +- Recommended role. +- Optional intel list. + +Server boundary: + +- Confirm entry calls mission attempt creation. +- Cancel does not spend rewards, set clear flags, or write completion ledgers. + +### 5.2 Threshold Platform + +Purpose: + +- Teaches that this is now a Gate instance. +- Starts visible TIME pressure. +- Gives the player a clear forward route. + +Required content: + +- Safe spawn pad. +- Objective marker: `Reach the signal node`. +- One short radio or NPC line. +- No enemy immediately on spawn. + +Validation: + +- Attempt id is active. +- Current body is alive. +- Instance id is linked to the attempt. + +### 5.3 Collapsed Service Corridor + +Purpose: + +- First combat and obstacle validation room. +- Teaches hit validation without visual chaos. + +Required content: + +- 2-3 Ash Strays. +- 1 line-of-sight blocker. +- 1 low obstacle or broken vehicle silhouette. +- Enough width for dodge and target selection. + +Optional content: + +- 1 supply crate with non-durable run loot. + +Success condition: + +- Player reaches the far marker. +- Enemies may be defeated or bypassed if the mission still feels readable. + +Failure risk: + +- Body takes injury. +- TIME exposure continues. + +### 5.4 Signal Split + +Purpose: + +- Main objective room. +- Creates one small decision before the boss. + +Required content: + +- Signal node interaction. +- Split route signage. +- One Signal Jack or equivalent ranged/support threat. + +Player options: + +| Option | Result | +| ---- | ---- | +| Interact and extract | Partial clear path becomes available. | +| Interact and push | Toll Plaza Arena opens or becomes marked. | +| Search side spur | Optional clue, memory tag, or safer boss tell. | + +Objective validation: + +- Signal proof requires range, line-of-sight, alive body, and active attempt. +- Unity cannot set `proof_collected` locally. +- The server returns objective event id and next allowed routes. + +### 5.5 Optional Memory Spur + +Purpose: + +- Shows how NPC intel and body stats can matter. +- Keeps the alpha from feeling like a flat hallway. + +Unlock examples: + +- Spark gave a route rumor. +- Whisper completed a Signal Sweep. +- Current body has enough Perception. + +Reward: + +- One memory clue or route warning. +- No major economy payout. +- Can add a safer tell before Tollkeeper Shell. + +Cut line: + +- Remove this room if the first Gate is too long. + +### 5.6 Toll Plaza Arena + +Purpose: + +- First elite/boss shell. +- Tests combat readability, server-owned objective state, and push-risk choice. + +Required content: + +- Tollkeeper Shell. +- 2 small adds or hazard pulses. +- Signal proof route behind or near the arena. +- Clear extraction marker after defeat. + +Arena requirements: + +- Circular or wide rectangle, not a maze. +- Clear boss telegraph space. +- Top-down silhouette readable at alpha camera distance. +- One low cover object only if it helps line-of-sight validation. + +### 5.7 Extraction Marker + +Purpose: + +- Ends the attempt and routes player back to The Garden outcome report. + +Rules: + +- Partial extraction requires `proof_collected`. +- Full extraction requires `proof_collected` and Tollkeeper defeat. +- Body death routes to death/reinhabitation instead of normal extraction. +- Disconnect handling can be conservative in alpha: mark attempt abandoned + unless server has already recorded proof and extraction. + +--- + +## 6. Encounter Actors + +### Ash Stray + +Role: + +- Basic melee pressure. + +Alpha behavior: + +```text +idle + -> acquire_target + -> approach + -> telegraph_short + -> strike + -> recover + -> reset_or_die +``` + +Requirements: + +- Low HP. +- Clear hit reaction. +- No complex pathing. +- Server-validated hit and death state. + +### Signal Jack + +Role: + +- Ranged or support pressure near signal equipment. + +Alpha behavior: + +```text +idle + -> keep_distance + -> aim_ping + -> fire_or_mark + -> reposition +``` + +Requirements: + +- Weak HP. +- Slower attack cadence than Ash Stray. +- Visual line points back to signal hazard. +- Can be cut if ranged combat is not ready. + +### Tollkeeper Shell + +Role: + +- Gate-bound authority pattern around access, toll, debt, and passage. + +Alpha behavior: + +```text +idle_guard + -> challenge_line + -> heavy_telegraph + -> heavy_strike + -> summon_or_pulse + -> vulnerable_window + -> repeat + -> defeated +``` + +Boss design rules: + +- One grounded line of dialogue is enough for alpha. +- Dialogue must not grant or deny rewards. +- The boss cannot rewrite mission state through LLM output. +- All damage, defeat, and clear flags are server-owned. + +Example boss line: + +```text +Passage was paid. Bodies were not. +``` + +--- + +## 7. Combat and Objective Boundaries + +Unity may: + +- render enemies, markers, UI, and local anticipation +- request attacks through validated action intents +- display server results +- play hit, miss, death, objective, and extraction feedback + +Unity may not: + +- grant SECOND +- set objective completion +- set boss defeat +- alter TIME +- decide body death +- write relationship or memory outcomes directly + +Nakama should own: + +- mission definition +- quest state +- objective flags +- reward brackets +- ledger writes +- memory and relationship summaries +- anti-repeat or prompt evidence metadata for NPC responses + +Fusion should own or validate: + +- movement and combat simulation +- target ids and hit timing +- range, cone, and obstacle checks +- enemy lifecycle inside the instance +- authoritative combat events + +--- + +## 8. Reward and Outcome Rules + +Alpha reward brackets: + +| Outcome | Reward Direction | Consequence | +| ---- | ---- | ---- | +| Partial extract | 180-240 SECOND | Proof returned, no Tollkeeper clear. | +| Full clear | 360-420 SECOND | Gate clear record and boss memory hook. | +| Body death | No normal reward claim | Body lost, reinhabitation flow, partial account knowledge only if already recorded. | +| Abandon before proof | No reward | Attempt abandoned, possible small relationship disappointment later. | + +TIME result: + +- The Gate should expose 6-10 minutes expected TIME pressure. +- Exact drain can be simulated first and server-owned later. +- Outcome report must show TIME spent or expected exposure once the runtime can + support it. + +Inventory result: + +- Run loot is temporary until extraction. +- Quest proof is objective state first, item second. +- No boss-body unlock in alpha unless a separate server-owned eligibility flag + exists. + +--- + +## 9. NPC and Relationship Hooks + +The Gate should feed back into named NPCs. + +| Hook | Trigger | Result Direction | +| ---- | ---- | ---- | +| Echo warning respected | Player extracts partial after proof | Echo trust or respect can rise. | +| Spark route clue used | Player uses safer clue or Memory Spur | Spark familiarity can rise. | +| Vell body warning ignored | Player enters with low TIME and returns injured | Vell concern, fear, or disapproval can rise. | +| Whisper signal read confirmed | Proof collected | Whisper memory records technical validation. | +| Iron repair scarcity helped | Player returns salvage or repair material | Iron respect can rise. | + +Relationship changes should be small in alpha. + +LLM NPCs may comment on outcomes, but the outcome report and ledgers must +already exist before NPCs react. + +--- + +## 10. UI and Feedback + +Required player-facing surfaces: + +| Surface | Required Fields | +| ---- | ---- | +| Mission Card | title, objective, TIME risk, reward range, recommended role, hazards, start/cancel | +| Gate HUD | current body, TIME, HP, energy, objective, partial/full clear state | +| Objective Toast | signal reached, proof collected, extract available, full clear available | +| Combat Feedback | target valid, hit, miss reason, enemy defeated, body injured | +| Extraction Prompt | partial extract, push deeper, full clear, body death fallback | +| Outcome Report | SECOND, TIME, injury, memory, relationship, ledger ids, next recommendation | + +Do not explain systems with long in-world text. Use short labels and let the +outcome report carry details. + +--- + +## 11. Audio and Visual Needs + +Minimum audio: + +- Gate entry pulse. +- TIME warning tick or low-time tone. +- Signal node hum. +- Ash Stray hit and death. +- Tollkeeper heavy telegraph. +- Extraction confirmation. +- Outcome report sting. + +Minimum visual: + +- Ash Underpass threshold. +- Broken transit route silhouette. +- Signal node prop. +- Readable hazard color. +- Tollkeeper Shell silhouette. +- Extraction marker. + +Visual identity: + +- Modern damaged infrastructure first. +- Gate distortion second. +- No medieval dungeon mood. +- No giant sci-fi portal room unless it still reads as broken Dayton transit. + +--- + +## 12. Implementation Packets + +### Packet G1: Mission Definition + +Output: + +- Server-owned `ash-underpass-signal` mission definition. +- Mission card fields. +- Entry validation rules. + +Verification: + +- Backend test proves mission definition exists. +- UI can read card fields without hardcoding all text locally. + +### Packet G2: Attempt Lifecycle + +Output: + +- Create attempt. +- Enter Gate. +- Abandon, partial extract, full clear, body death states. + +Verification: + +- Backend tests cover valid and invalid transitions. +- Attempt cannot claim reward twice. + +### Packet G3: Objective Interaction + +Output: + +- Signal node objective event. +- Optional clue flags. +- Partial extract availability. + +Verification: + +- Server rejects objective completion without active attempt and alive body. + +### Packet G4: Combat Slice + +Output: + +- Ash Stray and optional Signal Jack lifecycle. +- Tollkeeper Shell minimal state machine. +- Fusion/Nakama event boundary. + +Verification: + +- Play Mode evidence shows hit, miss, enemy defeat, objective, and extraction. + +### Packet G5: Outcome Consequence + +Output: + +- Outcome report payload. +- SECOND/TIME/injury/memory/relationship ledger rows. +- NPC reaction hook payload. + +Verification: + +- Recent gameplay ledger shows the attempt. +- Outcome report reads server payload. +- NPC reaction uses outcome data, not self-reported client text. + +--- + +## 13. Evidence Checklist + +Before calling the Gate slice ready: + +- [ ] Mission card screenshot with current body, TIME, risk, and reward. +- [ ] Attempt creation log or backend test evidence. +- [ ] Gate entry screenshot. +- [ ] First combat room screenshot or clip. +- [ ] Signal node objective screenshot. +- [ ] Partial extract screenshot. +- [ ] Full clear screenshot or documented cut if boss is not ready. +- [ ] Outcome report screenshot. +- [ ] Ledger rows for attempt, objective, reward, TIME, and relationship or + memory. +- [ ] Console check with no repeated errors. +- [ ] Public-safe evidence saved without provider secrets or raw private + PromptTrace. + +--- + +## 14. Cut Rules + +Cut first if schedule slips: + +1. Memory Spur. +2. Signal Jack. +3. Full Tollkeeper mechanics beyond one heavy telegraph. +4. Optional NPC clue effects. +5. Extra loot drops. + +Do not cut: + +- server-owned attempt id +- signal proof objective +- partial extraction +- outcome report +- no-client-authority rule +- body death or failed attempt path + +The first Gate can be small, but it must be accountable. +