From ff8ee32c9a3e695775e988e8a29bdf3be29322b6 Mon Sep 17 00:00:00 2001 From: Frank Tovar Date: Tue, 12 May 2026 20:39:07 +0200 Subject: [PATCH] Add Godot UX blueprint --- docs/UX.md | 347 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 docs/UX.md diff --git a/docs/UX.md b/docs/UX.md new file mode 100644 index 0000000..d4bcdc2 --- /dev/null +++ b/docs/UX.md @@ -0,0 +1,347 @@ +# Reactor Maintenance UX Blueprint + +This document is the Godot implementation blueprint for the player-facing frontend. It describes scene responsibilities, control composition, navigation flow, and the minimum data concepts needed to populate the UI. It is not a final art direction document. + +## UX Goals + +- Put the level grid and current reactor state at the center of play. +- Make every simulation state readable before the player commits to a lengthy action. +- Keep menu flow short: splash, main menu, mode selection, level, outcome, next action. +- Treat campaign as a linear chain of handcrafted levels with names and short flavor text. +- Let players retry a lost level from its starting state and advance from a won level to the next campaign level. + +## Scene Flow + +```text +SplashScreen + -> MainMenu + +MainMenu + -> New Campaign -> CampaignIntro or LevelScreen + -> Continue Campaign -> LevelScreen + -> Play Random Level -> LevelScreen + -> OptionsScreen + -> TutorialScreen + +LevelScreen + -> LoseOverlay -> Retry Level | MainMenu + -> WinOverlay -> Next Level | MainMenu + -> GameOverScreen + -> GameWonScreen + +GameOverScreen + -> Retry Current Level | MainMenu + +GameWonScreen + -> MainMenu +``` + +Use one scene navigation service or autoload to own transitions. Individual screens emit intent signals such as `NewCampaignRequested`, `RetryRequested`, or `NextLevelRequested`; they should not load unrelated scenes directly. + +## Shared Runtime Concepts + +### Campaign Manifest + +Represent campaign content as an ordered list. The exact storage format can be a Godot `Resource`, JSON file, or C# model, but the UI should receive these fields: + +- `Id`: stable level identifier. +- `Name`: player-facing level name. +- `FlavorText`: one or two short lines of lore shown before the level starts and after menu selection. +- `LevelPath`: path or key used to load serialized simulation level data. + +The first implementation can ship a single manifest for the default campaign. Branching paths, unlock maps, and difficulty variants are out of scope. + +### Session State + +The frontend session should track: + +- current mode: campaign, random level, or tutorial, +- current campaign index when in campaign mode, +- current level start snapshot for retry, +- current mutable level state during play, +- whether a continue save exists, +- last outcome: won, lost, campaign complete, or abandoned. + +Retry always restores the current level start snapshot. Continue campaign resumes the last saved campaign index and mutable level state if available. + +## Scene Blueprints + +### SplashScreen.tscn + +Purpose: a short branded entry point before the main menu. + +Recommended root: `Control`. + +Controls: + +- `CenterContainer` +- `VBoxContainer` +- title label: `Reactor Maintenance` +- small status label for build/version text if available + +Behavior: + +- Show for roughly 1-2 seconds. +- Any confirm, cancel, click, or tap skips immediately to `MainMenu`. +- Do not block on loading campaign data unless a clear loading label is shown. + +### MainMenu.tscn + +Purpose: primary navigation. + +Recommended root: `Control`. + +Controls: + +- title label: `Reactor Maintenance` +- vertical command stack: + - `New Campaign` + - `Continue Campaign` + - `Play Random Level` + - `Options` + - `Tutorial` +- small footer for version or build label + +Behavior: + +- `Continue Campaign` is disabled when no continue state exists. +- `New Campaign` starts at campaign index `0`; if a save exists, confirm replacement before overwriting. +- `Play Random Level` loads a single non-campaign level. It can select from authored levels until random generation exists. +- `Options` and `Tutorial` return to this screen. + +### CampaignIntro.tscn + +Purpose: optional lightweight introduction before the first campaign level or before each level. + +Recommended root: `Control`. + +Controls: + +- level name label +- flavor text label +- `Begin` button +- `Back` button when entered from a menu + +Behavior: + +- For a compact first pass, this may be embedded as a modal panel inside `LevelScreen`. +- The text should be short enough to read quickly and should not explain mechanics that belong in tutorial content. + +### LevelScreen.tscn + +Purpose: core gameplay screen. + +Recommended root: `Control`. + +Suggested layout: + +```text +LevelScreen + MarginContainer + VBoxContainer + LevelHeader + HSplitContainer + GridViewport + InspectorPanel + ActionBar + OverlayLayer +``` + +Primary controls: + +- `LevelHeader` + - level name + - campaign progress label such as `Level 2 / 8` + - global state badge: `Stable`, `Caution`, `Critical`, `Ready` + - reactor heat or readiness summary +- `GridViewport` + - visual grid + - robot marker + - terrain, props, leaks, hazards, and optional underground overlay + - selected cell highlight and reachable/actionable hints +- `InspectorPanel` + - selected cell coordinates + - terrain and prop summary + - underground values when visible through terminal access + - visible hazards with safe/caution/critical bands + - forecast warnings +- `ActionBar` + - contextual action buttons: move, interact, repair, remedy, heat shield, wait, activate reactor + - disabled buttons must show why the action is unavailable +- `InventoryPanel` + - fuel neutralizer count + - coolant neutralizer count + - electricity neutralizer count + - heat shield count + +Behavior: + +- Selection and inspection are quick actions and must not advance the simulation. +- Movement is a quick action and must update robot position without advancing the turn. +- Interact, repair, remedy, heat shield, wait, and activate reactor are lengthy actions and must resolve one simulation step when accepted. +- Invalid actions should produce a short refusal message and not mutate level state. +- When the level state becomes `Lost`, show `LoseOverlay`. +- When the level state becomes `Won`, show `WinOverlay`. +- When the reactor is ready, make `Activate Reactor` visually prominent but keep other valid actions available. + +### LoseOverlay.tscn + +Purpose: immediate failure response while preserving context. + +Recommended root: `PanelContainer` or `CanvasLayer` child. + +Controls: + +- title label: `Level Lost` +- short cause label from the terminal state or latest failure message +- `Retry Level` +- `Main Menu` + +Behavior: + +- Pauses input to the grid behind it. +- `Retry Level` reloads the current level from the start snapshot. +- `Main Menu` abandons the current run after confirmation if unsaved progress would be lost. + +### WinOverlay.tscn + +Purpose: immediate success response and transition to the next level. + +Recommended root: `PanelContainer` or `CanvasLayer` child. + +Controls: + +- title label: `Reactor Online` +- level completion text +- `Next Level` when another campaign level exists +- `Finish Campaign` when this was the final campaign level +- `Main Menu` + +Behavior: + +- Saves campaign progress before presenting the next-level command. +- `Next Level` loads the next handcrafted campaign level and shows its name and flavor text. +- In random level mode, replace `Next Level` with `Play Another` or `Main Menu`. + +### GameOverScreen.tscn + +Purpose: full-screen campaign failure or abandoned-run endpoint. + +Recommended root: `Control`. + +Controls: + +- title label: `Game Over` +- summary label with the failed level name +- `Retry Current Level` +- `Main Menu` + +Behavior: + +- Use this when leaving the level context after a loss, not for the immediate in-level failure modal. +- Retry uses the same start snapshot rules as `LoseOverlay`. + +### GameWonScreen.tscn + +Purpose: full-screen campaign completion endpoint. + +Recommended root: `Control`. + +Controls: + +- title label: `Campaign Complete` +- short final lore text +- completed level count +- `Main Menu` + +Behavior: + +- Reached after winning the final handcrafted campaign level. +- Clears any in-progress continue marker or marks campaign complete. + +### OptionsScreen.tscn + +Purpose: global settings. + +Recommended root: `Control`. + +Controls: + +- audio sliders +- fullscreen toggle +- UI scale selector if supported +- color/accessibility toggles when implemented +- `Back` + +Behavior: + +- Changes apply immediately where practical. +- Persist settings separately from campaign progress. + +### TutorialScreen.tscn + +Purpose: teach interaction grammar before or outside campaign. + +Recommended root: `Control`. + +Controls: + +- tutorial topic list +- content panel +- `Start Tutorial Level` +- `Back` + +Behavior: + +- Keep tutorial text focused on action economy, hazards, forecasts, remedies, and reactor activation. +- Tutorial level can reuse `LevelScreen` with a tutorial mode flag and guided prompts. + +## Reusable Controls + +- `PrimaryButton`: consistent command button style and focus behavior. +- `StateBadge`: color-coded label for `Stable`, `Caution`, `Critical`, `Ready`, `Lost`, and `Won`. +- `LevelHeader`: level metadata, global state, and campaign progress. +- `CellInspector`: selected cell details, visible hazards, prop state, underground details when available. +- `ForecastList`: ordered warnings from soonest to latest turn. +- `InventoryStrip`: remedy and heat shield counts. +- `OutcomeOverlay`: shared base layout for win and loss overlays. +- `ConfirmDialog`: save overwrite, abandon run, and return-to-menu confirmations. + +Keep repeated controls as separate scenes so the level screen, tutorial, and overlays can reuse them without duplicating layout logic. + +## Input And Focus + +- Support mouse and keyboard from the first implementation. +- Confirm activates the focused button or selected contextual action. +- Cancel closes overlays or returns to the previous screen when safe. +- Arrow keys or WASD can move the robot when the level grid has focus. +- Tab cycles between grid, inspector, action bar, and menu buttons. +- Disabled commands must remain inspectable by focus or hover so the player can read why they are unavailable. + +## Visual Language + +- The game should feel technical, readable, and tense, not decorative. +- Use restrained panels and clear hierarchy: grid first, status second, supporting details third. +- Color roles: + - fuel: red + - coolant: blue + - electricity: yellow + - heat: orange or white-hot accent + - safe: neutral or green + - caution: amber + - critical/lost: red + - ready/won: bright green or white +- Do not rely on color alone; pair colored states with text labels or icons. + +## Implementation Acceptance Checklist + +- Every scene has one clear root responsibility and emits navigation intent instead of directly owning campaign policy. +- The main menu exposes all requested buttons. +- Campaign levels show `Name` and `FlavorText`. +- Lost levels can be retried from the original starting snapshot. +- Won levels can advance to the next campaign level. +- Final campaign win reaches `GameWonScreen`. +- Full failure endpoint reaches `GameOverScreen`. +- The level screen distinguishes quick actions from lengthy actions. +- Forecasts, inventory, selected cell inspection, and global level state have dedicated UI space. +- Documentation stays aligned with `docs/design.md` when simulation rules change.