Add Godot UX blueprint
This commit is contained in:
347
docs/UX.md
Normal file
347
docs/UX.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# 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 -> 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.
|
||||
Reference in New Issue
Block a user