docs.unity3d.com
    Show / Hide Table of Contents

    Class InputActionSetupExtensions

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

    Inheritance
    Object
    InputActionSetupExtensions
    Namespace: UnityEngine.InputSystem
    Syntax
    public static class InputActionSetupExtensions : object
    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)

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

    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.

    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.

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

    See Also
    bindings

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

    See Also
    InputBinding
    bindings

    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.

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

    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.

    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");

    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.

    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");

    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");

    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");

    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");

    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");

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

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

    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.

    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.

    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.

    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.

    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
    Back to top
    Terms of use
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023