zfxaction26_2/TASKS.md

Reactor Maintenance Tasks

Godot Frontend Integration

The Godot frontend (src/ReactorMaintenance.Godot) has a complete UX scaffold (splash to main menu to campaign intro to level screen to win/loss overlays) and reusable controls (StateBadge, PrimaryButton, CellInspector, ForecastList, InventoryStrip, ConfirmDialog, OutcomeOverlay) but no connection to the simulation core. This section covers bridging the gap.

Phase 1: Simulation Bridge (Critical Path)

Goal: Connect LevelScreen to SimulationEngine so gameplay state flows between simulation and UI.

• Task 1.1: Create GameSession class

  • Location: src/ReactorMaintenance.Godot/Data/GameSession.cs
  • Wraps SimulationEngine and holds the current LevelState
  • Loads LevelState from JSON via LevelSerializer.Deserialize() using Godot FileAccess
  • Exposes current state properties: RobotPosition, GlobalState, Terrain, Surface, UndergroundLayers, Props, Leaks, Forecasts
  • Fires events on state changes: OnLevelStateChanged, OnRobotMoved, OnTurnAdvanced, OnLevelWon, OnLevelLost
  • Exposes action methods: MoveRobot, EndTurn, InteractProp, InteractLeak, ApplyHeatShield, ActivateReactor
  • Validates actions before committing (rejects invalid moves)
  • Handles level start snapshot for retry

• Task 1.2: Create LevelStateLoader helper

  • Location: src/ReactorMaintenance.Godot/Data/LevelStateLoader.cs
  • Static helper that takes a res://Data/Levels/... path
  • Uses Godot FileAccess to read JSON string
  • Calls LevelSerializer.Deserialize() and returns LevelState
  • Throws descriptive exceptions for missing files or schema errors
  • Supports both res:// and user:// paths

• Task 1.3: Wire LevelScreen to GameSession

  • Update LevelScreen.Configure() to accept GameSession instead of raw CampaignLevel
  • Replace placeholder grid with real viewport
  • Wire CellInspector.SetCellInfo() to display live selected cell data
  • Wire ForecastList.SetForecasts() to display live simulation forecasts
  • Connect action bar buttons to GameSession action methods
  • Update LevelHeader with live global state badge (Stable/Caution/Critical/Ready)
  • Update InventoryStrip with live remedy/heat shield counts

• Task 1.4: Create res://Data/Levels/ directory and level files

  • Create placeholder level files for the 3 campaign levels
  • Use Win2D editor to export v3 JSON schema for each level
  • Files: coolant_restart.json, fuel_bleed.json, black_start.json
  • Verify round-trip: load -> serialize -> deserialize -> validate

Phase 2: Grid Viewport Rendering (Critical Path)

Goal: Replace the grid placeholder with a functional, interactive tile-based viewport.

• Task 2.1: Create GridViewport control

  • Location: src/ReactorMaintenance.Godot/Controls/GridViewport.cs
  • Custom Control that renders the level grid via CanvasItem._draw()
  • Supports configurable tile size (default 48px)
  • Handles viewport scrolling and zoom
  • Exposes SelectedCell, RobotPosition, HoveredCell properties
  • Fires OnCellSelected, OnCellHovered, OnGridClicked signals

• Task 2.2: Implement terrain rendering

  • Draw floor tiles with graphite/steel palette per ART.md
  • Draw wall tiles with darker steel, reinforced silhouettes
  • Apply subtle hue shifts between adjacent floor plates (no checkerboard)
  • Support layer opacity rules (surface full / underground 25% or 50%)

• Task 2.3: Implement prop rendering

  • Draw props at cell centers with semantic colors
  • Show state indicators (enabled/disabled, producing/starved)
  • Use generated asset textures where available, fall back to procedural badges
  • Support prop highlight for selected cell

• Task 2.4: Implement robot marker

  • Draw robot sprite at current RobotPosition
  • Show direction indicator
  • Use maintenance_robot.png from Assets/Characters
  • Animate on position change (optional, low priority)

• Task 2.5: Implement hazard rendering

  • Draw surface hazards on affected floor cells
  • Use semantic colors: fuel (red slicks), coolant (blue-cyan), electricity (yellow arcs), heat (orange-white)
  • Show hazard intensity via saturation/opacity

• Task 2.6: Implement cell selection highlight

  • Draw selection rectangle around selected cell
  • Draw reachable/actionable hints on valid move targets
  • Support hover highlight on non-selected cells

• Task 2.7: Implement underground network visualization

  • Draw carrier-colored network lines between adjacent cells with positive flow
  • Fuel = red, Coolant = blue, Electricity = yellow
  • Render sources as large centered dots
  • Support layer toggle: show/hide each underground layer independently
  • Apply opacity rules per design doc

Phase 3: Action Input System

Goal: Enable player interaction with the simulation through grid input and keyboard.

• Task 3.1: Implement grid click-to-select

  • Left-click on grid cell -> select cell, update CellInspector
  • Right-click -> context menu for available actions (repair, interact, etc.)
  • Click on robot position -> select robot cell

• Task 3.2: Implement keyboard movement

  • WASD / Arrow keys -> move robot to adjacent floor cell
  • Validate against SimulationEngine.MoveRobot before committing
  • Show rejected movement as brief toast/negative feedback
  • Tab -> cycle focus between grid, inspector, action bar buttons

• Task 3.3: Implement action bar integration

  • Move button -> enter move mode (highlight reachable cells)
  • Interact button -> execute prop interaction at robot position
  • Repair button -> repair reachable leak at robot position
  • Trigger Win / Trigger Lose -> remove for release, keep for dev testing
  • Disable buttons when action is invalid; keep them inspectable

• Task 3.4: Implement Enter/Space action confirmation

  • Enter -> confirm current action (interact, repair, activate)
  • Space -> quick action (move to adjacent in facing direction)
  • Escape -> cancel current mode, deselect

Phase 4: UI Polish and Data Flow

Goal: Make all UI controls display live simulation data and feel responsive.

• Task 4.1: Complete CellInspector data binding

  • Display: position, terrain type, prop type, prop state
  • Display: surface hazards (type, amount, band)
  • Display: underground state (when all-seeing-eye active)
  • Update on every simulation step

• Task 4.2: Complete ForecastList data binding

  • Map EForecastKind values to display strings
  • Show turn offset (+1, +2, etc.) and severity band
  • Order from soonest to latest
  • Update on every simulation step

• Task 4.3: Complete InventoryStrip data binding

  • Display remedy counts (fuel/coolant/electricity remedy types)
  • Display heat shield count
  • Show depleted/empty states

• Task 4.4: Complete LevelHeader data binding

  • Display global state badge (Stable/Caution/Critical/Ready/Lost/Won)
  • Display reactor heat level with band coloring
  • Display campaign progress (Level X / Y)

• Task 4.5: Add turn transition feedback

  • Brief visual indicator when a turn is resolved
  • Show outcome of lengthy actions (prop toggled, leak repaired, etc.)
  • Toast/negative feedback for rejected actions

Phase 5: Testing and Verification

Goal: Ensure simulation -> Godot data flow is correct and reliable.

• Task 5.1: Write GameSession unit tests

  • Load level from JSON -> verify LevelState matches expected
  • Execute actions -> verify state mutations match simulation engine
  • Test retry restores start snapshot
  • Test invalid action rejection

• Task 5.2: Write LevelStateLoader tests

  • Load existing level files -> verify successful deserialization
  • Load missing file -> verify descriptive exception
  • Load malformed JSON -> verify schema error message

• Task 5.3: End-to-end integration verification

  • Run Godot editor, load campaign, play through one full level
  • Verify all props, leaks, hazards render correctly
  • Verify cell inspector shows accurate data
  • Verify forecasts match simulation output
  • Verify win/loss overlays trigger at correct simulation states

• Task 5.4: Verify Win2D to Godot level compatibility

  • Export a level from Win2D editor -> load in Godot frontend
  • Verify all terrain, props, underground data, robot state, and inventory transfer correctly
  • Verify simulation engine produces identical results regardless of source

Phase 6: Underground Layer Toggle (Medium Priority)

Goal: Allow the player to inspect underground networks when at an all-seeing-eye terminal.

• Task 6.1: Implement all-seeing-eye viewing mode

  • When robot is at an all-seeing-eye terminal, enable underground visibility
  • Show all three underground layers simultaneously with reduced opacity
  • Highlight the carrier of the active underground layer at full opacity

• Task 6.2: Implement per-layer underground toggle

  • Allow player to cycle through Fuel/Coolant/Electricity underground views
  • Each view shows only that carrier network at full opacity
  • Other layers at 25% opacity

Phase 7: Release Cleanup (Low Priority)

Goal: Prepare the Godot frontend for release.

• Task 7.1: Remove dev-only buttons

  • Remove Trigger Win and Trigger Lose buttons from action bar
  • Replace with End Turn / Wait button

• Task 7.2: Add loading state for level transitions

  • Show loading indicator when loading level JSON
  • Handle slow load gracefully

• Task 7.3: Export configuration

  • Verify Godot export template for Windows works
  • Test standalone build with all assets bundled