# V2 Platform Overlay Integration

Phase 72.21.1.11 adds a platform overlay integration surface for detecting
active native overlays, pausing gameplay while an overlay owns focus, and
restoring input focus when the overlay closes.
`FV2PlatformOverlayIntegrationPolicy` owns provider route coverage,
`FV2PlatformOverlayRuntimeState` captures current game focus and pause state,
and `FV2PlatformOverlayPlan` carries the gameplay response and optional
`ShowOverlay` platform SDK request.

## Events

`PlanPlatformOverlayTransition` supports:

- `QueryOverlayState` reads provider overlay state through the route's query
  command.
- `ShowOverlay` queues `EV2PlatformSdkRequestType::ShowOverlay` only after a
  user gesture and overlay permission.
- `OverlayActivated` records active overlay detection, suppresses gameplay
  input, and pauses the game if it is not already paused.
- `OverlayDeactivated` restores input focus and resumes gameplay if the overlay
  pause was active.
- `FocusLost` treats platform focus loss as overlay ownership and suppresses
  gameplay input.
- `FocusRestored` restores gameplay focus after the provider reports focus
  return.

## Provider Routes

| Provider             | Native overlay surface                  | Show command                         | Active/focus callback                                                       |
| -------------------- | --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
| Steamworks           | `ISteamFriends/ISteamUtils`             | `ISteamFriends::ActivateGameOverlay` | `GameOverlayActivated_t`                                                    |
| Epic Online Services | `EOS_UI`                                | `EOS_UI_ShowFriends`                 | `EOS_UI_AddNotifyDisplaySettingsUpdated`                                    |
| GOG Galaxy           | `galaxy::api::IUtils`                   | `galaxy::api::IUtils::ShowOverlay`   | `galaxy::api::IOverlayVisibilityChangeListener::OnOverlayVisibilityChanged` |
| PlayStation SDK      | `V2PlayStationSystemUiOverlayInterface` | `PsnOverlay.ShowSystemUi`            | `PsnOverlay.OnOverlayActivated`, `PsnFocus.OnRestored`                      |
| Xbox GDK             | `V2XboxGdkGameBarOverlayInterface`      | `XboxGameBar.ShowOverlay`            | `XboxGameBar.OnActivationChanged`, `XboxFocus.OnRestored`                   |

Console routes remain public stubs in `V2OnlineServices`. Proprietary
PlayStation and Xbox headers or symbols stay in restricted platform SDK modules.

## Rules

The default policy requires Steamworks, EOS, GOG Galaxy, PlayStation SDK, and
Xbox GDK route coverage. Each route must detect active overlay state, expose
focus callbacks, require a user gesture for explicit overlay opens, and pause
gameplay when the provider overlay becomes active.

Activation and focus-loss plans suppress gameplay input. Activation plans pause
gameplay unless it is already paused, in which case they hold the existing pause
state. Deactivation and focus-restored plans restore input focus and resume
gameplay when the current runtime state is paused. Platform API failures fail
closed instead of queuing overlay opens or trusting provider callbacks.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-platform-overlay-integration.py
```

The checker validates the C++ API, contract, automation spec, CI workflow, Horde
gate, documentation, and TODO evidence for Section 72.21.1.11.