# SS_UIManager — Game Instance Subsystem

**Parent Class:** `UGameInstanceSubsystem`
**Dependencies:** [`GI_GameFramework`](../01-core/04_GI_GameFramework.md)
**File:** `SS_UIManager`

---

## Purpose

The central UI orchestration subsystem. Owns all full-screen menu widgets (MainMenu, PauseMenu, Settings, Inventory, Journal) and manages their visibility, stacking, and transitions. In-world HUD widgets are owned by [`WBP_HUD`](33_WBP_HUD.md) directly.

---

## Responsibilities

- Create and cache all full-screen menu widget instances on subsystem Init
- Manage a navigation stack (MenuStack) for push/pop/replace menu transitions
- React to `E_GamePhase` changes from [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) to auto-show/hide menus
- Provide a static-style accessor pattern via [`FL_GameUtilities`](../01-core/02_FL_GameUtilities.md)`::GetUIManager`
- Route input mode changes (GameOnly → UIOnly → GameAndUI) when menus open/close
- Broadcast menu open/close events for other systems to react

---

## Variables

| Name | Type | Description |
|------|------|-------------|
| `MenuWidgets` | Map (`E_MenuType` → Widget) | Cached instances of all menu widgets |
| `MenuStack` | Array of `E_MenuType` | Navigation history for back-stack |
| `ActiveMenu` | `E_MenuType` | Currently visible full-screen menu (None = HUD only) |
| `bInputModeUI` | Bool | Are we in UI-only input mode |
| `HUDWidget` | `WBP_HUD` | Reference to root HUD (created separately) |

---

## Enums

### `E_MenuType`

| Value | Description |
|-------|-------------|
| `None` | No menu active (game view) |
| `MainMenu` | Title screen |
| `PauseMenu` | In-game pause |
| `SettingsMenu` | Audio/Graphics/Controls/Accessibility |
| `InventoryMenu` | Full inventory screen |
| `JournalMenu` | Journal and documents viewer |
| `SaveLoadMenu` | Save/load slot selection |
| `LoadGameMenu` | Load from title screen |
| `DialogueMenu` | Dialogue choice UI |
| `ContainerMenu` | Container search/loot UI |
| `DeathScreen` | Game over / death screen |

---

## Functions / Events

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `Initialize` | — | — | On subsystem init; creates all cached menu widgets (not visible) |
| `ShowMenu` | MenuType: `E_MenuType` | — | Shows a menu, pushes previous menu to stack, updates input mode |
| `HideMenu` | — | — | Hides current menu, pops stack, restores input mode |
| `PushMenu` | MenuType: `E_MenuType` | — | Pushes menu, stores current on stack (for sub-menus) |
| `PopMenu` | — | — | Returns to previous menu from stack |
| `ReplaceMenu` | MenuType: `E_MenuType` | — | Replaces current menu without stack history |
| `ClearToHUD` | — | — | Empties stack, hides all menus, shows HUD only |
| `IsMenuOpen` | MenuType | Bool | Checks if a specific menu is currently shown |
| `GetTopMenu` | — | `E_MenuType` | Returns current top of stack |
| `SetInputModeUI` | bUIOnly: Bool | — | Switches between GameOnly and GameAndUI input modes |
| `GetHUD` | — | `WBP_HUD` | Returns root HUD reference |

---

## Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|------------|
| `OnMenuOpened` | MenuType: `E_MenuType` | Any menu becomes visible |
| `OnMenuClosed` | MenuType: `E_MenuType` | Any menu is hidden |
| `OnInputModeChanged` | bUIOnly: Bool | Input mode switches |

---

## Blueprint Flow — ShowMenu Logic

```mermaid
flowchart TD
    A[ShowMenu Called] --> B{Menu already visible?}
    B -->|Yes| C[Do nothing / return]
    B -->|No| D[Push current ActiveMenu to MenuStack]
    D --> E[Set ActiveMenu = NewMenuType]
    E --> F[Create widget if not cached]
    F --> G[Add to viewport]
    G --> H[Set input mode to UIOnly]
    H --> I[Broadcast OnMenuOpened]
    I --> J[Pause game if MenuType is pause-capable?]
```

---

## Communications With

| Target System | Method | Why |
|--------------|--------|-----|
| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | Dispatcher (`OnGamePhaseChanged`) | Auto-hide menus during cutscenes/loading |
| [`WBP_HUD`](33_WBP_HUD.md) | Direct reference | Controlled hide/show alongside menus |
| [`PC_CoreController`](../02-player/) | Direct | Input mode changes routed through controller |
| All menu widgets | Direct (cached references) | Show/hide/set data |

---

## Reuse Notes

This subsystem is project-agnostic. Add new `E_MenuType` values per project. The widget caching pattern prevents repeated construction. The stack-based navigation handles any menu depth.