Class InputActionSetupExtensions

Methods to change the setup of InputAction, InputActionMap, and InputActionAsset objects.

Inheritance

object

InputActionSetupExtensions

Namespace: UnityEngine.InputSystem

Assembly: Unity.InputSystem.dll

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 null or empty. Also, no other action that already exists in map must have this name already.
InputActionType	type	Action type. See type.
string	binding	If not null, a binding is automatically added to the newly created action with the value of this parameter being used as the binding's path.
string	interactions	If binding is not null, this string is used for interactions of the binding that is automatically added for the action.
string	processors	If binding is not null, this string is used for processors of the binding that is automatically added for the action.
string	groups	If binding is not null, this string is used for groups of the binding that is automatically added for the action.
string	expectedControlLayout	Value for expectedControlType; null by default.

Returns

Type	Description
InputAction	The newly added input action.

Exceptions

Type	Condition
ArgumentNullException	map is null.
ArgumentException	name is null or empty.
InvalidOperationException	map is enabled (see enabled) or is part of an InputActionAsset that has InputActionMaps that are enabled -or- map already contains an action called name (case-insensitive).

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	asset is null or An action map with the given name already exists in asset. name is null or empty.

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	map or asset is null.
InvalidOperationException	map has no name or asset already contains a map with the same name -or- map is currently enabled -or- map is part of an InputActionAsset that has InputActionMaps that are enabled.

See Also

actionMaps

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)

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 binding.

Returns

Type	Description
InputActionSetupExtensions.BindingSyntax	Syntax to configure the binding further.

Exceptions

Type	Condition
ArgumentNullException	action is null or control is null.

See Also

bindings

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	action is not part of actionMap.
ArgumentNullException	path is null.

See Also

InputBinding

bindings

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	path is null.

See Also

InputBinding

bindings

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 actionMap.
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	action is not part of actionMap.
ArgumentNullException	path is null.

See Also

InputBinding

bindings

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	action is not part of actionMap.
ArgumentNullException	path is null.

See Also

InputBinding

bindings

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	action is null.
ArgumentException	composite is null or empty.

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 binding group 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	asset is null -or- name is null or empty.

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	controlScheme has no name.
ArgumentNullException	asset is null.
InvalidOperationException	A control scheme with the same name as controlScheme already exists in the asset.

ChangeBinding(InputAction, int)

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.
int	index	Index in action's bindings of the binding to be changed.

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	action is null.
ArgumentOutOfRangeException	index is out of range (as per bindings of action).

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	action is null.
ArgumentOutOfRangeException	index is out of range (as per bindings of action).

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 match or an invalid accessor (see valid) if no binding was found to match the mask.

Exceptions

Type	Condition
ArgumentNullException	action is null.

ChangeBinding(InputActionMap, int)

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.
int	index	Index in actionMap's bindings of the binding to be changed.

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	actionMap is null.
ArgumentOutOfRangeException	index is out of range (as per bindings of actionMap).

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 action that is assigned to the given binding group.

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	action is null.
ArgumentException	No binding on the action is assigned to the given binding group.

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	action is null.
ArgumentException	No binding with the given id exists on action.

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	action is null.
ArgumentException	No binding with the given id exists on action.

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 action that is assigned the given path.

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	action is null.
ArgumentException	No binding on the action is assigned the given path.

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 compositeName could be found on action.

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	action is null -or- compositeName is null or empty.

See Also

isComposite

InputBindingComposite

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	action is null.
ArgumentException	action is a standalone action that is not part of an InputActionMap and thus cannot be removed from anything.
InvalidOperationException	action is part of an InputActionMap or InputActionAsset that has at least one enabled action.

See Also

AddAction(InputActionMap, string, InputActionType, string, string, string, string, string)

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, bool) for details.

Exceptions

Type	Condition
ArgumentNullException	asset is null -or- nameOrId is null or empty.

See Also

RemoveAction(InputAction)

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	asset or nameOrId is null.
InvalidOperationException	The map referenced by nameOrId is currently enabled (see enabled).

See Also

RemoveActionMap(InputActionAsset, string)

actionMaps

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	asset or map is null.
InvalidOperationException	map is currently enabled (see enabled) or is part of an InputActionAsset that has InputActionMaps that are currently enabled.

See Also

RemoveActionMap(InputActionAsset, string)

actionMaps

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	asset is null -or- name is null or empty.

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	action is null or newName is null or empty.
InvalidOperationException	actionMap of action already contains an action called newName.

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	scheme

WithDevice(InputControlScheme, string, bool)

Declaration

public static InputControlScheme WithDevice(this InputControlScheme scheme, string controlPath, bool required)

Parameters

Type	Name	Description
InputControlScheme	scheme
string	controlPath
bool	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