362 lines
12 KiB
Markdown
362 lines
12 KiB
Markdown
# 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, 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.
|