Class InputActionSetupExtensions

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

Inheritance

InputActionSetupExtensions

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 `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 InvalidOperationException `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.

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	`action` is null or `control` is null.

AddBinding(InputActionMap, String, Guid, String, String)

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
String	path
Guid	action
String	interactions
String	groups

Returns

Type	Description
InputActionSetupExtensions.BindingSyntax

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

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

AddBinding(InputActionMap, InputBinding)

Declaration

public static InputActionSetupExtensions.BindingSyntax AddBinding(this InputActionMap actionMap, InputBinding binding)

Parameters

Type	Name	Description
InputActionMap	actionMap
InputBinding	binding

Returns

Type	Description
InputActionSetupExtensions.BindingSyntax

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

Declaration

public static InputActionSetupExtensions.BindingSyntax ChangeBinding(this InputAction action, string name)

Parameters

Type	Name	Description
InputAction	action
String	name

Returns

Type	Description
InputActionSetupExtensions.BindingSyntax

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, 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 `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.

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.

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

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

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.

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)

Declaration

public static InputControlScheme WithBindingGroup(this InputControlScheme scheme, string bindingGroup)

Parameters

Type	Name	Description
InputControlScheme	scheme
String	bindingGroup

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

Class InputActionSetupExtensions

Inheritance

Namespace: UnityEngine.InputSystem

Syntax

Remarks

Methods

AddAction(InputActionMap, String, InputActionType, String, String, String, String, String)

Declaration

Parameters

Returns

Exceptions

AddActionMap(InputActionAsset, String)

Declaration

Parameters

Returns

Exceptions

AddActionMap(InputActionAsset, InputActionMap)

Declaration

Parameters

Exceptions

See Also

AddBinding(InputAction, String, String, String, String)

Declaration

Parameters

Returns

AddBinding(InputAction, InputBinding)

Declaration

Parameters

Returns

Remarks

AddBinding(InputAction, InputControl)

Declaration

Parameters

Returns

Exceptions

See Also

AddBinding(InputActionMap, String, Guid, String, String)

Declaration

Parameters

Returns

AddBinding(InputActionMap, String, String, String, String, String)

Declaration

Parameters

Returns

Remarks

Exceptions

See Also

AddBinding(InputActionMap, String, InputAction, String, String)

Declaration

Parameters

Returns

Exceptions

See Also

AddBinding(InputActionMap, InputBinding)

Declaration

Parameters

Returns

AddCompositeBinding(InputAction, String, String, String)

Declaration

Parameters

Returns

Exceptions

AddControlScheme(InputActionAsset, String)

Declaration

Parameters

Returns

Remarks

Exceptions

AddControlScheme(InputActionAsset, InputControlScheme)

Declaration

Parameters

Exceptions

ChangeBinding(InputAction, Int32)

Declaration

Parameters

Returns

Remarks

Exceptions

ChangeBinding(InputAction, String)

Declaration