Skip to content

GDD: Action Pivot — from tactical stealth to readable action-extraction

Overview

This GDD details the pivot defined in concept.md: Shadow Raiders keeps its extraction skeleton, visuals, and forgiving-death twist, and rebuilds the minute-to-minute play around fast, readable action — one thumb steers, one button acts, combat is automatic, stealth becomes pure positioning, raids shrink to a few minutes, and death flows straight into the next run. Unity is the shipping target of this pivot. The web prototype is revived as a time-boxed rule-validation vehicle: pivot rules and numbers are cheap-tested there first, then ported to Unity verbatim (the project's established pattern); web changes are disposable probes, not a maintained second product. See implementation-plan.md (draft, pending lead-designer approval) for the phased plan.

Why: the July 16–19 publisher test (docs/research/playtest-2026-07-telemetry.md) measured the problem — D1 retention 22.5%, tutorial completion 75.5% (seven ~95%-per-step gates whose losses compound), 74% churn inside biome 1, one 10-minute raid per session, and fail-rate spikes exactly where new content enters (hound at 1-2, boss at 1-5, rivals+Warden at 2-1). The concept doc diagnoses the causes — a pressure cliff after the tutorial, passive overlong fights, scarce visible rewards, raids as long as a whole session, and death that punishes instead of inviting a retry. Every mechanic below addresses one of those causes, and the plan's Phase-3 gate scores against that baseline.

Mechanics

Movement & input

  • Left thumb — floating virtual joystick (already shipped): direct steering, wall-slide, no autopilot. Unchanged.
  • Right thumb — the Action Button. One large button, short cooldown, launch version: dodge-dash — a quick burst in the current steer direction with a brief invulnerability window, usable through enemy telegraphs and projectiles. This revives the parked dodge-roll as a button (the swipe gesture stays retired). The button reads its cooldown on its face and pulses when a nearby enemy winds up a heavy attack — a soft "now!" cue.
  • No sprint, no stamina, no tap-to-target: those systems stay parked. Base move speed is tuned so steering feels lively without the Badlanders trap of outrunning all danger.

Combat

  • Fully automatic attacks (existing stance arbiter): ranged fire at the nearest visible enemy in range, melee when in the enemy's face. The mutual-sight rule ("you only fire once spotted") is removed — if the player can see it and it's in range, they fight it.
  • Fast, readable fights. Trash enemies die in a couple of seconds of focus; the current "prolonged-but-survivable" sponginess is retired. Heavier enemies keep their telegraphed wind-ups — the dodge-dash through a telegraph is the core skill check, and it's the one lesson the combat FTUE stage teaches.
  • Flank crit (the backstab, simplified). Any hit landed from outside the target's facing arc crits, with the existing hitstop freeze-frame and a distinct sound. No silence rules, no detection precondition, no once-only arming: strafe behind → crit, every time. This keeps positioning as the skill and the game's signature juicy beat, at zero cognitive overhead.
  • Enemy perception collapses to aggro. Enemies acquire the player by simple range + line-of-sight. Vision cones remain as art (they telegraph facing, which the flank crit makes meaningful) but the gradual-detection fill, suspect state, detection arcs/vignette, bush concealment, and echo-sense blips are parked. Alerted enemies chase, lose you on broken line-of-sight, give up and return — the existing chase/search behavior, minus the stealth-state machinery.
  • Noise stays as risk-per-loot. Cracking a chest, forcing the gate, and boarding a portal still ping nearby enemies to come looking (with the existing recruit cap). This is the one stealth-era system that survives untouched — it makes greed loud without asking the player to read anything.

Raid structure & pacing

  • Raid length: a few minutes (roughly half the current cap), so 2–3 raids fit a session. Early-biome maps stay compact.
  • The first real floor is a designed win. Dense, weak enemies; generous loot; the extraction portal visible early. Threat pressure, gear odds, and floor size are tuned so a fresh graduate ends their first raid extracted, richer, and un-scared.
  • One new pressure per floor (extending the FTUE's one-lesson rhythm into the ladder):
  • Floor 1 — pure loot-and-fight, no clock. Rival raiders present but placid.
  • Floor 2 — the closing extraction: partway through the raid, exits begin shutting down on a broadcast countdown; the last one stays open but far. This replaces the storm's hard "everyone dies" with spatial pressure — you're never killed by a timer, you're hurried.
  • Floor 3 — the vault/key race, as today.
  • Floors 4–5 — gatekeeper ramp and the boss, as today.
  • Rival raiders from raid 1. Believable, non-threatening bot rivals loot, wander, and extract from the first floor (the current rival AI, tuned gentle at low floors). Their kill reward — dropping their whole haul — is the raid's jackpot moment, as today. Meeting a rival is a choice (attack / ignore / cooperate), not an automatic fight — the neutral-by-default encounter model is specified in ../rival-interactions/rival-interactions-gdd.md (its Tier 0 ships with this pivot as a dependency of rivals-from-floor-1).

Guarded extraction — the descend portal as the finale fight

The existing guarded-portal mechanic stays, repurposed as the endgame beat. Under the stealth design, portal guards were an avoidance puzzle; under the action design, extraction is the raid's finale fight: clear the guards (a real fight at the new fast TTK), start boarding, and the loud board-start noise pulls a short wave to survive — a "hold the pad" defense of dodging telegraphs while the presence timer fills. With the storm hard-death and the detection dread gone, the guarded portal and the closing exits are the two systems carrying endgame tension — this is a promotion, not a leftover.

  • Guards ride the per-floor pressure ramp. The first floor's descend portal is unguarded or token-guarded (part of the designed win); guard count and tier scale up the ladder via the same from-floor gating as rivals/arrows/clock.
  • Closing exits funnel into the guarded fight. On later floors, the last-open pad can bias toward the guarded descend portal, so the closing pressure herds the player into one final contested fight — a deliberate climax, tuned, not accidental.
  • The descend/safe split is the greed dial. Safe exits bank the haul cheaply with no ladder progress; the descend portal advances the floor but is the guarded, louder one. "Push or leave" made spatial, at zero new-system cost.
  • Anti-cheese rules stay untouched: a hit stalls boarding, and force-boarding is denied mid-fight — a fast player cannot skip the finale by tanking the timer.
  • Rivals compose for free: the last open pad late in the raid is already a contested objective in the rival-interactions model, so a rival racing the player to the final guarded pad escalates through the normal warning → hostile flow. Guards, closing exits, and rival contest stack without new rules.

Death & retry

  • Death costs exactly the carried haul. No floor-ladder reset; the player re-attempts the same floor. Banked loot, gear, and biome progress are never touched. (Verified 2026-07-23: this is already the shipped behavior on both web and Unity — endRun and MetaLoopController keep all progression on death. The design intent stands; no build work is needed for this line, only for the retry flow below.)
  • The death screen leads with one huge "Raid again" button that drops the player straight into a fresh run of the same floor — target: under five seconds and two taps from death to moving again. The result details (what was lost, what was banked) are visible but secondary. (This is the real gap today: retry round-trips through a full scene reload and the lobby.)

Stealth systems — parked, not deleted

Per the branch convention, the gradual-detection model, suspect state, echo-sense, bush concealment, detection UI, and mutual-sight fire gate are gated behind flags and default off. The simulation code remains for a possible future "stalker mode" or enemy-specific reuse.

Five systems the pivot touches indirectly; each needs an explicit call. Recommended defaults:

  1. Fog & the sight-fairness invariant. Keep limited vision (it's part of the validated look) with a modest radius/zoom bump, and adopt the invariant: nothing may engage the player from beyond the player's own sight. Today several ranged enemies out-see the player's fog radius, and the only thing preventing beyond-sight shots is the mutual-sight fire gate — which this pivot removes. The invariant replaces that silent protection: clamp enemy engagement range to player sight (or raise player sight above the largest enemy sight). Threat arrows point at aggroed enemies from floor 1 — incoming-danger fairness, not the cut scouting layer.
  2. Weapons: keep magazine + reload, anchored as "one fight per mag." A magazine kills one trash enemy with margin (already nearly true at neutral tuning); reload is a between-fights beat that becomes an exposed punish window only when the player greedily pulls multiple enemies — reload as the risk-pricing of aggression, not friction. The four archetypes stay (the only build identity pre-roster; short fights make their differences more legible); the sniper's tiny magazine gets a pass under this rule. The steady-fire rtsMode fallback stays parked unless playtests read reload as pure friction.
  3. Healing: instant potion, no channel, no auto-regen. The rooted potion channel was designed for disengage-and-hide play; under strafe combat it fights the thumbs. Potion becomes instant (or a fraction-of-a-second non-blocking animation) on a small button in the right-thumb arc. No out-of-combat auto-regen: HP attrition across the raid is a core greed lever ("at 30% — push the vault or extract?"); if doomed-walk states show up in playtests, the fix is more potion drops, not regen.
  4. Combat-math re-anchor: TTK targets first, multipliers second. One named tuning task: write the TTK target table (trash ~1.5–2s · mid-tier ~3–4s · heavies ~6–8s with dash-answerable telegraphs · boss ~30–45s, likely via phases rather than raw HP), derive the multipliers from it, verify headless, feel-check on web. Keep the power-ratio damage clamp (it keeps the green/amber/red threat tags honest — worth more post-pivot). Shift enemy power-scaling toward HP and away from damage, and revisit the stretched enemy attack cadence — post-pivot deaths should come from readable, dodgeable hits that can actually threaten inside a short fight window.
  5. Gear meta: re-theme, don't restructure. Slots, stats, rarity math, and the blueprint economy stay untouched. Semantics change where stealth died: crit becomes flank-crit damage (the stat maps cleanly onto the pivot's positional payoff); the Stalker set re-themes to a flank/dash identity (its detectability bonus references a parked stat); stealth perks are replaced with action-legible ones — dash cooldown, reload speed, potion potency, and magnet radius (the most casual-visible perk available). Hunter and Bulwark survive as-is.

Consequential retirements (no decision needed, listed for explicit approval): the stamina model loses its last consumer (dodge moves to a cooldown) and is retired with the HUD ring; the backstab 🗡 tell and its grace rules (silent-opener fire lock, silence window, LOS re-arm) retire with the stealth opener — the tell may be repurposed as a simple "you're in the crit arc" indicator for the FTUE; bushes become decoration plus their speed perk; the chest-crack channel survives as the loud-exposure beat (tuned shorter); the minimap shows objectives (chests, exits, closing status) and no enemies; floor 1 gets a long soft time cap so an idle raid still ends.

Progression / economy

  • Banked progression is untouched: extract → haul banks to stash/gold/blueprints; gear equips and upgrades in the lobby; the biome ladder advances on the progression portal; the boss floor unlocks the next biome. The no-gear-loss wall stays absolute.
  • Loot frequency rises, banking stays gated. Raids should feel abundant — frequent, visible, recognizable drops vacuumed by the magnet — but everything is only kept by extracting. The greed decision ("push one more zone or leave now?") is the game's tension and must never be softened by mid-raid banking.
  • Gear stays the rare event, blueprints the steady drip (current economy intent, unchanged in shape) — but the first floors are tuned generous so the first sessions reliably produce a felt upgrade.
  • Collection sets (fast-follow, not launch). Each biome carries a themed set of collectible pieces found in raids; completing a set in the lobby album grants a permanent reward and a cosmetic flourish. Collection gives every raid a "one more piece" hook and gives the loot spill more recognizable star items. Seasonal rotation is a later option.
  • Difficulty follows power (existing enemy scaling), so extracted gear never makes floors trivial; the anti-snowball intent from docs/design/balance/player-progression.md stands.

UX

  • Orientation: portrait, unchanged. Joystick-left + Action-Button-right in the bottom third is the proven portrait two-thumb layout (Archero, Survivor.io); auto-aim means no second stick ever forces landscape. Portrait also matches the validated CPI creatives, the vertically-authored content, and the instant-retry loop (no rotation ritual). Revisit only if a future iteration becomes a genuine multi-skill hero game.
  • HUD: joystick (left), Action Button with cooldown face (right), HP bar, haul counter, minimap. Threat arrows appear only from floor 2. Detection vignette, stamina ring, and stealth glyphs are removed from the HUD.
  • Closing extraction: a raid-wide banner + minimap markers when exits begin closing; closed pads read visibly dead; the final pad is always marked.
  • Death flow: death beat (existing slow-mo/delay) → result card led by Raid again; secondary: haul lost / banked summary, lobby button.
  • Extraction flow: unchanged (walk onto pad, presence-board with visible progress).
  • Lobby: unchanged (loadout, upgrade, biome picker); the collection album is added behind its own tab when that phase lands.
  • FTUE rewrite — 3 stages replacing the current 7 (measured per-step completion is 93–98% — no step is broken, the 24.5% cumulative loss is the price of seven sequential gates; three gates at the same per-step rate ≈ 88%+ completion): ① move + auto-fight + Action Button; ② loot, magnet, extract; ③ flank crit + dodge through a telegraph. The stealth stages (Unseen, Heard) and the vault stage retire; the vault teaches itself on floor 3 via the existing key/gate nudges. The first-raid coach shrinks to rivals + closing-exits tips.

Visual identity

Unchanged assets, sharpened feedback: every kill pops loot with the existing spill/hop; flank crits get the hitstop + a heavier flash than normal crits; the Action Button dash gets a smear + afterimage; chest cracks keep the wobble + noise rings. Vision cones stay rendered (they're now the flank-crit UI). The "being noticed" vignette, detection arcs, and sonar blips are removed from render. Louder, more frequent reward feedback overall — the game should sound generous.

Scope

In (the pivot): Action Button dash · combat retune (fast TTK, flank crit, aggro-only perception) · closing-extraction pressure replacing the storm death · floor-by-floor pressure ramp · rivals from floor 1 · death → instant retry, no ladder reset · FTUE rewrite (3 stages) · HUD cleanup.

Fast-follow: collection sets + lobby album · Action Button variants (2–3 alternatives as loadout choice).

Out (explicitly): hero roster / characters with unique kits (open question — see concept); alliance/betrayal social mechanics; real PvP / networking; weight system (still deferred); in-run inventory triage (stays parked). Web-prototype work is allowed only as the Phase-0 rule-validation sprint (disposable probes, no parity or polish obligation — see the implementation plan); the shipping pivot itself is Unity-only.

ТЗ / tech spec

The pivot ships in the Unity project (unity/raiders); the web prototype hosts only the Phase-0 rule-validation probes (throwaway code — validated rules and values port into Unity). Existing GameConfig mirrors config.js group/key names; all new knobs follow that pattern so they surface in the tuning workflow.

  • Tunables (GameConfig):
  • New action group: dash cooldown, dash distance/duration, invulnerability window, wind-up pulse cue toggle.
  • combat: master flag for aggro-only perception (parks gradual detection / suspect state), flank-crit arc + multiplier (reuses the backstab values), retired sponge multipliers return to neutral.
  • map / extraction: shortened round length; closing-exits schedule (start time, interval, which pad closes last) replacing the storm-death as the default; storm stays as a flag for possible high-biome reuse.
  • spawn / prog: per-floor pressure gating (rivals-from-floor, arrows-from-floor, clock-from-floor), first-floor generosity (threat budget, gear odds).
  • meta: retry-flow toggle. (A death-ladder-reset flag is unnecessary — no-reset is already the shipped behavior on both platforms.)
  • Later: a collection group (set definitions per biome, drop weights).
  • Game systems:
  • PlayerController: Action Button input path reusing the parked Dodge implementation; removal of the mutual-sight gate in target acquisition.
  • EnemyController / DetectionModel: an aggro-only mode (range + LOS acquisition) that bypasses the fill/suspect pipeline behind the master flag; chase/search unchanged.
  • RaidController / extraction: closing-exits scheduler broadcasting close events; portal states already support open/closed.
  • MetaLoopController: "Raid again" fast path that rebuilds the run without returning to the lobby scene (floor re-attempt without ladder reset already ships).
  • FTUE stage assets: three new stage definitions; old stages retired from the sequence (assets kept).
  • UI / art:
  • Action Button widget (cooldown face, wind-up pulse) in the InGame HUD.
  • Closing-exits banner + minimap close markers; dead-pad visual state.
  • Result screen variant led by "Raid again"; HUD removal of stamina ring / detection vignette / sonar blips.
  • Dash smear/afterimage VFX; flank-crit flash variant. No new character art required.
  • Later: collection album screen + per-biome set icons.