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)

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, 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)

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

ApplyBindingOverride(InputActionMap, Int32, InputBinding)

Copy the override properties (overridePath, overrideProcessors, and overrideInteractions) from bindingOverride over to the binding at index bindingIndex in bindings of actionMap.

Declaration
public static void ApplyBindingOverride(this InputActionMap actionMap, int bindingIndex, InputBinding bindingOverride)
Parameters
Type Name Description
InputActionMap actionMap

Action map whose bindings to modify.
Int32 bindingIndex

Index of the binding to modify in bindings of actionMap.
InputBinding bindingOverride

Binding whose override properties (overridePath, overrideProcessors, and overrideInteractions) to copy.
Exceptions
Type Condition
ArgumentNullException

actionMap is null.
ArgumentOutOfRangeException

bindingIndex is not a valid index for bindings of actionMap.

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

An action map. Overrides will be applied to its bindings.
InputBinding bindingOverride

Binding that is matched (see Matches(InputBinding)) against the bindings of actionMap. The binding's overridePath, overrideInteractions, and overrideProcessors properties will be copied over to any matching binding.
Returns
Type Description
Int32

The number of bindings overridden in the given map.
Exceptions
Type Condition
ArgumentNullException

actionMap is null.
See Also

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)

For all bindings in the action, if a binding matches a control in the given control hierarchy, set an override on the binding to refer specifically to that control.

Declaration
public static int ApplyBindingOverridesOnMatchingControls(this InputAction action, InputControl control)
Parameters
Type Name Description
InputAction action

An action whose bindings to modify.
InputControl control

A control hierarchy or an entire InputDevice.
Returns
Type Description
Int32

The number of binding overrides that have been applied to the given action.
Remarks

This method can be used to restrict bindings that otherwise apply to a wide set of possible controls.

// Create two gamepads.
var gamepad1 = InputSystem.AddDevice<Gamepad>();
var gamepad2 = InputSystem.AddDevice<Gamepad>();

// Create an action that binds to the A button on gamepads.
var action = new InputAction();
action.AddBinding("<Gamepad>/buttonSouth");

// When we enable the action now, it will bind to both
// gamepad1.buttonSouth and gamepad2.buttonSouth.
action.Enable();

// But let's say we want the action to specifically work
// only with the first gamepad. One way to do it is like
// this:
action.ApplyBindingOverridesOnMatchingControls(gamepad1);

// As "<Gamepad>/buttonSouth" matches the gamepad1.buttonSouth
// control, an override will automatically be applied such that
// the binding specifically refers to that button on that gamepad.

Note that for actions that are part of InputActionMaps and/or InputActionAssets, it is possible to restrict actions to specific device without having to set overrides. See bindingMask and bindingMask.

Exceptions
Type Condition
ArgumentNullException

action is null -or- control is null.
See Also

ApplyBindingOverridesOnMatchingControls(InputActionMap, InputControl)

For all bindings in the actionMap, if a binding matches a control in the given control hierarchy, set an override on the binding to refer specifically to that control.

Declaration
public static int ApplyBindingOverridesOnMatchingControls(this InputActionMap actionMap, InputControl control)
Parameters
Type Name Description
InputActionMap actionMap

An action map whose bindings to modify.
InputControl control

A control hierarchy or an entire InputDevice.
Returns
Type Description
Int32

The number of binding overrides that have been applied to the given action.
Remarks

This method can be used to restrict bindings that otherwise apply to a wide set of possible controls. It will go through bindings and apply overrides to 

// Create two gamepads.
var gamepad1 = InputSystem.AddDevice<Gamepad>();
var gamepad2 = InputSystem.AddDevice<Gamepad>();

// Create an action map with an action for the A and B buttons
// on gamepads.
var actionMap = new InputActionMap();
var aButtonAction = actionMap.AddAction("a", binding: "<Gamepad>/buttonSouth");
var bButtonAction = actionMap.AddAction("b", binding: "<Gamepad>/buttonEast");

// When we enable the action map now, the actions will bind
// to the buttons on both gamepads.
actionMap.Enable();

// But let's say we want the actions to specifically work
// only with the first gamepad. One way to do it is like
// this:
actionMap.ApplyBindingOverridesOnMatchingControls(gamepad1);

// Now binding overrides on the actions will be set to specifically refer
// to the controls on the first gamepad.

Note that for actions that are part of InputActionMaps and/or InputActionAssets, it is possible to restrict actions to specific device without having to set overrides. See bindingMask and bindingMask.

// For an InputActionMap, we could alternatively just do:
actionMap.devices = new InputDevice[] { gamepad1 };
Exceptions
Type Condition
ArgumentNullException

actionMap is null -or- control is null.
See Also

ApplyParameterOverride(InputAction, String, PrimitiveValue, Int32)

Set the value of the given parameter on the InputBindingComposite, IInputInteraction, and InputProcessor objects found on the bindings of action.

Declaration
public static void ApplyParameterOverride(this InputAction action, string name, PrimitiveValue value, int bindingIndex)
Parameters
Type Name Description
InputAction action

An action on whose bindings to look for objects to set the parameter value on.
String name

Name of the parameter to get the value of. Case-insensitive. This can either be just the name of the parameter (like "duration" or expressed as nameof(TapInteraction.duration)) or can be prefixed with the type of object to get the parameter value from. For example, "tap:duration" will specifically get the "duration" parameter from the object registered as "tap" (which will usually be TapInteraction).
PrimitiveValue value

New value to assign to the parameter.
Int32 bindingIndex

Index of the binding in bindings of action to which to restrict the parameter override to.
Remarks

This method is a variation of ApplyParameterOverride(InputActionMap, String, PrimitiveValue, InputBinding) which allows specifying a binding by index. It otherwise behaves identically to that method.

Exceptions
Type Condition
ArgumentOutOfRangeException

bindingIndex is negative or equal or greater than the number of bindings of action.
ArgumentNullException

action is null -or- name is null or empty.

ApplyParameterOverride(InputAction, String, PrimitiveValue, InputBinding)

Set the value of the given parameter on the InputBindingComposite, IInputInteraction, and InputProcessor objects found on the bindings of action.

Declaration
public static void ApplyParameterOverride(this InputAction action, string name, PrimitiveValue value, InputBinding bindingMask = default(InputBinding))
Parameters
Type Name Description
InputAction action

An action on whose bindings to look for objects to set the parameter value on.
String name

Name of the parameter to get the value of. Case-insensitive. This can either be just the name of the parameter (like "duration" or expressed as nameof(TapInteraction.duration)) or can be prefixed with the type of object to get the parameter value from. For example, "tap:duration" will specifically get the "duration" parameter from the object registered as "tap" (which will usually be TapInteraction).
PrimitiveValue value

New value to assign to the parameter.
InputBinding bindingMask

A binding mask that determines which of action's bindings to apply the override to. By default this is empty which leads to the override to be applied to all bindings of the action.
Remarks

This method both directly applies the new value and also stores the override internally.

If an override for the same parameter name on the same action and with the same bindingMask already exists, its value is simply updated. No new override will be created.

You can use this method to set parameters (public fields) on composites, interactions, and processors that are created from bindings.

// Create an action with a binding that has a "ClampProcessor" applied to it.
// This processor has two parameters:
// - "min" (float)
// - "max" (float)
var action = new InputAction(binding: ">Gamepad>/rightTrigger", processors: "clamp(min=0.2,max=0.8)");

// Apply parameter overrides to set the values differently.
action.ApplyParameterOverride("min", 0.3f);
action.ApplyParameterOverride("max", 0.9f);

An override can optionally be directed at a specific type of object.

// Create an action with both a "tap" and a "hold" interaction. Both have a
// "duration" parameter.
var action = new InputAction(binding: "<Gamepad>/buttonSouth", interactions: "tap;hold");

// Apply parameter overrides individually to the two.
action.ApplyParameterOverride("tap:duration", 0.6f);
action.ApplyParameterOverride("hold:duration", 4f);

By default, the parameter override will apply to all bindings on the action. To limit the override to specific bindings, you can supply a bindingMask.

// Create a "look" style action with a mouse and a gamepad binding.
var lookAction = new InputAction();
lookAction.AddBinding("<Mouse>/delta", processors: "scaleVector2", groups: "Mouse");
lookAction.AddBinding("<Gamepad>/rightStick", processors: "scaleVector2", groups: "Gamepad");

// Override scaling of the mouse delta individually.
lookAction.ApplyBindingOverride("scaleVector2:x", 0.25f, InputBinding.MaskByGroup("Mouse"));
lookAction.ApplyBindingOverride("scaleVector2:y", 0.25f, InputBinding.MaskByGroup("Mouse"));

// Can also do that by path.
lookAction.ApplyBindingOverride("scaleVector2:x", 0.25f, new InputBinding("<Mouse>/delta"));
lookAction.ApplyBindingOverride("scaleVector2:y", 0.25f, new InputBinding("<Mouse>/delta"));

Note that parameter overrides stay in place on the action. Like binding overrides, however, they are not automatically persisted and thus need to be reapplied when actions are loaded from assets. This will, however, be applied automatically to bindings added to the action in the future as well as whenever bindings for the action are resolved.

Exceptions
Type Condition
ArgumentNullException

action is null -or- name is null or empty.
See Also

ApplyParameterOverride(InputActionAsset, String, PrimitiveValue, InputBinding)

Set the value of the given parameter on the InputBindingComposite, IInputInteraction, and InputProcessor objects found on the bindings of each of the actionMaps in asset.

Declaration
public static void ApplyParameterOverride(this InputActionAsset asset, string name, PrimitiveValue value, InputBinding bindingMask = default(InputBinding))
Parameters
Type Name Description
InputActionAsset asset

An .inputactions asset on whose bindings to look for objects to set the parameter value on.
String name

Name of the parameter to get the value of. Case-insensitive. This can either be just the name of the parameter (like "duration" or expressed as nameof(TapInteraction.duration)) or can be prefixed with the type of object to get the parameter value from. For example, "tap:duration" will specifically get the "duration" parameter from the object registered as "tap" (which will usually be TapInteraction).
PrimitiveValue value

New value to assign to the parameter.
InputBinding bindingMask

A binding mask that determines which of the bindings to apply the override to. By default this is empty which leads to the override to be applied to all bindings in the asset.
Remarks

This method both directly applies the new value and also stores the override internally.

If an override for the same parameter name and with the same bindingMask already exists, its value is simply updated. No new override will be created.

You can use this method to set parameters (public fields) on composites, interactions, and processors that are created from bindings.

// Create an asset with one action map and two actions.
var asset = ScriptableObject.CreateInstance<InputActionAsset>();
var map = asset.AddActionMap("map");
var action1 = map.AddAction("action1");
var action2 = map.AddAction("action2");

// Add a binding to each action to which  a "ClampProcessor" is applied.
// This processor has two parameters:
// - "min" (float)
// - "max" (float)
action1.AddBinding(">Gamepad>/rightTrigger", processors: "clamp(min=0.2,max=0.8)");
action2.AddBinding(">Gamepad>/leftTrigger", processors: "clamp(min=0.2,max=0.8)");

// Apply parameter overrides to set the values differently.
// This will apply the setting to *both* the bindings on action1 *and* action2.
asset.ApplyParameterOverride("min", 0.3f);
asset.ApplyParameterOverride("max", 0.9f);

An override can optionally be directed at a specific type of object.

asset.ApplyParameterOverride("clamp:min", 0.3f);
asset.ApplyParameterOverride("clamp:max", 0.9f);

By default, the parameter override will apply to all bindings in the asset. To limit the override to specific bindings, you can supply a bindingMask.

// Apply a parameter override only to action1.
asset.ApplyBindingOverride("clamp:min", 0.25f, new InputBinding { action = action1.name });

// Apply a parameter override only to a specific binding path.
asset.ApplyBindingOverride("clamp:min", 0.4f, new InputBinding { path = "<Gamepad>/leftTrigger" });

If multiple overrides exist for the same parameter, an attempt is made to choose the override that is most specific. Say, that you apply an override for "duration" on an entire InputActionAsset using ApplyParameterOverride(InputActionAsset, String, PrimitiveValue, InputBinding). But then you also apply an override to just an individual InputAction inside the asset. In this case, the "duration" override for just that action will be applied to bindings of that action and the override inside the asset will be applied to bindings of all other actions. Note that if multiple overrides exist that could all be considered equally valid, the behavior is undecided.

Note that parameter overrides stay in place on the map. Like binding overrides, however, they are not automatically persisted and thus need to be reapplied when actions are loaded from assets. This will, however, be applied automatically to bindings added to the action in the future as well as whenever bindings are resolved to controls.

Exceptions
Type Condition
ArgumentNullException

asset is null -or- name is null or empty.
See Also

ApplyParameterOverride(InputActionMap, String, PrimitiveValue, InputBinding)

Set the value of the given parameter on the InputBindingComposite, IInputInteraction, and InputProcessor objects found on the bindings of actionMap.

Declaration
public static void ApplyParameterOverride(this InputActionMap actionMap, string name, PrimitiveValue value, InputBinding bindingMask = default(InputBinding))
Parameters
Type Name Description
InputActionMap actionMap

An action map on whose bindings to look for objects to set the parameter value on.
String name

Name of the parameter to get the value of. Case-insensitive. This can either be just the name of the parameter (like "duration" or expressed as nameof(TapInteraction.duration)) or can be prefixed with the type of object to get the parameter value from. For example, "tap:duration" will specifically get the "duration" parameter from the object registered as "tap" (which will usually be TapInteraction).
PrimitiveValue value

New value to assign to the parameter.
InputBinding bindingMask

A binding mask that determines which of actionMap's bindings to apply the override to. By default this is empty which leads to the override to be applied to all bindings in the map.
Remarks

This method both directly applies the new value and also stores the override internally.

If an override for the same parameter name and with the same bindingMask already exists, its value is simply updated. No new override will be created.

You can use this method to set parameters (public fields) on composites, interactions, and processors that are created from bindings.

// Create an action map with two actions.
var map = new InputActionMap();
var action1 = map.AddAction("action1");
var action2 = map.AddAction("action2");

// Add a binding to each action to which  a "ClampProcessor" is applied.
// This processor has two parameters:
// - "min" (float)
// - "max" (float)
action1.AddBinding(">Gamepad>/rightTrigger", processors: "clamp(min=0.2,max=0.8)");
action2.AddBinding(">Gamepad>/leftTrigger", processors: "clamp(min=0.2,max=0.8)");

// Apply parameter overrides to set the values differently.
// This will apply the setting to *both* the bindings on action1 *and* action2.
map.ApplyParameterOverride("min", 0.3f);
map.ApplyParameterOverride("max", 0.9f);

An override can optionally be directed at a specific type of object.

map.ApplyParameterOverride("clamp:min", 0.3f);
map.ApplyParameterOverride("clamp:max", 0.9f);

By default, the parameter override will apply to all bindings in the map. To limit the override to specific bindings, you can supply a bindingMask.

// Apply a parameter override only to action1.
map.ApplyBindingOverride("clamp:min", 0.25f, new InputBinding { action = action1.name });

// Apply a parameter override only to a specific binding path.
map.ApplyBindingOverride("clamp:min", 0.4f, new InputBinding { path = "<Gamepad>/leftTrigger" });

If multiple overrides exist for the same parameter, an attempt is made to choose the override that is most specific. Say, that you apply an override for "duration" on an entire InputActionAsset using ApplyParameterOverride(InputActionAsset, String, PrimitiveValue, InputBinding). But then you also apply an override to just an individual InputAction inside the asset. In this case, the "duration" override for just that action will be applied to bindings of that action and the override inside the asset will be applied to bindings of all other actions. Note that if multiple overrides exist that could all be considered equally valid, the behavior is undecided.

Note that parameter overrides stay in place on the map. Like binding overrides, however, they are not automatically persisted and thus need to be reapplied when actions are loaded from assets. This will, however, be applied automatically to bindings added to the action in the future as well as whenever bindings are resolved to controls.

Exceptions
Type Condition
ArgumentNullException

actionMap is null -or- name is null or empty.
See Also

ApplyParameterOverride<TObject, TValue>(InputAction, Expression<Func<TObject, TValue>>, TValue, InputBinding)

Set the value of the given parameter on the InputBindingComposite, IInputInteraction, and InputProcessor objects found on the bindings of action.

Declaration
public static void ApplyParameterOverride<TObject, TValue>(this InputAction action, Expression<Func<TObject, TValue>> expr, TValue value, InputBinding bindingMask = default(InputBinding))
    where TValue : struct
Parameters
Type Name Description
InputAction action

An action on whose bindings to look for objects to set the parameter value on.
Expression<Func<TObject, TValue>> expr

An expression such as (TapInteraction x) => x.duration that determines the name and type of the parameter whose value to set.
TValue value

New value to assign to the parameter.
InputBinding bindingMask

Optional mask that determines on which bindings to look for objects with parameters. If used, only bindings that match (see Matches(InputBinding)) the given mask will have the override applied to them.
Type Parameters
Name Description
TObject
TValue
Remarks

This method is a variation of ApplyParameterOverride(InputAction, String, PrimitiveValue, InputBinding) that encapsulates a reference to the name of the parameter and the type of object it is found on in a way that is type-safe and does not involve strings.

// Override the "duration" parameter from a TapInteraction.
// This is equivalent to calling ApplyParameterOverride("tap:duration", 0.4f).
action.ApplyParameterOverride((TapInteraction x) => x.duration, 0.4f);
Exceptions
Type Condition
ArgumentNullException

action is null -or- expr is null or empty.
See Also

ApplyParameterOverride<TObject, TValue>(InputActionAsset, Expression<Func<TObject, TValue>>, TValue, InputBinding)

Set the value of the given parameter on the InputBindingComposite, IInputInteraction, and InputProcessor objects found on the bindings of the actionMaps in asset.

Declaration
public static void ApplyParameterOverride<TObject, TValue>(this InputActionAsset asset, Expression<Func<TObject, TValue>> expr, TValue value, InputBinding bindingMask = default(InputBinding))
    where TValue : struct
Parameters
Type Name Description
InputActionAsset asset

An asset on whose bindings to look for objects to set the parameter value on.
Expression<Func<TObject, TValue>> expr

An expression such as (TapInteraction x) => x.duration that determines the name and type of the parameter whose value to set.
TValue value

New value to assign to the parameter.
InputBinding bindingMask

Optional mask that determines on which bindings to look for objects with parameters. If used, only bindings that match (see Matches(InputBinding)) the given mask will have the override applied to them.
Type Parameters
Name Description
TObject
TValue
Remarks

This method is a variation of ApplyParameterOverride(InputActionAsset, String, PrimitiveValue, InputBinding) that encapsulates a reference to the name of the parameter and the type of object it is found on in a way that is type-safe and does not involve strings.

// Override the "duration" parameter from a TapInteraction.
// This is equivalent to calling mApplyParameterOverride("tap:duration", 0.4f).
asset.ApplyParameterOverride((TapInteraction x) => x.duration, 0.4f);
Exceptions
Type Condition
ArgumentNullException

asset is null -or- expr is null or empty.
See Also

ApplyParameterOverride<TObject, TValue>(InputActionMap, Expression<Func<TObject, TValue>>, TValue, InputBinding)

Set the value of the given parameter on the InputBindingComposite, IInputInteraction, and InputProcessor objects found on the bindings of actionMap.

Declaration
public static void ApplyParameterOverride<TObject, TValue>(this InputActionMap actionMap, Expression<Func<TObject, TValue>> expr, TValue value, InputBinding bindingMask = default(InputBinding))
    where TValue : struct
Parameters
Type Name Description
InputActionMap actionMap

An action on whose bindings to look for objects to set the parameter value on.
Expression<Func<TObject, TValue>> expr

An expression such as (TapInteraction x) => x.duration that determines the name and type of the parameter whose value to set.
TValue value

New value to assign to the parameter.
InputBinding bindingMask

Optional mask that determines on which bindings to look for objects with parameters. If used, only bindings that match (see Matches(InputBinding)) the given mask will have the override applied to them.
Type Parameters
Name Description
TObject
TValue
Remarks

This method is a variation of ApplyParameterOverride(InputActionMap, String, PrimitiveValue, InputBinding) that encapsulates a reference to the name of the parameter and the type of object it is found on in a way that is type-safe and does not involve strings.

// Override the "duration" parameter from a TapInteraction.
// This is equivalent to calling mApplyParameterOverride("tap:duration", 0.4f).
actionMap.ApplyParameterOverride((TapInteraction x) => x.duration, 0.4f);
Exceptions
Type Condition
ArgumentNullException

actionMap is null -or- expr is null or empty.
See Also

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(0, out var deviceLayoutNameA, out var controlPathA));
Debug.Log(deviceLayoutNameA);
Debug.Log(controlPathA);

// Prints "LMB", then "Mouse", then "leftButton".
Debug.Log(action.GetBindingDisplayString(1, out var deviceLayoutNameB, out var controlPathB));
Debug.Log(deviceLayoutNameB);
Debug.Log(controlPathB);
Exceptions
Type Condition
ArgumentNullException

action is null.
See Also

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

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

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

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

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

GetBindingIndex(InputActionMap, InputBinding)

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

Declaration
public static int GetBindingIndex(this InputActionMap actionMap, InputBinding bindingMask)
Parameters
Type Name Description
InputActionMap actionMap

An input action map.
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

actionMap is null.
See Also

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.

GetParameterValue(InputAction, String, Int32)

Return the current value of the given parameter as found on the processors, interactions, or composites of the action's current bindings.

Declaration
public static PrimitiveValue? GetParameterValue(this InputAction action, string name, int bindingIndex)
Parameters
Type Name Description
InputAction action

Action on whose bindings to look for the value of the given parameter.
String name

Name of the parameter to get the value of. Case-insensitive. This can either be just the name of the parameter (like "duration" or expressed as nameof(TapInteraction.duration)) or can be prefixed with the type of object to get the parameter value from. For example, "tap:duration" will specifically get the "duration" parameter from the object registered as "tap" (which will usually be TapInteraction).
Int32 bindingIndex

Index of the binding in action's bindings to look for processors, interactions, and composites on.
Returns
Type Description
Nullable<PrimitiveValue>

The current value of the given parameter or null if the parameter not could be found.
Remarks

This method is a variation of ApplyParameterOverride(InputActionMap, String, PrimitiveValue, InputBinding) to specifically target a single binding by index. Otherwise, the method is identical in functionality.

Exceptions
Type Condition
ArgumentNullException

action is null -or- name is null

GetParameterValue(InputAction, String, InputBinding)

Return the current value of the given parameter as found on the processors, interactions, or composites of the action's current bindings.

Declaration
public static PrimitiveValue? GetParameterValue(this InputAction action, string name, InputBinding bindingMask = default(InputBinding))
Parameters
Type Name Description
InputAction action

Action on whose bindings to look for the value of the given parameter.
String name

Name of the parameter to get the value of. Case-insensitive. This can either be just the name of the parameter (like "duration" or expressed as nameof(TapInteraction.duration)) or can be prefixed with the type of object to get the parameter value from. For example, "tap:duration" will specifically get the "duration" parameter from the object registered as "tap" (which will usually be TapInteraction).
InputBinding bindingMask

Optional mask that determines on which bindings to look for objects with parameters. If used, only bindings that match (see Matches(InputBinding)) the given mask will be taken into account.
Returns
Type Description
Nullable<PrimitiveValue>

The current value of the given parameter or null if the parameter could not be found.
Remarks

Parameters are found on interactions (IInputInteraction), processors (InputProcessor), and composites (see InputBindingComposite) that are applied to bindings. For example, the following binding adds a Hold interaction with a custom duration parameter on top of binding to the gamepad's A button:

new InputBinding
{
    path = "<Gamepad>/buttonSouth",
    interactions = "hold(duration=0.6)"
};

In the editor UI, parameters are set graphically from the properties sections in the right-most pane in the action editor when an action or a binding is selected.

When the binding above is applied to an action, the duration parameter from the Hold interaction can be queried like so:

action.GetParameterValue("duration") // Returns 0.6

Note that if there are multiple objects on the action that use the same parameter name, the value of the first parameter that is encountered is returned. Also note that this method will create GC heap garbage.

The type of object to query the parameter from can be include in the name parameter. For example, if an action has both a TapInteraction and a HoldInteraction on it, the duration parameter can be queried independently like so:

// Query "duration" from "hold":
action.GetParameterValue("hold:duration");

// Query "duration" from "tap":
action.GetParameterValue("tap:duration");

The names used here to identify the object holding the parameter are the same used by RegisterInteraction(Type, String), RegisterBindingComposite(Type, String), and RegisterProcessor(Type, String).

Exceptions
Type Condition
ArgumentNullException

action is null -or- name is null
See Also

GetParameterValue<TObject, TValue>(InputAction, Expression<Func<TObject, TValue>>, InputBinding)

Return the current value of the given parameter as found on the processors, interactions, or composites of the action's current bindings.

Declaration
public static TValue? GetParameterValue<TObject, TValue>(this InputAction action, Expression<Func<TObject, TValue>> expr, InputBinding bindingMask = default(InputBinding))
    where TValue : struct
Parameters
Type Name Description
InputAction action

Action on whose bindings to look for the value of the given parameter.
Expression<Func<TObject, TValue>> expr

An expression such as (TapInteraction x) => x.duration that determines the name and type of the parameter being looked for.
InputBinding bindingMask

Optional mask that determines on which bindings to look for objects with parameters. If used, only bindings that match (see Matches(InputBinding)) the given mask will be taken into account.
Returns
Type Description
Nullable<TValue>

The current value of the given parameter or null if the parameter not could be found.
Type Parameters
Name Description
TObject
TValue
Remarks

This method is a variation of ApplyParameterOverride(InputActionMap, String, PrimitiveValue, InputBinding) that encapsulates a reference to the name of the parameter and the type of object it is found on in a way that is type-safe and does not involve strings.

// Get the "duration" parameter from a TapInteraction.
// This is equivalent to calling GetParameterValue("tap:duration")
// but will return a float? instead of a PrimitiveValue?.
action.GetParameterValue((TapInteraction x) => x.duration)
Exceptions
Type Condition
ArgumentNullException

action is null -or- expr is null
See Also

LoadBindingOverridesFromJson(IInputActionCollection2, String, Boolean)

Restore all binding overrides stored in the given JSON string to the bindings in actions.

Declaration
public static void LoadBindingOverridesFromJson(this IInputActionCollection2 actions, string json, bool removeExisting = true)
Parameters
Type Name Description
IInputActionCollection2 actions

A set of actions and their bindings, such as an InputActionMap, an InputActionAsset, or a C# wrapper class generated from an .inputactions asset.
String json

A string persisting binding overrides in JSON format. See SaveBindingOverridesAsJson(IInputActionCollection2).
Boolean removeExisting

If true (default), all existing overrides present on the bindings of actions will be removed first. If false, existing binding overrides will be left in place but may be overwritten by overrides present in json.
Remarks
void SaveUserRebinds(PlayerInput player)
{
    var rebinds = player.actions.SaveBindingOverridesAsJson();
    PlayerPrefs.SetString("rebinds", rebinds);
}

void LoadUserRebinds(PlayerInput player)
{
    var rebinds = PlayerPrefs.GetString("rebinds");
    player.actions.LoadBindingOverridesFromJson(rebinds);
}

Note that this method can also be used with C# wrapper classes generated from .inputactions assets.

Exceptions
Type Condition
ArgumentNullException

actions is null.
See Also

LoadBindingOverridesFromJson(InputAction, String, Boolean)

Restore all binding overrides stored in the given JSON string to the bindings of action.

Declaration
public static void LoadBindingOverridesFromJson(this InputAction action, string json, bool removeExisting = true)
Parameters
Type Name Description
InputAction action

Action to restore bindings on.
String json

A string persisting binding overrides in JSON format. See SaveBindingOverridesAsJson(InputAction).
Boolean removeExisting

If true (default), all existing overrides present on the bindings of action will be removed first. If false, existing binding overrides will be left in place but may be overwritten by overrides present in json.
Remarks
void SaveUserRebinds(PlayerInput player)
{
    var rebinds = player.actions.SaveBindingOverridesAsJson();
    PlayerPrefs.SetString("rebinds", rebinds);
}

void LoadUserRebinds(PlayerInput player)
{
    var rebinds = PlayerPrefs.GetString("rebinds");
    player.actions.LoadBindingOverridesFromJson(rebinds);
}

Note that this method can also be used with C# wrapper classes generated from .inputactions assets.

Exceptions
Type Condition
ArgumentNullException

actions is null.
See Also

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. In particular, it will apply the following default configuration:

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(IInputActionCollection2)

Restore all bindings in the map to their defaults.

Declaration
public static void RemoveAllBindingOverrides(this IInputActionCollection2 actions)
Parameters
Type Name Description
IInputActionCollection2 actions

Collection of actions to remove overrides from.
Exceptions
Type Condition
ArgumentNullException

actions is null.
See Also

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.
See Also

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

SaveBindingOverridesAsJson(IInputActionCollection2)

Return a JSON string containing all overrides applied to bindings in the given set of actions.

Declaration
public static string SaveBindingOverridesAsJson(this IInputActionCollection2 actions)
Parameters
Type Name Description
IInputActionCollection2 actions

A collection of InputActions such as an InputActionAsset or an InputActionMap.
Returns
Type Description
String

A JSON string containing a serialized version of the overrides applied to bindings in the given set of actions.
Remarks

This method can be used to serialize the overrides, i.e. overridePath, overrideProcessors, and overrideInteractions, applied to bindings in the set of actions. Only overrides will be saved.

void SaveUserRebinds(PlayerInput player)
{
    var rebinds = player.actions.SaveBindingOverridesAsJson();
    PlayerPrefs.SetString("rebinds", rebinds);
}

void LoadUserRebinds(PlayerInput player)
{
    var rebinds = PlayerPrefs.GetString("rebinds");
    player.actions.LoadBindingOverridesFromJson(rebinds);
}

Note that this method can also be used with C# wrapper classes generated from .inputactions assets.

Exceptions
Type Condition
ArgumentNullException

actions is null.
See Also

SaveBindingOverridesAsJson(InputAction)

Return a string in JSON format that contains all overrides applied bindings of action.

Declaration
public static string SaveBindingOverridesAsJson(this InputAction action)
Parameters
Type Name Description
InputAction action

An action for which to extract binding overrides.
Returns
Type Description
String

A string in JSON format containing binding overrides for action.
Remarks

This overrides can be restored using LoadBindingOverridesFromJson(InputAction, String, Boolean).

Exceptions
Type Condition
ArgumentNullException

action is null.

See Also