Shop Overhaul — Main-Menu Entry, Death-Flow Split, Categorised Multi-Level UI — Design

Shop Overhaul — Main-Menu Entry, Death-Flow Split, Categorised Multi-Level UI — Design

Status: draft for review · Date: 2026-06-28 Sequence: independent of the spawn/dash work; must land before the drone shop trees (the drone system adds a big shop section that needs this structure). Good slot: after biomass spawning, before/with the drone overhaul. Touches: ui/meta_shop_panel.gd, ui/start_menu.gd, the game-over flow in main.gd, ResultsPanel, bible.json meta_upgrades (+ a category field). No /sim changes → no determinism impact (meta upgrades already apply outside the sim).

Problems being fixed

1. The shop is the death screen today (MetaShopPanel doubles as game-over) — you can only shop after dying, and the screen conflates “you died” with “spend gold.”
2. The shop is a single flat grid — overloaded and getting worse as drones/weapons grow.
3. No way to shop from the main menu.

Flow changes

Shop is reachable from three places, standalone (decided)

• Start menu: a SHOP entry. Back returns to the start menu.
• In-run pause menu: a Shop button — spend banked gold mid-run; closing returns to the pause menu (the run stays paused). (decided: mid-run shop allowed.)
• Death (crystal/survival): the game-over screen becomes a Results screen (below), whose Shop button opens it and returns on close.

New Results screen on death

Run summary (time, level, kills, gold earned, banked total) + three buttons:

• Redeploy — restart the same mode immediately (the current “Play Again”).
• Shop — open the standalone shop, then come back here.
• Main Menu — return to the start menu.

(Story victory keeps its own ResultsPanel.show_victory; this is the survival/crystal death screen.)

Categorised, multi-level shop

Two levels

• Root: a row/grid of category tiles + a header showing banked gold. Pick a category.
• Category view: the upgrade cards for that category only (the existing card UI, scoped), buy here, Back to the root. tvOS-safe focus nav at both levels (mirrors the existing panels).

Proposed categories (open for your input — see bottom)

Each meta_upgrade gets a category field in bible.json (data-driven; the shop groups by it, so new upgrades just declare a category):

Category	What’s in it
Pilot	Survivability + mobility: max HP (vitality), armor (bulwark), move speed (swiftness), fire rate (haste), dash/thrusters.
Drones	Drone slots, class unlocks, per-class attribute trees. Absorbs the current decoy unlocks/upgrades. The biggest section once the drone system lands.
Arsenal	Weapon unlocks (scatter, future weapons) + any future weapon meta-upgrades.
Utility	Economy / QoL: pickup radius (greed), and future gold/XP boosts. (Could fold into Pilot if you’d rather 3 categories.)

Card depth

Cards keep showing name / effect / cost / current level / “OWNED” / “MAXED” (already supported). The multi-level split is what removes the overload — each screen shows one coherent group.

Architecture

• MetaShopPanel → a standalone, reusable shop opened with open_shop(meta, defs, return_to) where return_to is a callback (start menu or results). It renders the root category view, drills into a category, and emits closed when backed out. Buy logic + persistence unchanged (MetaState.buy + MetaStore.save_state).
• A new/!split ResultsPanel (or extend the existing one) for the survival/crystal death screen with the 3 buttons; its Shop button opens MetaShopPanel and restores focus on close.
• StartMenu gains the SHOP card → opens MetaShopPanel with return_to = show start menu.
• PauseMenu gains a Shop button → opens MetaShopPanel with return_to = pause menu (run stays paused).
• main.gd game-over branch: show the Results screen instead of the shop directly.
• Categories are derived from the category field; the root view lists categories that have ≥1 upgrade (so empty categories — e.g. Drones before that system lands — auto-hide).

tvOS / UX

• Both shop levels use the established debounced joypad/d-pad focus nav (Siri Remote + controller), centered layout (overscan-safe), and the procedural upgrade icons already in ui/shop_icons.gd.
• Back button (B / Esc) steps category→root→close, so it’s never a dead end.

Determinism

None — pure UI + meta-progression (applied outside the sim, like today). No baseline impact.

Decisions (resolved 2026-06-28)

1. Categories: Pilot / Drones / Arsenal / Utility (4 top-level sections).
2. Death-screen buttons: Redeploy / Shop / Main Menu (no Quit — Apple TV home exits on tvOS).
3. Shop reachable mid-run from the pause menu too (start menu + pause + death), so banked gold can be spent mid-run.