# 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. - Keep one-action setups in guided tutorial content; campaign levels should present at least two plausible lengthy interventions with different pulse outcomes. ## 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, sprinkler water, and wet-electricity risk with safe/caution/critical bands - forecast warnings - `ActionBar` - contextual action buttons: move, interact, toggle isolation valve, activate sprinkler valve, 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, isolation valve toggles, sprinkler valve activation, 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. - Before committing a lengthy action, the selected action state should expose the forecasted pulse consequence in plain terms such as isolated leak, restored pressure, downstream starvation, hazard growth, or reactor ready. Pulse playback behavior: - During a pulse, animate the configured steps as one short cascade of hazard motion, leak growth, quenching, evaporation, ignition, electrical conduction, and readiness updates. - Isolation valve toggles must visibly mark the affected underground branch, show stopped or restored pressure flow, and warn when downstream consumers or reactor feed will starve. - Sprinkler valve activation must visibly release blue sprinkler water at authored outlet cells and show the affected coolant service area losing pressure. - Evaporation must be communicated through shrinking wet overlays and stronger steam/cooling feedback on hot cells. - Wet cells that can spread electricity must use a distinct warning treatment so the player can distinguish helpful suppression water from dangerous electrified water. - 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, isolation valves, sprinkler suppression, evaporation, wet-electricity hazards, forecasts, remedies, and reactor activation. - Tutorial level can reuse `LevelScreen` with a tutorial mode flag and guided prompts. - A tutorial level may demonstrate a single safe lengthy action. The first campaign level should not be a single-action demonstration; it should ask the player to choose between service restoration, isolation, repair, or activation timing. ## 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, sprinkler water, wet-electricity risk, prop state, isolation valve branch impact, 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/sprinkler water: blue - electricity: yellow - heat: orange or white-hot accent - isolated branch: muted carrier color with a broken-flow or valve marker - wet-electricity risk: yellow over blue or a distinct charged-water pattern - 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. - The level screen previews selected lengthy-action pulse consequences before commitment. - The level screen makes isolation valve branch effects, sprinkler valve outlets, evaporation, and wet-electricity risk readable before and after a pulse. - Forecasts, inventory, selected cell inspection, and global level state have dedicated UI space. - Documentation stays aligned with `docs/design.md` when simulation rules change.