zfxaction26_2/docs/UX.md

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

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:

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

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.
• 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, sprinkler suppression, evaporation, wet-electricity 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, sprinkler water, wet-electricity risk, 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/sprinkler water: blue
  • electricity: yellow
  • heat: orange or white-hot accent
  • 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 makes 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.