1  # GUNRPG Console UI - Pokemon Style
  2  
  3  ## Overview
  4  The GUNRPG console client has been redesigned with a retro Pokemon-style interface using the [hex1b](https://hex1b.dev) terminal UI library. The interface is optimized for an 80x43 character viewport and uses proper Hex1b widgets for authentic menu navigation.
  5  
  6  ## Features
  7  
  8  ### Pokemon-Style Aesthetic
  9  - Clean box-drawing borders with proper titles using hex1b's BorderWidget
 10  - List-based navigation with Up/Down arrow keys
 11  - Automatic selection indicators (►) managed by Hex1b theme
 12  - Native progress bars using hex1b's ProgressWidget
 13  - Status displays for operator information
 14  - Retro color scheme inspired by Pokemon Red/Crystal
 15  
 16  ### Navigation
 17  - **Up/Down Arrows**: Navigate menu items
 18  - **Enter/Space**: Select current item
 19  - **Tab**: Move focus between widgets (if multiple)
 20  - **Escape**: Return to previous screen
 21  - All navigation is handled by Hex1b's ListWidget - no manual cursor management
 22  
 23  ### Screens
 24  
 25  #### 1. Main Menu
 26  - Create new operator
 27  - Continue with existing operator
 28  - Exit application
 29  
 30  #### 2. Create Operator
 31  - Generate random operator names (Operative-XXXX format)
 32  - Create new operator profile
 33  - Returns to main menu
 34  
 35  #### 3. Base Camp
 36  - Displays operator status:
 37    - Name and XP
 38    - Health bar
 39    - Equipped weapon
 40    - Unlocked perks
 41    - Exfil streak
 42    - Current mode (Base/Infil)
 43  - Action menu (state-aware):
 44    - **Base Mode Actions:**
 45      - Change Loadout
 46      - Treat Wounds
 47      - Apply XP
 48      - Unlock Perk
 49      - Start Mission
 50    - **Infil Mode Actions:**
 51      - Continue Mission (goes to combat session)
 52      - Disabled actions with explanations
 53  
 54  #### 4. Mission Briefing
 55  - Shows infiltration warnings
 56  - Confirms mission start
 57  - Starts infil mode and creates combat session
 58  
 59  #### 5. Combat Session
 60  - Shows player and enemy stats side-by-side:
 61    - Health bars
 62    - Ammo count
 63    - Distance
 64    - Cover status
 65    - Movement state
 66  - Turn-by-turn combat advancement
 67  - **Automatic outcome processing when combat ends**
 68  - Returns to base camp when complete
 69  
 70  #### 6. Mission Complete
 71  - Shows combat outcome
 72  - Displays debriefing message
 73  - **Operator automatically returned to Base mode with XP applied**
 74  
 75  #### 7. Message Dialog
 76  - Generic popup for information and errors
 77  - Returns to previous screen
 78  
 79  ## State Machine Enforcement
 80  
 81  The UI respects the operator state machine:
 82  - **Base Mode**: Full access to loadout, wounds, XP, perks, and mission start
 83  - **Infil Mode**: Only mission continuation available; other actions disabled
 84  - **Combat Completion**: Automatically processes outcome via server-side validation
 85  - Invalid actions are clearly marked as unavailable
 86  - API calls only happen when actions are valid
 87  
 88  ## Technical Details
 89  
 90  ### Architecture
 91  - Uses hex1b declarative widget API with BorderWidget for proper borders
 92  - State management via `GameState` class
 93  - Screen-based navigation system
 94  - API integration via HttpClient
 95  
 96  ### Combat Outcome Flow
 97  1. Combat ends (player or enemy eliminated)
 98  2. Client calls `POST /operators/{id}/infil/outcome` with session ID
 99  3. Server loads combat session and computes deterministic outcome
100  4. Server applies XP, updates mode, and saves operator state
101  5. Client refreshes operator state and returns to Base mode
102  
103  This ensures outcomes are **server-authoritative** and cannot be manipulated by clients.
104  
105  ### Dependencies
106  - hex1b 0.79.0
107  - .NET 10.0
108  - GUNRPG Application layer DTOs
109  
110  ### UI Architecture
111  - **ListWidget**: Used for all menu navigation with OnItemActivated event handlers
112  - **BorderWidget**: Properly displays titles in border frames
113  - **ProgressWidget**: Native progress bars for health/status displays
114  - **VStackWidget/HStackWidget**: Layout containers for organizing content
115  - **TextBlockWidget**: Static text display
116  - **TextBoxWidget**: User input (operator name creation)
117  
118  ### Code Structure
119  All screens follow a consistent pattern:
120  1. Define menu items as string array
121  2. Create ListWidget with OnItemActivated handler
122  3. Use switch statement on ActivatedIndex for menu actions
123  4. Wrap content in BorderWidget with title
124  5. Use helper methods from UI class for common patterns
125  
126  ### API Endpoints Used
127  - `POST /operators` - Create operator
128  - `GET /operators/{id}` - Get operator state
129  - `POST /operators/{id}/infil/start` - Start mission
130  - `POST /operators/{id}/infil/outcome` - Process combat outcome (server-side validation)
131  - `GET /sessions/{id}/state` - Get combat state
132  - `POST /sessions/{id}/advance` - Progress combat
133  
134  ## Running the Console Client
135  
136  ```bash
137  # Start the API server (in one terminal)
138  cd GUNRPG.Api
139  dotnet run
140  
141  # Start the console client (in another terminal)
142  cd GUNRPG.ConsoleClient
143  dotnet run
144  ```
145  
146  The client defaults to connecting to `http://localhost:5209`. You can override this with the `GUNRPG_API_BASE` environment variable.
147  
148  ## Controls
149  
150  - **Arrow Keys / Tab**: Navigate between buttons
151  - **Enter / Space**: Select button
152  - **Ctrl+C**: Exit application
153  
154  ## Current Implementation
155  
156  ### Working Features
157  ✅ Operator creation with random name generation
158  ✅ Base camp with state-aware menus
159  ✅ Mission start with infil mode transition
160  ✅ Turn-based combat with stat display
161  ✅ **Automatic combat outcome processing**
162  ✅ **Server-side outcome validation (no client manipulation)**
163  ✅ **Operator mode transitions (Infil → Base after combat)**
164  ✅ Proper hex1b BorderWidget usage with titles
165  ✅ **ListWidget-based menu navigation (no manual ButtonWidgets)**
166  ✅ **Theme-managed selection indicators**
167  ✅ **Single primary focus widget per screen (CreateOperator uses TextBox + List with Tab focus switching)**
168  
169  ### Known Limitations
170  - Text input widget requires focus management (TextBoxWidget used in CreateOperator)
171  - Intent submission UI not implemented (complex multi-choice system)
172  - Manual testing requires TTY (terminal with proper input handling)
173  - **Synchronous event handlers**: hex1b's ListWidget.OnItemActivated handlers are synchronous, causing UI to freeze during HTTP calls (known framework limitation)
174  
175  ## Future Enhancements
176  
177  - Implement focus-aware text input for operator names
178  - Add intent submission UI for combat
179  - Add operator list/selection screen
180  - Add color theming (Game Boy Color palette)
181  - Add animation for health bars
182  - Add more detailed status displays