Class InputActionRebindingExtensions

Extensions to help with dynamically rebinding InputActions in various ways.

Inheritance

Object

InputActionRebindingExtensions

Namespace: UnityEngine.InputSystem

Syntax

public static class InputActionRebindingExtensions

Remarks

Unlike InputActionSetupExtensions, the extension methods in here are meant to be called during normal game operation, i.e. as part of screens whether the user can rebind controls.

The two primary duties of these extensions are to apply binding overrides that non-destructively redirect existing bindings and to facilitate user-controlled rebinding by listening for controls actuated by the user.

Methods

ApplyBindingOverride(InputAction, Int32, String)

Apply a binding override to the Nth binding on the given action.

Declaration

public static void ApplyBindingOverride(this InputAction action, int bindingIndex, string path)

Parameters

Type	Name	Description
InputAction	action	Action to apply the binding override to.
Int32	bindingIndex	Index of the binding in bindings to which to apply the override to.
String	path	Override path (overridePath) to set on the given binding in bindings.

Remarks

Calling this method is equivalent to calling ApplyBindingOverride(InputAction, Int32, InputBinding) like so:

action.ApplyBindingOverride(new InputBinding { overridePath = path });

Exceptions

Type	Condition
ArgumentNullException	action is null.
ArgumentOutOfRangeException	bindingIndex is out of range.

See Also

ApplyBindingOverride(InputAction, Int32, InputBinding)

ApplyBindingOverride(InputAction, Int32, InputBinding)

Apply a binding override to the Nth binding on the given action.

Declaration

public static void ApplyBindingOverride(this InputAction action, int bindingIndex, InputBinding bindingOverride)

Parameters

Type	Name	Description
InputAction	action	Action to apply the binding override to.
Int32	bindingIndex	Index of the binding in bindings to which to apply the override to.
InputBinding	bindingOverride	A binding that specifies the overrides to apply. In particular, the overridePath, overrideProcessors, and overrideInteractions properties will be copied into the binding in bindings. The remaining fields will be ignored by this method.

Remarks

Unlike ApplyBindingOverride(InputAction, InputBinding) this method will not use Matches(InputBinding) to determine which binding to apply the override to. Instead, it will apply the override to the binding at the given index and to that binding alone.

The remaining details of applying overrides are identical to ApplyBindingOverride(InputAction, InputBinding).

Note that calling this method with an empty (default-constructed) bindingOverride is equivalent to resetting all overrides on the given binding.

// Reset the overrides on the second binding on 'fireAction'.
fireAction.ApplyBindingOverride(1, default);

Exceptions

Type	Condition
ArgumentNullException	action is null.
ArgumentOutOfRangeException	bindingIndex is out of range.

See Also

ApplyBindingOverride(InputAction, InputBinding)

ApplyBindingOverride(InputAction, String, String, String)

Put an override on all matching bindings of action.

Declaration

public static void ApplyBindingOverride(this InputAction action, string newPath, string group = null, string path = null)

Parameters

Type	Name	Description
InputAction	action	Action to apply the override to.
String	newPath	New binding path to take effect. Supply an empty string to disable the binding(s). See InputControlPath for details on the path language.
String	group	Optional list of binding groups to target the override to. For example, "Keyboard;Gamepad" will only apply overrides to bindings that either have the "Keyboard" or the "Gamepad" binding group listed in groups.
String	path	Only override bindings that have this exact path.

Remarks

Calling this method is equivalent to calling ApplyBindingOverride(InputAction, InputBinding) with the properties of the given InputBinding initialized accordingly.

// Override the binding to the gamepad A button with a binding to
// the Y button.
fireAction.ApplyBindingOverride("<Gamepad>/buttonNorth",
    path: "<Gamepad>/buttonSouth);

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

ApplyBindingOverride(InputAction, InputBinding)

effectivePath

overridePath

Matches(InputBinding)

ApplyBindingOverride(InputAction, InputBinding)

Apply overrides to all bindings on action that match bindingOverride. The override values are taken from overridePath, overrideProcessors, and overrideInteractions on bindingOverride.

Declaration

public static void ApplyBindingOverride(this InputAction action, InputBinding bindingOverride)

Parameters

Type	Name	Description
InputAction	action	Action to override bindings on.
InputBinding	bindingOverride	A binding that both acts as a mask (see Matches(InputBinding)) on the bindings to action and as a container for the override values.

Remarks

The method will go through all of the bindings for action (i.e. its bindings) and call Matches(InputBinding) on them with bindingOverride. For every binding that returns true from Matches, the override values from the binding (i.e. overridePath, overrideProcessors, and overrideInteractions) are copied into the binding.

Binding overrides are non-destructive. They do not change the bindings set up for an action but rather apply non-destructive modifications that change the paths of existing bindings. However, this also means that for overrides to work, there have to be existing bindings that can be modified.

This is achieved by setting overridePath which is a non-serialized property. When resolving bindings, the system will use effectivePath which uses overridePath if set or path otherwise. The same applies to effectiveProcessors and effectiveInteractions.

// Override the binding in the "KeyboardMouse" group on 'fireAction'
// by setting its override binding path to the space bar on the keyboard.
fireAction.ApplyBindingOverride(new InputBinding
{
    groups = "KeyboardMouse",
    overridePath = "<Keyboard>/space"
});

If the given action is enabled when calling this method, the effect will be immediate, i.e. binding resolution takes place and controls are updated. If the action is not enabled, binding resolution is deferred to when controls are needed next (usually when either controls is queried or when the action is enabled).

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

bindings

Matches(InputBinding)

ApplyBindingOverride(InputActionMap, Int32, InputBinding)

Declaration

public static void ApplyBindingOverride(this InputActionMap actionMap, int bindingIndex, InputBinding bindingOverride)

Parameters

Type	Name	Description
InputActionMap	actionMap
Int32	bindingIndex
InputBinding	bindingOverride

ApplyBindingOverride(InputActionMap, InputBinding)

Apply the given binding override to all bindings in the map that are matched by the override.

Declaration

public static int ApplyBindingOverride(this InputActionMap actionMap, InputBinding bindingOverride)

Parameters

Type	Name	Description
InputActionMap	actionMap
InputBinding	bindingOverride

Returns

Type	Description
Int32	The number of bindings overridden in the given map.

Exceptions

Type	Condition
ArgumentNullException	actionMap is null.

ApplyBindingOverrides(InputActionMap, IEnumerable<InputBinding>)

Declaration

public static void ApplyBindingOverrides(this InputActionMap actionMap, IEnumerable<InputBinding> overrides)

Parameters

Type	Name	Description
InputActionMap	actionMap
IEnumerable<InputBinding>	overrides

ApplyBindingOverridesOnMatchingControls(InputAction, InputControl)

Declaration

public static int ApplyBindingOverridesOnMatchingControls(this InputAction action, InputControl control)

Parameters

Type	Name	Description
InputAction	action
InputControl	control

Returns

Type	Description
Int32

ApplyBindingOverridesOnMatchingControls(InputActionMap, InputControl)

Declaration

public static int ApplyBindingOverridesOnMatchingControls(this InputActionMap actionMap, InputControl control)

Parameters

Type	Name	Description
InputActionMap	actionMap
InputControl	control

Returns

Type	Description
Int32

GetBindingDisplayString(InputAction, Int32, out String, out String, InputBinding.DisplayStringOptions)

Return a string suitable for display in UIs that shows what the given action is currently bound to.

Declaration

public static string GetBindingDisplayString(this InputAction action, int bindingIndex, out string deviceLayoutName, out string controlPath, InputBinding.DisplayStringOptions options = (InputBinding.DisplayStringOptions)0)

Parameters

Type	Name	Description
InputAction	action	Action to create a display string for.
Int32	bindingIndex	Index of the binding in the bindings array of action for which to get a display string.
String	deviceLayoutName	Receives the name of the InputControlLayout used for the device in the given binding, if applicable. Otherwise is set to null. If, for example, the binding is "<Gamepad>/buttonSouth", the resulting value is "Gamepad.
String	controlPath	Receives the path to the control on the device referenced in the given binding, if applicable. Otherwise is set to null. If, for example, the binding is "<Gamepad>/leftStick/x", the resulting value is "leftStick/x".
InputBinding.DisplayStringOptions	options	Optional set of formatting flags.

Returns

Type	Description
String	A string suitable for display in rebinding UIs.

Remarks

The information returned by deviceLayoutName and controlPath can be used, for example, to associate images with controls. Based on knowing which layout is used and which control on the layout is referenced, you can look up an image dynamically. For example, if the layout is based on DualShockGamepad (use IsFirstLayoutBasedOnSecond(String, String) to determine inheritance), you can pick a PlayStation-specific image for the control as named by controlPath.

var action = new InputAction();

action.AddBinding("<Gamepad>/dpad/up", groups: "Gamepad");
action.AddBinding("<Mouse>/leftButton", groups: "KeyboardMouse");

// Prints "A", then "Gamepad", then "dpad/up".
Debug.Log(action.GetBindingDisplayString(InputBinding.MaskByGroup("Gamepad", out var deviceLayoutNameA, out var controlPathA));
Debug.Log(deviceLayoutNameA);
Debug.Log(controlPathA);

// Prints "LMB", then "Mouse", then "leftButton".
Debug.Log(action.GetBindingDisplayString(InputBinding.MaskByGroup("KeyboardMouse", out var deviceLayoutNameB, out var controlPathB));
Debug.Log(deviceLayoutNameB);
Debug.Log(controlPathB);

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

ToDisplayString(InputBinding.DisplayStringOptions, InputControl)

ToHumanReadableString(String, InputControlPath.HumanReadableStringOptions, InputControl)

GetBindingDisplayString(InputAction, Int32, InputBinding.DisplayStringOptions)

Return a string suitable for display in UIs that shows what the given action is currently bound to.

Declaration

public static string GetBindingDisplayString(this InputAction action, int bindingIndex, InputBinding.DisplayStringOptions options = (InputBinding.DisplayStringOptions)0)

Parameters

Type	Name	Description
InputAction	action	Action to create a display string for.
Int32	bindingIndex	Index of the binding in the bindings array of action for which to get a display string.
InputBinding.DisplayStringOptions	options	Optional set of formatting flags.

Returns

Type	Description
String	A string suitable for display in rebinding UIs.

Remarks

This method will ignore active binding masks and return the display string for the given binding whether it is masked out (disabled) or not.

var action = new InputAction();

action.AddBinding("<Gamepad>/buttonSouth", groups: "Gamepad");
action.AddBinding("<Mouse>/leftButton", groups: "KeyboardMouse");

// Prints "A".
Debug.Log(action.GetBindingDisplayString(0));

// Prints "LMB".
Debug.Log(action.GetBindingDisplayString(1));

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

ToDisplayString(InputBinding.DisplayStringOptions, InputControl)

ToHumanReadableString(String, InputControlPath.HumanReadableStringOptions, InputControl)

GetBindingDisplayString(InputAction, InputBinding, InputBinding.DisplayStringOptions)

Return a string suitable for display in UIs that shows what the given action is currently bound to.

Declaration

public static string GetBindingDisplayString(this InputAction action, InputBinding bindingMask, InputBinding.DisplayStringOptions options = (InputBinding.DisplayStringOptions)0)

Parameters

Type	Name	Description
InputAction	action	Action to create a display string for.
InputBinding	bindingMask	Mask for bindings to take into account. Any binding on the action not matching (see Matches(InputBinding)) the mask is ignored and not included in the resulting string.
InputBinding.DisplayStringOptions	options	Optional set of formatting flags.

Returns

Type	Description
String	A string suitable for display in rebinding UIs.

Remarks

This method will take into account any binding masks (such as from control schemes) in effect on the action (such as bindingMask on the action itself, the bindingMask on its action map, or the bindingMask on its asset) as well as the actual controls that the action is currently bound to (see controls).

var action = new InputAction();

action.AddBinding("<Gamepad>/buttonSouth", groups: "Gamepad");
action.AddBinding("<Mouse>/leftButton", groups: "KeyboardMouse");

// Prints "A".
Debug.Log(action.GetBindingDisplayString(InputBinding.MaskByGroup("Gamepad"));

// Prints "LMB".
Debug.Log(action.GetBindingDisplayString(InputBinding.MaskByGroup("KeyboardMouse"));

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

ToDisplayString(InputBinding.DisplayStringOptions, InputControl)

ToHumanReadableString(String, InputControlPath.HumanReadableStringOptions, InputControl)

GetBindingDisplayString(InputAction, InputBinding.DisplayStringOptions, String)

Return a string suitable for display in UIs that shows what the given action is currently bound to.

Declaration

public static string GetBindingDisplayString(this InputAction action, InputBinding.DisplayStringOptions options = (InputBinding.DisplayStringOptions)0, string group = null)

Parameters

Type	Name	Description
InputAction	action	Action to create a display string for.
InputBinding.DisplayStringOptions	options	Optional set of formatting flags.
String	group	Optional binding group to restrict the operation to. If this is supplied, it effectively becomes the binding mask (see Matches(InputBinding)) to supply to GetBindingDisplayString(InputAction, InputBinding, InputBinding.DisplayStringOptions).

Returns

Type	Description
String	A string suitable for display in rebinding UIs.

Remarks

This method will take into account any binding masks (such as from control schemes) in effect on the action (such as bindingMask on the action itself, the bindingMask on its action map, or the bindingMask on its asset) as well as the actual controls that the action is currently bound to (see controls).

var action = new InputAction();

action.AddBinding("<Gamepad>/buttonSouth", groups: "Gamepad");
action.AddBinding("<Mouse>/leftButton", groups: "KeyboardMouse");

// Prints "A | LMB".
Debug.Log(action.GetBindingDisplayString());

// Prints "A".
Debug.Log(action.GetBindingDisplayString(group: "Gamepad");

// Prints "LMB".
Debug.Log(action.GetBindingDisplayString(group: "KeyboardMouse");

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

ToDisplayString(InputBinding.DisplayStringOptions, InputControl)

ToHumanReadableString(String, InputControlPath.HumanReadableStringOptions, InputControl)

GetBindingForControl(InputAction, InputControl)

Return the binding that the given control resolved from.

Declaration

public static InputBinding? GetBindingForControl(this InputAction action, InputControl control)

Parameters

Type	Name	Description
InputAction	action	An input action that may be using the given control.
InputControl	control	Control to look for a binding for.

Returns

Type	Description
Nullable<InputBinding>	The binding from which control has been resolved or null if no such binding could be found on action.

Exceptions

Type	Condition
ArgumentNullException	action is null -or- control is null.

GetBindingIndex(InputAction, String, String)

Get the index of the first binding in bindings on action that matches the given binding group and/or path.

Declaration

public static int GetBindingIndex(this InputAction action, string group = null, string path = null)

Parameters

Type	Name	Description
InputAction	action	An input action.
String	group	Binding group to match (see groups).
String	path	Binding path to match (see path).

Returns

Type	Description
Int32	The first binding on the action matching the given group and/or path or -1 if no binding on the action matches.

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

Matches(InputBinding)

GetBindingIndex(InputAction, InputBinding)

Get the index of the first binding in bindings on action that matches the given binding mask.

Declaration

public static int GetBindingIndex(this InputAction action, InputBinding bindingMask)

Parameters

Type	Name	Description
InputAction	action	An input action.
InputBinding	bindingMask	Binding mask to match (see Matches(InputBinding)).

Returns

Type	Description
Int32	The first binding on the action matching bindingMask or -1 if no binding on the action matches the mask.

Exceptions

Type	Condition
ArgumentNullException	action is null.

See Also

Matches(InputBinding)

GetBindingIndexForControl(InputAction, InputControl)

Return the index into action's bindings that corresponds to control bound to the action.

Declaration

public static int GetBindingIndexForControl(this InputAction action, InputControl control)

Parameters

Type	Name	Description
InputAction	action	The input action whose bindings to use.
InputControl	control	An input control for which to look for a binding.

Returns

Type	Description
Int32	The index into the action's binding array for the binding that control was resolved from or -1 if the control is not currently bound to the action.

Remarks

Note that this method will only take currently active bindings into consideration. This means that if the given control could come from one of the bindings on the action but does not currently do so, the method still returns -1.

In case you want to manually find out which of the bindings on the action could match the given control, you can do so using Matches(String, InputControl):

// Find the binding on 'action' that matches the given 'control'.
foreach (var binding in action.bindings)
    if (InputControlPath.Matches(binding.effectivePath, control))
        Debug.Log($"Binding for {control}: {binding}");

Exceptions

Type	Condition
ArgumentNullException	action is null -or- control is null.

PerformInteractiveRebinding(InputAction, Int32)

Initiate an operation that interactively rebinds the given action based on received input.

Declaration

public static InputActionRebindingExtensions.RebindingOperation PerformInteractiveRebinding(this InputAction action, int bindingIndex = -1)

Parameters

Type	Name	Description
InputAction	action	Action to perform rebinding on.
Int32	bindingIndex	Optional index (within the bindings array of action) of binding to perform rebinding on. Must not be a composite binding.

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation	A rebind operation configured to perform the rebind.

Remarks

This method will automatically perform a set of configuration on the InputActionRebindingExtensions.RebindingOperation based on the action and, if specified, binding.

TODO

Note that rebind operations must be disposed of once finished in order to not leak memory.

// Target the first binding in the gamepad scheme.
var bindingIndex = myAction.GetBindingIndex(InputBinding.MaskByGroup("Gamepad"));
var rebind = myAction.PerformInteractiveRebinding(bindingIndex);

// Dispose the operation on completion.
rebind.OnComplete(
   operation =>
   {
       Debug.Log($"Rebound '{myAction}' to '{operation.selectedControl}'");
       operation.Dispose();
   };

// Start the rebind. This will cause the rebind operation to start running in the
// background listening for input.
rebind.Start();

Exceptions

Type	Condition
ArgumentNullException	action is null.
ArgumentOutOfRangeException	bindingIndex is not a valid index.
InvalidOperationException	The binding at bindingIndex is a composite binding.

RemoveAllBindingOverrides(InputAction)

Remove all binding overrides on action, i.e. clear all overridePath, overrideProcessors, and overrideInteractions set on bindings for the given action.

Declaration

public static void RemoveAllBindingOverrides(this InputAction action)

Parameters

Type	Name	Description
InputAction	action	Action to remove overrides from.

Exceptions

Type	Condition
ArgumentNullException	action is null.

RemoveAllBindingOverrides(InputActionMap)

Restore all bindings in the map to their defaults.

Declaration

public static void RemoveAllBindingOverrides(this InputActionMap actionMap)

Parameters

Type	Name	Description
InputActionMap	actionMap	Action map to remove overrides from.

Exceptions

Type	Condition
ArgumentNullException	actionMap is null.

RemoveBindingOverride(InputAction, Int32)

Remove any overrides from the binding on action with the given index.

Declaration

public static void RemoveBindingOverride(this InputAction action, int bindingIndex)

Parameters

Type	Name	Description
InputAction	action	Action whose bindings to modify.
Int32	bindingIndex	Index of the binding within action's bindings.

Exceptions

Type	Condition
ArgumentNullException	action is null.
ArgumentOutOfRangeException	bindingIndex is invalid.

RemoveBindingOverride(InputAction, InputBinding)

Remove any overrides from the binding on action matching the given binding mask.

Declaration

public static void RemoveBindingOverride(this InputAction action, InputBinding bindingMask)

Parameters

Type	Name	Description
InputAction	action	Action whose bindings to modify.
InputBinding	bindingMask	Mask that will be matched against the bindings on action. All bindings that match the mask (see Matches(InputBinding)) will have their overrides removed. If none of the bindings on the action match the mask, no bindings will be modified.

Remarks

// Remove all binding overrides from bindings associated with the "Gamepad" binding group.
myAction.RemoveBindingOverride(InputBinding.MaskByGroup("Gamepad"));

Exceptions

Type	Condition
ArgumentNullException	action is null.

RemoveBindingOverrides(InputActionMap, IEnumerable<InputBinding>)

Declaration

public static void RemoveBindingOverrides(this InputActionMap actionMap, IEnumerable<InputBinding> overrides)

Parameters

Type	Name	Description
InputActionMap	actionMap
IEnumerable<InputBinding>	overrides

See Also

InputActionSetupExtensions

InputBinding

bindings