Binding resolution
Understand how the Input System determines which controls on the connected devices each action uses.
Understanding binding resolution helps you predict which controls drive an action as devices connect and disconnect, query those controls from code, and handle actions that the Input System cancels when it updates their controls.
Why the Input System resolves bindings
A binding doesn't reference a control directly. Instead, it has a control path: a string that describes where to find the control or controls that the action uses. For example, the control path <Gamepad>/buttonEast refers to the right action button on any connected gamepad. A simple binding has one control path, and each part of a composite binding has its own.
A control path can refer to a specific device or to a device type, and can contain wildcard characters, so it can match different controls depending on which input hardware is connected. The Input System therefore resolves the bindings at runtime to determine which controls on the connected devices are valid for each action. Resolution happens the first time the action needs its controls, for example, when you enable the action or read its controls property.
What happens during resolution
The Input System resolves all the bindings in an action map at once. For each binding, it does the following:
- Skips the binding if its control path is empty, or if a binding mask excludes it. For example, a binding mask can limit an action map to the bindings in one control scheme.
- Searches for controls that match the control path. If the action map or its asset has a device list, the Input System searches only those devices. Otherwise, it searches all connected devices with
InputSystem.FindControls. - Adds the matching controls to the action, together with the binding's processors and interactions.
A composite binding has no control path of its own, so the Input System resolves each of its parts.
Which controls an action resolves to
The controls an action resolves to depend on how many controls each control path matches, and on whether several bindings reference the same control.
Multiple controls from one control path
A single control path can match multiple controls. For example:
- A device-specific path such as
<DualShockGamepad>/buttonEastmatches the Circle button on a PlayStation controller. If you connect multiple PlayStation controllers, it resolves to the Circle button on each of them. - An abstract device path such as
<Gamepad>/buttonEastmatches the right action button on any connected gamepad. If you connect a PlayStation controller and an Xbox controller, it resolves to the Circle button on the PlayStation controller and the B button on the Xbox controller. - A path can contain wildcards. For example,
<Gamepad>/button*matches every control on a gamepad whose name starts withbutton, which includes all four action buttons.*/{Submit}matches any control on any device that has theSubmitusage.
The same control in multiple bindings
If multiple bindings on the same action reference the same control, the control contributes input to the action once for each binding. This lets one control produce different input on the same action, for example, through composites, processors, or interactions. However, the control appears only once in the action's controls array.
Get resolved controls in code
To get the controls that an action resolves to, read InputAction.controls. If the bindings aren't resolved yet, reading the property resolves them, so this also works when the action is disabled.
To find out when binding resolution happens, listen to InputSystem.onActionChange. It reports InputActionChange.BoundControlsAboutToChange before the Input System changes the control lists, and InputActionChange.BoundControlsChanged after it updates them.
Binding resolution while actions are enabled
The Input System resolves bindings again when the controls an action can use might change: when devices are added or removed, and when bindings or binding masks change. The effect on enabled actions depends on what changed.
Device changes
When a device is added or removed, either globally or from the device list of an action map or asset, the Input System updates the controls of the affected actions without disabling them:
- If you add a device that an action can use, the action picks up input from the device's matching controls. Actions in progress continue.
- If you remove a device, actions in progress continue unless their active control is on that device. In that case, the Input System cancels the action.
If a device's usages or configuration change, the Input System re-resolves bindings in the same way as for a binding change.
Binding changes
When you change bindings or a binding mask, for example, through rebinding or by adding or deleting bindings, the Input System does the following for each enabled action map:
- Disables the actions in the map, which cancels any actions in progress.
- Resolves the bindings again.
- Re-enables the actions that were enabled. Actions that use initial state checks respond immediately to controls that are already actuated.
Control scheme auto-switching is a common cause of binding changes. When the scheme switches, PlayerInput pairs the devices for the new scheme and sets a binding mask for it, which cancels any actions in progress. Code that listens only for performed receives no event for the interrupted press. To handle the interruption, listen for canceled.