Fighting Game · Guides & deep dives

V2 Input System Binding Configuration Guide

The input system is configured through these stable artifacts:

10sections4 minread
Markdown source
On this page

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