Input & Interaction

Grids overlays support two input modes: passthrough (Alt-key) and exclusive capture. The mode determines whether game input (movement, camera, etc.) is blocked while interacting with an overlay.

Input Modes

Passthrough Mode (Alt-Key)

The default mode. Overlays are visible but non-interactive. Holding Alt enables cursor-based interaction while keeping game input active in the background. Best for HUD elements, notifications, and overlays where you want quick peek-and-interact.

Exclusive Capture Mode

For modal overlays like menus, dialogs, and search UIs where typing shouldn't move the character. When an overlay captures input exclusively, the player controller switches to UI-only input mode — all keyboard and mouse input goes to the overlay, none reaches the game.

When to use: Any overlay with text fields, search boxes, chat input, or complex interactions where WASD/mouse should not affect the game.

Using Input Capture

From C++ (creating overlays)

UWebOverlay* Overlay = Sys->CreateOverlay("my-menu", Url, 100);
Overlay->SetInteractive(true);
Overlay->SetCapturesInput(true);  // Blocks game input while this overlay is active

From JavaScript/TypeScript (at runtime)

import { grids } from '@grids/overlay-sdk';

// Request exclusive input capture (blocks game input)
grids.captureInput();

// Release exclusive input (game input restored)
grids.releaseInput();

The capture state is tracked globally by UWebOverlaySubsystem. If any visible and interactive overlay has bCapturesInput = true, the player controller switches to UI-only input mode. When the last capturing overlay is hidden, closed, or releases capture, game input is automatically restored.

Choosing the Right Mode

Implementation Details

Alt-Key System

The Alt-key logic lives in AGridsPlayerController:

1. Key down — Show mouse cursor, switch to GameAndUI input mode
2. Key up — Dismiss context menus, hide cursor, restore GameOnly input mode
3. Right-click while Alt held — Perform a line trace, check if the hit actor implements IContextMenuProvider, and open the context menu overlay via UContextMenuManager

Exclusive Capture System

Input capture is managed by the overlay subsystem with a delegate pattern:

1. UWebOverlay::SetCapturesInput(true) marks the overlay as input-capturing
2. UWebOverlaySubsystem::UpdateInputCaptureState() checks if any overlay is capturing
3. OnInputCaptureChanged delegate fires, notifying AGridsPlayerController
4. Controller switches to FInputModeUIOnly (capture) or FInputModeGameOnly (release)

Input Mapping

The system uses Unreal's Enhanced Input System:

• IMC_Default — Standard gameplay input (movement, camera, actions)
• IMC_MouseLook — Separate context for when cursor is active during Alt hold

Overlay Focus vs Input Capture

These are two separate concepts:

You can combine both: requestFocus() makes the overlay interactive, captureInput() additionally blocks game input.