# 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, 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.
