# 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 -> GenerationScreen -> 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, 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 trigger a pulse. - Movement is a quick action and must update robot position without triggering a pulse. - Interact, repair, remedy, and heat shield are environment-changing actions and must trigger one animated pulse when accepted. - Activate reactor must be visually prominent when ready and should resolve immediately without requiring a wait or extra pulse. - 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. Pulse playback behavior: - During a pulse, animate the configured steps as one short cascade of hazard motion, leak growth, quenching, ignition, shorts, and readiness updates. - Disable conflicting action commands while pulse playback is running so the player cannot queue hidden actions into an unresolved environment state. - Present the final post-pulse state as the next decision point. - Do not make pulse length vary by action type, forecast outcome, or danger level. - Do not expose a normal campaign fast-forward loop; the player goal is to solve the cascade and activate the reactor as soon as a pulse leaves its needs fulfilled. ### 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, pulses, 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 pulse. - `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.