# V2 Input System Binding Configuration Guide

This guide covers `TODOS.phase-72.72.27.1.15`: the operator workflow for
authoring, reviewing, testing, and shipping input actions and binding
configuration in V2.

## Runtime Surface

The input system is configured through these stable artifacts:

- action catalog:
  `V2/ue/Content/V2/Input/Actions/InputActions_V2_ActionCatalog.json`
- action registry contract:
  `V2/ue/Content/V2/Input/Actions/InputActionRegistry_V2_Contract.json`
- binding system contract:
  `V2/ue/Content/V2/Input/Actions/InputBindingSystem_V2_Contract.json`
- mapping context catalog:
  `V2/ue/Content/V2/Input/MappingContexts/InputMappingContexts_V2_PlatformCatalog.json`
- binding UI contract:
  `V2/ue/Content/V2/UI/Settings/InputBindingUI_V2_Contract.json`
- persistence contract:
  `V2/ue/Content/V2/Input/Actions/InputBindingPersistence_V2_Contract.json`
- global remapping contract:
  `V2/ue/Content/V2/Input/Remapping/GlobalInputRemapping_V2_Contract.json`
- simultaneous devices contract:
  `V2/ue/Content/V2/Input/Actions/SimultaneousInputDevices_V2_Contract.json`
- input recording contract:
  `V2/ue/Content/V2/Input/Actions/InputRecordingForTesting_V2_Contract.json`
- haptic binding contract:
  `V2/ue/Content/V2/Input/Actions/HapticFeedbackBinding_V2_Contract.json`
- input debugging overlay contract:
  `V2/ue/Content/V2/UI/HUD/InputDebuggingOverlay_V2_Contract.json`

The source APIs are `UV2InputBlueprintLibrary`, `UV2UIBlueprintLibrary`,
`UV2InputConfigAsset`, `UV2SaveGame`, and `UV2PersistenceSubsystem`.

## Binding Configuration Flow

Use this order for every new gameplay action or binding change:

1. Add or update the action in the action catalog with a stable action id,
   display label, gameplay category, command tag, and default binding intent.
2. Register the action in the action registry so validation can reject unknown
   action ids before they reach mapping contexts, remapping profiles, or UI.
3. Add platform defaults to the binding slot table for keyboard and mouse, PC
   gamepad, PS5 DualSense, Xbox Series gamepad, Switch 2, and mobile touch when
   the action applies to that device family.
4. Place the action in the correct input mapping context. Context changes must
   preserve active context ids such as `Input.Context.OnFoot`,
   `Input.Context.Driving`, `Input.Context.Swimming`, `Input.Context.Menu`, and
   `Input.Context.Dialogue`.
5. Add binding UI rows and prompt icon metadata so players see the same action
   name, device token, and conflict status in settings and in HUD prompts.
6. Update persistence and global remapping coverage when the binding is
   player-configurable. Candidate profiles must validate before replacing the
   last known-good profile.
7. Add tests, contracts, and focused checker expectations before marking the
   task complete.

## Token Standards

Binding tokens are stable `FName` values, not localized labels and not hard
asset references. Keep tokens device-specific and deterministic:

- keyboard and mouse examples: `Keyboard.Spacebar`, `Keyboard.K`, `Mouse.Left`
- PC gamepad examples: `Gamepad.FaceButtonBottom`, `Gamepad.RightTrigger`
- DualSense examples: `DualSense.Cross`, `DualSense.R2`
- Xbox examples: `Xbox.A`, `Xbox.RightTrigger`
- Switch examples: `Switch.B`, `Switch.ZR`
- touch examples: `Touch.Virtual.Jump`, `Touch.Gesture.Swipe`

Display labels and prompt glyphs are derived from the platform/device catalog.
Do not store localized button copy in saved remap profiles.

## Contexts And Priority

Mapping contexts are mutually reviewable layers. Gameplay contexts own movement,
combat, traversal, and interaction actions. Menu and dialogue contexts own UI
navigation, confirm, cancel, and text-advance actions. A context change must
declare priority, activation condition, supported platforms, and fallback
behavior when a device is missing.

When two contexts can be active, the higher-priority context must either consume
the action explicitly or pass through to the lower context. Do not rely on
undefined ordering between platform defaults.

## Remapping And Persistence

Per-player remaps use `FV2GlobalInputRemapProfile` and
`FV2InputBindingPersistenceRecord`. The remap flow is candidate-first:

- copy the last valid profile
- apply the requested override
- resolve effective bindings against the slot table
- reject duplicate primary or secondary tokens
- persist only the validated profile
- restore the profile before gameplay on startup

Rejected remaps must not alter save data, startup snapshots, UI rows, or active
runtime bindings.

## Binding UI Requirements

Every player-facing binding row must expose:

- action id and display name
- current primary and secondary device tokens
- default primary and secondary device tokens
- platform and control scheme
- conflict state and overwrite confirmation state
- reset-to-default behavior
- screen-reader-safe row summary

The UI must use the same binding slot table and conflict detector as the runtime
resolver. Settings screens must not implement a separate binding model.

## Testing And Debugging

Use deterministic fixtures for input verification:

- `FV2TestInputRecordingStream` records and replays exact frame input.
- `FV2SimultaneousInputDeviceState` verifies last-input-wins prompt switching.
- `FV2HapticFeedbackBindingCatalog` proves action-to-haptic binding output.
- `FV2InputDebuggingOverlaySpec` shows raw input, processed input, active
  context, current bindings, and combo state in a gameplay-inert developer
  overlay.

For binding failures, capture raw and processed samples, the active context id,
the resolved slot table row, the current remap profile id, and the conflict
reason before changing data.

## Review Checklist

- Action ids, command tags, and binding tokens are stable.
- Every platform-specific default is either authored or intentionally omitted by
  contract.
- Mapping context priority is explicit.
- Binding UI rows use runtime resolver data.
- Conflicts are rejected before persistence.
- Startup restore applies before gameplay.
- Input recording and the input debugging overlay cover the changed path.
- CI, Horde, and the focused checker reference the guide and contract.

## Verification

Run these checks after changing input actions or binding configuration:

```bash
python3 V2/ue/Tools/check-v2-input-system-documentation.py
python3 V2/ue/Tools/check-v2-input-action-registry.py
python3 V2/ue/Tools/check-v2-input-binding-system.py
python3 V2/ue/Tools/check-v2-input-mapping-contexts.py
python3 V2/ue/Tools/check-v2-input-binding-ui.py
python3 V2/ue/Tools/check-v2-input-binding-persistence.py
python3 V2/ue/Tools/check-v2-global-input-remapping.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m py_compile V2/ue/Tools/check-v2-input-system-documentation.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Input/Documentation/InputSystemBindingConfigurationGuide_V2_Contract.json
```

Automation coverage:

- `V2.Input.Module`
- `V2.UI.Module`
- `V2.Persistence.Module`
- `V2.Persistence.ProfileSave.AssetContract`

## Horde Gates

- `input-system-doc-source-present`
- `input-system-doc-action-registry`
- `input-system-doc-binding-configuration`
- `input-system-doc-remapping-persistence`
- `input-system-doc-debugging-testing`
- `input-system-doc-ci-wired`