Binding resolution

Binding resolution refers to when the Input System looks up which actual controls on connected devices should be used by each action, based on their binding control paths.

Why bindings are resolved

Each simple binding has a control path, which determines which control (or controls) should be associated with the action. For composite bindings, each of the composites sub-bindings (or parts) has a control path.

Control paths are stored as a string that describes where to find the relevant control or controls for the binding. For example, a control path "<Gamepad>/buttonEast" refers to the right action button on any connected gamepad.

Because control paths can refer to specific devices, or more broadly to a device type, and can also contain wildcard characters, and there may be any combinations of input hardware connected, the Input System must resolve the bindings at runtime to work out which controls on connected devices are valid for each action. This occurs when the Input System accesses an action for the first time.

What happens during resolution

During binding resolution, the action automatically calls InputSystem.FindControls<>() (filtering for devices assigned to the InputActionMap, if there are any) for the binding path of each of the Action's bindings. This creates a list of resolved Controls that are now bound to the Action.

Note that a single binding control path can match multiple Controls. For example:

• A device-specific path such as <DualShockGamepad>/buttonEast matches the "Circle" button on a PlayStation controller. If you have multiple PlayStation controllers connected, it resolves to the "Circle" button on each of these controllers.

• An abstract device path such as <Gamepad>/buttonEast matches the right action button on any connected gamepad. If you have a PlayStation controller and an Xbox controller connected, it resolves to the "Circle" button on the PlayStation controller, and to the "B" button on the Xbox controller.

• A binding path can also contain wildcards, such as <Gamepad>/button*. This matches any control on any gamepad with a name starting with "button", which matches all the four action buttons on any connected gamepad. A different example: */{Submit} matches any control tagged with the "Submit" usage on any device.

If there are multiple bindings on the same action that all reference the same control(s), the control will effectively feed into the action multiple times. This is to allow, for example, a single control to produce different input on the same action by virtue of being bound in a different fashion (composites, processors, interactions, etc). However, regardless of how many times a control is bound on any given action, it will only appear once in the action's array of controls.

To query the Controls that an Action resolves to, you can use InputAction.controls. You can also run this query if the Action is disabled.

To be notified when binding resolution happens, you can listen to InputSystem.onActionChange which triggers InputActionChange.BoundControlsAboutToChange before modifying Control lists and triggers InputActionChange.BoundControlsChanged after having updated them.

Binding resolution while actions are enabled

In certain situations, the controls bound to an action have to be updated more than once. For example, if a new device is plugged in and becomes usable with an action, the action may now pick up input from additional controls. Also, if bindings are added, removed, or modified, control lists will need to be updated.

This updating of controls usually happens transparently in the background. However, when an action is enabled and especially when it is in progress, there may be a noticeable effect on the Action.

Adding or removing a device – either globally or to/from the device list of an Action – will remain transparent except if an Action is in progress and it is the device of its active Control that is being removed. In this case, the Action will automatically be cancelled.

Modifying the binding mask or modifying any of the bindings (such as through rebinding or by adding or removing bindings) will, however, lead to all enabled actions being temporarily disabled and then re-enabled and resumed.