Class InputActionSetupExtensions
Methods to change the setup of InputAction, InputActionMap, and InputActionAsset objects.
Namespace: UnityEngine.InputSystem
Syntax
public static class InputActionSetupExtensions
Remarks
Unlike the methods in InputActionRebindingExtensions, the methods here are generally destructive, i.e. they will rearrange the data for actions.
Methods
AddAction(InputActionMap, String, InputActionType, String, String, String, String, String)
Add a new InputAction to the given map
.
Declaration
public static InputAction AddAction(this InputActionMap map, string name, InputActionType type = InputActionType.Value, string binding = null, string interactions = null, string processors = null, string groups = null, string expectedControlLayout = null)
Parameters
Type | Name | Description |
---|---|---|
InputActionMap | map | Action map to add the action to. The action will be appended to actions of the map. The map must be disabled (see enabled). |
String | name | Name to give to the action. Must not be |
InputActionType | type | Action type. See type. |
String | binding | If not |
String | interactions | If |
String | processors | If |
String | groups | If |
String | expectedControlLayout | Value for expectedControlType; |
Returns
Type | Description |
---|---|
InputAction | The newly added input action. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException |
|
InvalidOperationException |
|
AddActionMap(InputActionAsset, String)
Create an action map with the given name and add it to the asset.
Declaration
public static InputActionMap AddActionMap(this InputActionAsset asset, string name)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to add the action map to |
String | name | Name to assign to the |
Returns
Type | Description |
---|---|
InputActionMap | The newly added action map. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
AddActionMap(InputActionAsset, InputActionMap)
Add an action map to the asset.
Declaration
public static void AddActionMap(this InputActionAsset asset, InputActionMap map)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to add the map to. |
InputActionMap | map | A named action map. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
InvalidOperationException |
|
See Also
AddBinding(InputAction, String, String, String, String)
Add a new binding to the given action.
Declaration
public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputAction action, string path, string interactions = null, string processors = null, string groups = null)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action to add the binding to. If the action is part of an InputActionMap, the newly added binding will be visible on bindings. |
String | path | Binding path string. See path for details. |
String | interactions | Optional list of interactions to apply to the binding. See interactions for details. |
String | processors | Optional list of processors to apply to the binding. See processors for details. |
String | groups | Optional list of binding groups that should be assigned to the binding. See groups for details. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | Fluent-style syntax to further configure the binding. |
AddBinding(InputAction, InputBinding)
Add a new binding to the action.
Declaration
public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputAction action, InputBinding binding = default(InputBinding))
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | An action to add the binding to. |
InputBinding | binding | Binding to add to the action or default. Binding can be further configured via the struct returned by the method. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | Returns a fluent-style syntax structure that allows performing additional modifications based on the new binding. |
Remarks
This works both with actions that are part of an action set as well as with actions that aren't.
Note that actions must be disabled while altering their binding sets. Also, if the action belongs to a set, all actions in the set must be disabled.
fireAction.AddBinding()
.WithPath("<Gamepad>/buttonSouth")
.WithGroup("Gamepad");
AddBinding(InputAction, InputControl)
Add a binding that references the given control
and triggers
the given .
Declaration
public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputAction action, InputControl control)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action to trigger. |
InputControl | control | Control to bind to. The full path of the control will be used in the resulting InputBinding. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | Syntax to configure the binding further. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
See Also
AddBinding(InputActionMap, String, Guid, String, String)
Add a new binding that triggers the action given by GUID action
.
Declaration
public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputActionMap actionMap, string path, Guid action, string interactions = null, string groups = null)
Parameters
Type | Name | Description |
---|---|---|
InputActionMap | actionMap | Action map to add the binding to. |
String | path | Path of the control(s) to bind to. See InputControlPath and path. |
Guid | action | ID of the action as per id. |
String | interactions | Optional list of names and parameters for interactions to apply to the binding. See interactions. |
String | groups | Optional list of groups to apply to the binding. See groups. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write-accessor to the newly added binding. |
Remarks
Example of adding a binding to an action map that binds to a Gamepad device "leftStick" control and associates it with an action:
var map = new InputActionMap();
var action = map.AddAction("action");
map.AddBinding("<Gamepad>/leftStick", action: action.id);
Exceptions
Type | Condition |
---|---|
ArgumentException |
|
ArgumentNullException |
|
See Also
AddBinding(InputActionMap, String, String, String, String, String)
Add a new binding to the given action map.
Declaration
public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputActionMap actionMap, string path, string interactions = null, string groups = null, string action = null, string processors = null)
Parameters
Type | Name | Description |
---|---|---|
InputActionMap | actionMap | Action map to add the binding to. |
String | path | Path of the control(s) to bind to. See InputControlPath and path. |
String | interactions | Names and parameters for interactions to apply to the binding. See interactions. |
String | groups | Optional list of groups to apply to the binding. See groups. |
String | action | Action to trigger from the binding. See action. |
String | processors | Optional list of processors to apply to the binding. See processors. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write-accessor to the newly added binding. |
Remarks
// Add a binding for the A button the gamepad and make it trigger
// the "fire" action.
var gameplayActions = playerInput.actions.FindActionMap("gameplay");
gameplayActions.AddBinding("<Gamepad>/buttonSouth", action: "fire");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
See Also
AddBinding(InputActionMap, String, InputAction, String, String)
Add a new binding that triggers the given action to the given action map.
Declaration
public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputActionMap actionMap, string path, InputAction action, string interactions = null, string groups = null)
Parameters
Type | Name | Description |
---|---|---|
InputActionMap | actionMap | Action map to add the binding to. |
String | path | Path of the control(s) to bind to. See InputControlPath and path. |
InputAction | action | Action to trigger from the binding. See action.
Must be part of |
String | interactions | Names and parameters for interactions to apply to the binding. See interactions. |
String | groups | Binding groups to apply to the binding. See groups. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write-accessor to the newly added binding. |
Exceptions
Type | Condition |
---|---|
ArgumentException |
|
ArgumentNullException |
|
See Also
AddBinding(InputActionMap, InputBinding)
Add a binding to the given action map.
Declaration
public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputActionMap actionMap, InputBinding binding)
Parameters
Type | Name | Description |
---|---|---|
InputActionMap | actionMap | Action map to add the binding to. |
InputBinding | binding | Binding to add to the action map. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write-accessor to the newly added binding. |
Exceptions
Type | Condition |
---|---|
ArgumentException |
|
ArgumentNullException |
|
See Also
AddCompositeBinding(InputAction, String, String, String)
Add a composite binding to the bindings of action
.
Declaration
public static InputActionSetupExtensions.CompositeSyntax AddCompositeBinding(this InputAction action, string composite, string interactions = null, string processors = null)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action to add the binding to. |
String | composite | Type of composite to add. This needs to be the name the composite has been registered under using RegisterBindingComposite<T>(String). Case-insensitive. |
String | interactions | Interactions to add to the binding. See interactions. |
String | processors | Processors to add to the binding. See processors. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.CompositeSyntax | A write accessor to the newly added composite binding. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException |
|
AddControlScheme(InputActionAsset, String)
Add a new control scheme to the given asset
.
Declaration
public static InputActionSetupExtensions.ControlSchemeSyntax AddControlScheme(this InputActionAsset asset, string name)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to add the control scheme to. |
String | name | Name to give to the control scheme. Must be unique within the control schemes of the asset. Also used as default name of bindingGroup associated with the control scheme. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.ControlSchemeSyntax | Syntax to allow providing additional configuration for the newly added control scheme. |
Remarks
// Create an .inputactions asset.
var asset = ScriptableObject.CreateInstance<InputActionAsset>();
// Add an action map to it.
var actionMap = asset.AddActionMap("actions");
// Add an action to it and bind it to the A button on the gamepad.
// Also, associate that binding with the "Gamepad" control scheme.
var action = actionMap.AddAction("action");
action.AddBinding("<Gamepad>/buttonSouth", groups: "Gamepad");
// Add a control scheme called "Gamepad" that requires a Gamepad device.
asset.AddControlScheme("Gamepad")
.WithRequiredDevice<Gamepad>();
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
AddControlScheme(InputActionAsset, InputControlScheme)
Add a new control scheme to the asset.
Declaration
public static void AddControlScheme(this InputActionAsset asset, InputControlScheme controlScheme)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to add the control scheme to. |
InputControlScheme | controlScheme | Control scheme to add. |
Exceptions
Type | Condition |
---|---|
ArgumentException |
|
ArgumentNullException |
|
InvalidOperationException | A control scheme with the same name as |
ChangeBinding(InputAction, Int32)
Get write access to the binding in bindings of action
at the given index
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBinding(this InputAction action, int index)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action whose bindings to change. |
Int32 | index | Index in |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the given binding. |
Remarks
// Grab "fire" action from PlayerInput.
var fireAction = playerInput.actions["fire"];
// Change its second binding to go to the left mouse button.
fireAction.ChangeBinding(1)
.WithPath("<Mouse>/leftButton");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentOutOfRangeException |
|
ChangeBinding(InputAction, String)
Get write access to the binding in bindings of action
with the given name
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBinding(this InputAction action, string name)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action whose bindings to change. |
String | name | Name of the binding to be changed bindings. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the given binding. |
Remarks
// Grab "fire" action from PlayerInput.
var fireAction = playerInput.actions["fire"];
// Change its second binding to go to the left mouse button.
fireAction.ChangeBinding("fire")
.WithPath("<Mouse>/leftButton");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentOutOfRangeException |
|
ChangeBinding(InputAction, InputBinding)
Get write access to the binding on action
that matches the given
match
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBinding(this InputAction action, InputBinding match)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action whose bindings to match against. |
InputBinding | match | A binding mask. See Matches(InputBinding) for details. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write-accessor to the first binding matching |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ChangeBinding(InputActionMap, Int32)
Get write access to the binding in bindings of actionMap
at the given index
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBinding(this InputActionMap actionMap, int index)
Parameters
Type | Name | Description |
---|---|---|
InputActionMap | actionMap | Action map whose bindings to change. |
Int32 | index | Index in |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the given binding. |
Remarks
// Grab "gameplay" actions from PlayerInput.
var gameplayActions = playerInput.actions.FindActionMap("gameplay");
// Change its second binding to go to the left mouse button.
gameplayActions.ChangeBinding(1)
.WithPath("<Mouse>/leftButton");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentOutOfRangeException |
|
ChangeBindingWithGroup(InputAction, String)
Get write access to the first binding in bindings of action
that is assigned to the given binding group
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBindingWithGroup(this InputAction action, string group)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action whose bindings to change. |
String | group | Name of the binding group as per groups. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the first binding on |
Remarks
// Grab "fire" action from PlayerInput.
var fireAction = playerInput.actions["fire"];
// Change the binding in the "Keyboard&Mouse" group to go to the left mouse button.
fireAction.ChangeBindingWithGroup("Keyboard&Mouse")
.WithPath("<Mouse>/leftButton");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException | No binding on the |
ChangeBindingWithId(InputAction, Guid)
Get write access to the binding in bindings of action
that has the given id
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBindingWithId(this InputAction action, Guid id)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action whose bindings to change. |
Guid | id | ID of the binding as per id. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the binding with the given ID. |
Remarks
// Grab "fire" action from PlayerInput.
var fireAction = playerInput.actions["fire"];
// Change the binding with the given ID to go to the left mouse button.
fireAction.ChangeBindingWithId(new Guid("c3de9215-31c3-4654-8562-854bf2f7864f"))
.WithPath("<Mouse>/leftButton");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException | No binding with the given |
ChangeBindingWithId(InputAction, String)
Get write access to the binding in bindings of action
that has the given id
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBindingWithId(this InputAction action, string id)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action whose bindings to change. |
String | id | ID of the binding as per id. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the binding with the given ID. |
Remarks
// Grab "fire" action from PlayerInput.
var fireAction = playerInput.actions["fire"];
// Change the binding with the given ID to go to the left mouse button.
fireAction.ChangeBindingWithId("c3de9215-31c3-4654-8562-854bf2f7864f")
.WithPath("<Mouse>/leftButton");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException | No binding with the given |
ChangeBindingWithPath(InputAction, String)
Get write access to the binding in bindings of action
that is bound to the given path
.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeBindingWithPath(this InputAction action, string path)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action whose bindings to change. |
String | path | Path of the binding as per path. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the binding on |
Remarks
// Grab "fire" action from PlayerInput.
var fireAction = playerInput.actions["fire"];
// Change the binding to the right mouse button to go to the left mouse button instead.
fireAction.ChangeBindingWithPath("<Mouse>/rightButton")
.WithPath("<Mouse>/leftButton");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException | No binding on the |
ChangeCompositeBinding(InputAction, String)
Get a write accessor to the binding of action
that is both a composite
(see isComposite) and has the given binding name or composite
type.
Declaration
public static InputActionSetupExtensions.BindingSyntax ChangeCompositeBinding(this InputAction action, string compositeName)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action to look up the binding on. All bindings in the action's bindings property will be considered. |
String | compositeName | Either the name of the composite binding (see name) to look for or the name of the composite type used in the binding (such as "1DAxis"). Case-insensitive. |
Returns
Type | Description |
---|---|
InputActionSetupExtensions.BindingSyntax | A write accessor to the given composite binding or an invalid accessor if no composite
matching |
Remarks
// Add arrow keys as alternatives to the WASD Vector2 composite.
playerInput.actions["move"]
.ChangeCompositeBinding("WASD")
.InsertPartBinding("Up", "<Keyboard>/upArrow")
.InsertPartBinding("Down", "<Keyboard>/downArrow")
.InsertPartBinding("Left", "<Keyboard>/leftArrow")
.InsertPartBinding("Right", "<Keyboard>/rightArrow");
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
See Also
OrWithOptionalDevice(InputControlScheme, String)
Declaration
public static InputControlScheme OrWithOptionalDevice(this InputControlScheme scheme, string controlPath)
Parameters
Type | Name | Description |
---|---|---|
InputControlScheme | scheme | |
String | controlPath |
Returns
Type | Description |
---|---|
InputControlScheme |
OrWithRequiredDevice(InputControlScheme, String)
Declaration
public static InputControlScheme OrWithRequiredDevice(this InputControlScheme scheme, string controlPath)
Parameters
Type | Name | Description |
---|---|---|
InputControlScheme | scheme | |
String | controlPath |
Returns
Type | Description |
---|---|
InputControlScheme |
RemoveAction(InputAction)
Remove the given action from its InputActionMap.
Declaration
public static void RemoveAction(this InputAction action)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | An input action that is part of an InputActionMap. |
Remarks
After removal, the action's actionMap will be set to null
and the action will effectively become a standalone action that is not associated with
any action map. Bindings on the action will be preserved. On the action map, the bindings
for the action will be removed.
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException |
|
InvalidOperationException |
|
See Also
RemoveAction(InputActionAsset, String)
Remove the action with the given name from the asset.
Declaration
public static void RemoveAction(this InputActionAsset asset, string nameOrId)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to remove the action from. |
String | nameOrId | Name or ID of the action. See FindAction(String, Boolean) for details. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
See Also
RemoveActionMap(InputActionAsset, String)
Remove the action map with the given name or ID from the asset.
Declaration
public static void RemoveActionMap(this InputActionAsset asset, string nameOrId)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to remove the action map from. |
String | nameOrId | The name or ID (see id) of a map in the asset. Note that lookup is case-insensitive. If no map with the given name or ID is found, the method does nothing. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
InvalidOperationException | The map referenced by |
See Also
RemoveActionMap(InputActionAsset, InputActionMap)
Remove the given action map from the asset.
Declaration
public static void RemoveActionMap(this InputActionAsset asset, InputActionMap map)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to add the action map to. |
InputActionMap | map | An action map. If the given map is not part of the asset, the method does nothing. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
InvalidOperationException |
|
See Also
RemoveControlScheme(InputActionAsset, String)
Remove the control scheme with the given name from the asset.
Declaration
public static void RemoveControlScheme(this InputActionAsset asset, string name)
Parameters
Type | Name | Description |
---|---|---|
InputActionAsset | asset | Asset to remove the control scheme from. |
String | name | Name of the control scheme. Matching is case-insensitive. |
Remarks
If no control scheme with the given name can be found, the method does nothing.
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
Rename(InputAction, String)
Rename an existing action.
Declaration
public static void Rename(this InputAction action, string newName)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | Action to assign a new name to. Can be singleton action or action that is part of a map. |
String | newName | New name to assign to action. Cannot be empty. |
Remarks
Renaming an action will also update the bindings that refer to the action.
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
InvalidOperationException | actionMap of |
WithBindingGroup(InputControlScheme, String)
Associates the control scheme given by scheme
with the binding group given by bindingGroup
.
Declaration
public static InputControlScheme WithBindingGroup(this InputControlScheme scheme, string bindingGroup)
Parameters
Type | Name | Description |
---|---|---|
InputControlScheme | scheme | The control scheme to modify. |
String | bindingGroup | The binding group to be associated with the control scheme. |
Returns
Type | Description |
---|---|
InputControlScheme |
|
WithDevice(InputControlScheme, String, Boolean)
Declaration
public static InputControlScheme WithDevice(this InputControlScheme scheme, string controlPath, bool required)
Parameters
Type | Name | Description |
---|---|---|
InputControlScheme | scheme | |
String | controlPath | |
Boolean | required |
Returns
Type | Description |
---|---|
InputControlScheme |
WithOptionalDevice(InputControlScheme, String)
Declaration
public static InputControlScheme WithOptionalDevice(this InputControlScheme scheme, string controlPath)
Parameters
Type | Name | Description |
---|---|---|
InputControlScheme | scheme | |
String | controlPath |
Returns
Type | Description |
---|---|
InputControlScheme |
WithRequiredDevice(InputControlScheme, String)
Declaration
public static InputControlScheme WithRequiredDevice(this InputControlScheme scheme, string controlPath)
Parameters
Type | Name | Description |
---|---|---|
InputControlScheme | scheme | |
String | controlPath |
Returns
Type | Description |
---|---|
InputControlScheme |