Class InputActionRebindingExtensions
Extensions to help with dynamically rebinding InputActions in various ways.
Namespace: UnityEngine.InputSystem
Assembly: Unity.InputSystem.dll
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.
To implement user-controlled rebinding, create a UI with a button to trigger rebinding.
If the user clicks the button to bind a control to an action, use InputAction.PerformInteractiveRebinding
to handle the rebinding, as in the following example:
void RemapButtonClicked(InputAction actionToRebind)
{
var rebindOperation = actionToRebind.PerformInteractiveRebinding()
// To avoid accidental input from mouse motion
.WithControlsExcluding("Mouse")
.OnMatchWaitForAnother(0.1f)
.Start();
}
You can install the Tanks Demo sample from the Input System package using the Package Manager window, which has an example of an interactive rebinding UI.
Methods
ApplyBindingOverride(InputAction, int, 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. |
int | 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, int, InputBinding) like so:
action.ApplyBindingOverride(new InputBinding { overridePath = path });
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentOutOfRangeException |
|
See Also
ApplyBindingOverride(InputAction, int, 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. |
int | 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 |
|
ArgumentOutOfRangeException |
|
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, |
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 |
|
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 |
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 |
|
See Also
ApplyBindingOverride(InputActionMap, int, 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. |
int | bindingIndex | Index of the binding to modify in bindings of
|
InputBinding | bindingOverride | Binding whose override properties (overridePath, overrideProcessors, and overrideInteractions) to copy. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentOutOfRangeException |
|
See Also
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 |
Returns
Type | Description |
---|---|
int | The number of bindings overridden in the given map. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
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 |
See Also
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 |
---|---|
int | 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 |
|
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 |
---|---|
int | 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 |
|
See Also
ApplyParameterOverride(InputAction, string, PrimitiveValue, int)
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 |
PrimitiveValue | value | New value to assign to the parameter. |
int | bindingIndex | Index of the binding in bindings of |
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 |
|
ArgumentNullException |
|
See Also
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)
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 |
PrimitiveValue | value | New value to assign to the parameter. |
InputBinding | bindingMask | A binding mask that determines which of |
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 |
|
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)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | An |
string | name | Name of the parameter to get the value of. Case-insensitive. This can either be just the name of the
parameter (like |
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 |
|
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)
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 |
PrimitiveValue | value | New value to assign to the parameter. |
InputBinding | bindingMask | A binding mask that determines which of |
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 |
|
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) 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 |
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 |
|
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) 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 |
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 |
|
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) 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 |
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 |
|
See Also
GetBindingDisplayString(InputAction, int, out string, out string, 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. |
int | bindingIndex | Index of the binding in the bindings array of
|
string | deviceLayoutName | Receives the name of the InputControlLayout used for the
device in the given binding, if applicable. Otherwise is set to |
string | controlPath | Receives the path to the control on the device referenced in the given binding,
if applicable. Otherwise is set to |
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 |
|
See Also
GetBindingDisplayString(InputAction, int, 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. |
int | bindingIndex | Index of the binding in the bindings array of
|
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 |
|
See Also
GetBindingDisplayString(InputAction, 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 |
|
See Also
GetBindingDisplayString(InputAction, 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, 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 |
|
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 |
---|---|
InputBinding? | The binding from which |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
See Also
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 |
---|---|
int | 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 |
|
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 |
---|---|
int | The first binding on the action matching |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
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 |
---|---|
int | The first binding on the action matching |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
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 |
---|---|
int | The index into the action's binding array for the binding that |
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 |
|
See Also
GetParameterValue(InputAction, string, int)
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 |
int | bindingIndex | Index of the binding in |
Returns
Type | Description |
---|---|
PrimitiveValue? | The current value of the given parameter or |
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 |
|
See Also
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)
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 |
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 |
---|---|
PrimitiveValue? | The current value of the given parameter or |
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 |
|
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) 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 |
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 |
---|---|
TValue? | The current value of the given parameter or |
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 |
|
See Also
LoadBindingOverridesFromJson(IInputActionCollection2, string, bool)
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). |
bool | removeExisting | If true (default), all existing overrides present on the bindings
of |
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 |
|
See Also
LoadBindingOverridesFromJson(InputAction, string, bool)
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). |
bool | removeExisting | If true (default), all existing overrides present on the bindings
of |
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 |
|
See Also
PerformInteractiveRebinding(InputAction, int)
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. |
int | bindingIndex | Optional index (within the bindings array of |
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:
- WithAction(InputAction) will be called with
action
- The default timeout will be set to 0.05f seconds with OnMatchWaitForAnother(float).
- Pointer delta and position as well as touch position and delta controls will be excluded with WithControlsExcluding(string). This prevents mouse movement or touch leading to rebinds as it will generally be used to operate the UI.
- WithMatchingEventsBeingSuppressed(bool) will be invoked to suppress input funneled into rebinds from being picked up elsewhere.
- Except if the rebind is looking for a button, escapeKey will be set up to cancel the rebind using WithCancelingThrough(string).
- If
bindingIndex
is given, WithTargetBinding(int) is invoked to target the given binding with the rebind.
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 |
|
ArgumentOutOfRangeException |
|
InvalidOperationException | The binding at |
See Also
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 |
|
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 |
|
See Also
RemoveBindingOverride(InputAction, int)
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. |
int | bindingIndex | Index of the binding within |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentOutOfRangeException |
|
See Also
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 |
Remarks
// Remove all binding overrides from bindings associated with the "Gamepad" binding group.
myAction.RemoveBindingOverride(InputBinding.MaskByGroup("Gamepad"));
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
See Also
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
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 |
|
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 |
Remarks
This overrides can be restored using LoadBindingOverridesFromJson(InputAction, string, bool).
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|