docs.unity.cn
    Show / Hide Table of Contents

    Class InputActionAsset

    An asset that contains action maps and control schemes.

    Inheritance
    Object
    InputActionAsset
    Namespace: UnityEngine.InputSystem
    Syntax
    public class InputActionAsset : ScriptableObject, IInputActionCollection2, IInputActionCollection, IEnumerable<InputAction>
    Remarks

    InputActionAssets can be created in code but are usually stored in JSON format on disk with the ".inputactions" extension. Unity imports them with a custom importer.

    To create an InputActionAsset in code, use the Singleton API and populate the asset with the methods found in InputActionSetupExtensions. Alternatively, you can use FromJson(String) to load an InputActionAsset directly from a string in JSON format.

    // Create and configure an asset in code.
    var asset1 = ScriptableObject.CreateInstance<InputActionAsset>();
    var actionMap1 = asset1.AddActionMap("map1");
    action1Map.AddAction("action1", binding: "<Keyboard>/space");

    If you use the API to modify an InputActionAsset while in Play mode, it does not survive the transition back to Edit Mode. Unity tracks and reloads modified assets from disk when exiting Play mode. This is done so that you can realistically test the input related functionality of your application i.e. control rebinding etc, without inadvertently changing the input asset.

    Each asset can contain arbitrary many action maps that you can enable and disable individually (see Enable() and Disable()) or in bulk (see Enable() and Disable()). The name of each action map must be unique. The list of action maps can be queried from actionMaps.

    InputActionAssets can only define InputControlSchemes. They can be added to an asset with AddControlScheme(InputActionAsset, String) and can be queried from controlSchemes.

    Be aware that input action assets do not separate between static (configuration) data and dynamic (instance) data. For audio, for example, AudioClip represents the static, shared data portion of audio playback whereas AudioSource" represents the dynamic, per-instance audio playback portion (referencing the clip through AudioSource.clip).

    For input, such a split is less beneficial as the same input is generally not exercised multiple times in parallel. Keeping both static and dynamic data together simplifies using the system.

    However, there are scenarios where you indeed want to take the same input action and exercise it multiple times in parallel. A prominent example of such a use case is local multiplayer where each player gets the same set of actions but is controlling them with a different device (or devices) each. This is easily achieved by simply using UnityEngine.Object.Instantiate to instantiate the input action asset multiple times. PlayerInput will automatically do so in its internals.

    Note also that all action maps in an asset share binding state. This means that if one map in an asset has to resolve its bindings, all maps in the asset have to.

    Fields

    Extension

    File extension (without the dot) for InputActionAssets in JSON format.

    Declaration
    public const string Extension = null
    Field Value
    Type Description
    String

    File extension for InputActionAsset source files.

    Remarks

    Files with this extension will automatically be imported by Unity as InputActionAssets.

    Properties

    actionMaps

    List of action maps defined in the asset.

    Declaration
    public ReadOnlyArray<InputActionMap> actionMaps { get; }
    Property Value
    Type Description
    ReadOnlyArray<InputActionMap>

    Action maps contained in the asset.

    See Also
    AddActionMap(InputActionAsset, String)
    RemoveActionMap(InputActionAsset, InputActionMap)
    FindActionMap(String, Boolean)

    bindingMask

    Binding mask to apply to all action maps and actions in the asset.

    Declaration
    public InputBinding? bindingMask { get; set; }
    Property Value
    Type Description
    Nullable<InputBinding>

    Optional mask that determines which bindings in the asset to enable.

    Implements
    IInputActionCollection.bindingMask
    Remarks

    Binding masks can be applied at three different levels: for an entire asset through this property, for a specific map through bindingMask, and for single actions through bindingMask. By default, none of the masks will be set (i.e. they will be null).

    When an action is enabled, all the binding masks that apply to it are taken into account. Specifically, this means that any given binding on the action will be enabled only if it matches the mask applied to the asset, the mask applied to the map that contains the action, and the mask applied to the action itself. All the masks are individually optional.

    Masks are matched against bindings using Matches(InputBinding).

    Note that if you modify the masks applicable to an action while it is enabled, the action's controls will get updated immediately to respect the mask. To avoid repeated binding resolution, it is most efficient to apply binding masks before enabling actions.

    Binding masks are non-destructive. All the bindings on the action are left in place. Setting a mask will not affect the value of the bindings and bindings properties.

    See Also
    MaskByGroup(String)
    bindingMask
    bindingMask

    bindings

    Iterate over all bindings in the asset.

    Declaration
    public IEnumerable<InputBinding> bindings { get; }
    Property Value
    Type Description
    IEnumerable<InputBinding>
    Implements
    IInputActionCollection2.bindings
    Remarks

    This iterates over all action maps in actionMaps and, within each map, over the set of bindings.

    See Also
    bindings

    controlSchemes

    List of control schemes defined in the asset.

    Declaration
    public ReadOnlyArray<InputControlScheme> controlSchemes { get; }
    Property Value
    Type Description
    ReadOnlyArray<InputControlScheme>

    Control schemes defined for the asset.

    Implements
    IInputActionCollection.controlSchemes
    See Also
    AddControlScheme(InputActionAsset, String)
    RemoveControlScheme(InputActionAsset, String)

    devices

    Set of devices that bindings in the asset can bind to.

    Declaration
    public ReadOnlyArray<InputDevice>? devices { get; set; }
    Property Value
    Type Description
    Nullable<ReadOnlyArray<InputDevice>>

    Optional set of devices to use by bindings in the asset.

    Implements
    IInputActionCollection.devices
    Remarks

    By default (with this property being null), bindings will bind to any of the controls available through devices, i.e. controls from all devices in the system will be used.

    By setting this property, binding resolution can instead be restricted to just specific devices. This restriction can either be applied to an entire asset using this property or to specific action maps by using devices. Note that if both this property and devices is set for a specific action map, the list of devices on the action map will take precedence and the list on the asset will be ignored for bindings in that action map.

    // Create an asset with a single action map and a single action with a
    // gamepad binding.
    var asset = ScriptableObject.CreateInstance<InputActionAsset>();
    var actionMap = new InputActionMap();
    var fireAction = actionMap.AddAction("Fire", binding: "<Gamepad>/buttonSouth");
    asset.AddActionMap(actionMap);
    
    // Let's assume we have two gamepads connected. If we enable the
    // action map now, the 'Fire' action will bind to both.
    actionMap.Enable();
    
    // This will print two controls.
    Debug.Log(string.Join("\n", fireAction.controls));
    
    // To restrict the setup to just the first gamepad, we can assign
    // to the 'devices' property (in this case, we could do so on either
    // the action map or on the asset; we choose the latter here).
    asset.devices = new InputDevice[] { Gamepad.all[0] };
    
    // Now this will print only one control.
    Debug.Log(string.Join("\n", fireAction.controls));
    See Also
    devices

    enabled

    True if any action in the asset is currently enabled.

    Declaration
    public bool enabled { get; }
    Property Value
    Type Description
    Boolean
    See Also
    enabled
    enabled
    Enable()
    Enable()
    Enable()

    Item[String]

    Look up an action by name or ID.

    Declaration
    public InputAction this[string actionNameOrId] { get; }
    Parameters
    Type Name Description
    String actionNameOrId

    Name of the action as either a "map/action" combination (e.g. "gameplay/fire") or a simple name. In the former case, the name is split at the '/' slash and the first part is used to find a map with that name and the second part is used to find an action with that name inside the map. In the latter case, all maps are searched in order and the first action that has the given name in any of the maps is returned. Note that name comparisons are case-insensitive.

    Alternatively, the given string can be a GUID as given by id.

    Property Value
    Type Description
    InputAction

    The action with the corresponding name or null if no matching action could be found.

    Remarks

    This method is equivalent to FindAction(String, Boolean) except that it throws if no action with the given name or ID could be found.

    See Also
    FindAction(String, Boolean)

    Methods

    Contains(InputAction)

    Return true if the given action is part of the asset.

    Declaration
    public bool Contains(InputAction action)
    Parameters
    Type Name Description
    InputAction action

    An action. Can be null.

    Returns
    Type Description
    Boolean

    True if the given action is part of the asset, false otherwise.

    Implements
    IInputActionCollection.Contains(InputAction)

    Disable()

    Disable all action maps in the asset.

    Declaration
    public void Disable()
    Implements
    IInputActionCollection.Disable()
    Remarks

    This method is equivalent to calling Disable() on all maps in actionMaps.

    Enable()

    Enable all action maps in the asset.

    Declaration
    public void Enable()
    Implements
    IInputActionCollection.Enable()
    Remarks

    This method is equivalent to calling Enable() on all maps in actionMaps.

    FindAction(Guid)

    Find an action by its ID (see id).

    Declaration
    public InputAction FindAction(Guid guid)
    Parameters
    Type Name Description
    Guid guid

    ID of the action to look for.

    Returns
    Type Description
    InputAction

    The action in the asset with the given ID or null if no action in the asset has the given ID.

    FindAction(String, Boolean)

    Find an InputAction by its name in one of the InputActionMaps in the asset.

    Declaration
    public InputAction FindAction(string actionNameOrId, bool throwIfNotFound = false)
    Parameters
    Type Name Description
    String actionNameOrId

    Name of the action as either a "map/action" combination (e.g. "gameplay/fire") or a simple name. In the former case, the name is split at the '/' slash and the first part is used to find a map with that name and the second part is used to find an action with that name inside the map. In the latter case, all maps are searched in order and the first action that has the given name in any of the maps is returned. Note that name comparisons are case-insensitive.

    Alternatively, the given string can be a GUID as given by id.

    Boolean throwIfNotFound

    If true, instead of returning null when the action cannot be found, throw ArgumentException.

    Returns
    Type Description
    InputAction

    The action with the corresponding name or null if no matching action could be found.

    Implements
    IInputActionCollection2.FindAction(String, Boolean)
    Remarks

    Note that no lookup structures are used internally to speed the operation up. Instead, the search is done linearly. For repeated access of an action, it is thus generally best to look up actions once ahead of time and cache the result.

    If multiple actions have the same name and actionNameOrId is not an ID and not an action name qualified by a map name (that is, in the form of "mapName/actionName"), the action that is returned will be from the first map in actionMaps that has an action with the given name. An exception is if, of the multiple actions with the same name, some are enabled and some are disabled. In this case, the first action that is enabled is returned.

    var asset = ScriptableObject.CreateInstance<InputActionAsset>();
    
    var map1 = new InputActionMap("map1");
    var map2 = new InputActionMap("map2");
    
    asset.AddActionMap(map1);
    asset.AddActionMap(map2);
    
    var action1 = map1.AddAction("action1");
    var action2 = map1.AddAction("action2");
    var action3 = map2.AddAction("action3");
    
    // Search all maps in the asset for any action that has the given name.
    asset.FindAction("action1") // Returns action1.
    asset.FindAction("action2") // Returns action2
    asset.FindAction("action3") // Returns action3.
    
    // Search for a specific action in a specific map.
    asset.FindAction("map1/action1") // Returns action1.
    asset.FindAction("map2/action2") // Returns action2.
    asset.FindAction("map3/action3") // Returns action3.
    
    // Search by unique action ID.
    asset.FindAction(action1.id.ToString()) // Returns action1.
    asset.FindAction(action2.id.ToString()) // Returns action2.
    asset.FindAction(action3.id.ToString()) // Returns action3.

    FindActionMap(Guid)

    Find an InputActionMap in the asset by its ID.

    Declaration
    public InputActionMap FindActionMap(Guid id)
    Parameters
    Type Name Description
    Guid id

    ID (see id) of the action map to look for.

    Returns
    Type Description
    InputActionMap

    The InputActionMap with ID matching id or null if no map in the asset has the given ID.

    See Also
    actionMaps
    FindActionMap(String, Boolean)

    FindActionMap(String, Boolean)

    Find an InputActionMap in the asset by its name or ID.

    Declaration
    public InputActionMap FindActionMap(string nameOrId, bool throwIfNotFound = false)
    Parameters
    Type Name Description
    String nameOrId

    Name or ID (see id) of the action map to look for. Matching is case-insensitive.

    Boolean throwIfNotFound

    If true, instead of returning null, throw ArgumentException.

    Returns
    Type Description
    InputActionMap

    The InputActionMap with a name or ID matching nameOrId or null if no matching map could be found.

    See Also
    actionMaps

    FindBinding(InputBinding, out InputAction)

    Find the index of the first binding that matches the given mask.

    Declaration
    public int FindBinding(InputBinding mask, out InputAction action)
    Parameters
    Type Name Description
    InputBinding mask

    A binding. See Matches(InputBinding) for details.

    InputAction action

    Receives the action on which the binding was found. If none was found, will be set to null.

    Returns
    Type Description
    Int32

    Index into bindings of action of the binding that matches mask. If no binding matches, will return -1.

    Implements
    IInputActionCollection2.FindBinding(InputBinding, out InputAction)
    Remarks

    For details about matching bindings by a mask, see Matches(InputBinding).

    var index = playerInput.actions.FindBinding(
        new InputBinding { path = "<Gamepad>/buttonSouth" },
        out var action);
    
    if (index != -1)
        Debug.Log($"The A button is bound to {action}");
    See Also
    Matches(InputBinding)
    bindings

    FindControlScheme(String)

    Find the control scheme with the given name and return it.

    Declaration
    public InputControlScheme? FindControlScheme(string name)
    Parameters
    Type Name Description
    String name

    Name of the control scheme. Matching is case-insensitive.

    Returns
    Type Description
    Nullable<InputControlScheme>

    The control scheme with the given name or null if no scheme with the given name could be found in the asset.

    FindControlSchemeIndex(String)

    Find the control scheme with the given name and return its index in controlSchemes.

    Declaration
    public int FindControlSchemeIndex(string name)
    Parameters
    Type Name Description
    String name

    Name of the control scheme. Matching is case-insensitive.

    Returns
    Type Description
    Int32

    The index of the given control scheme or -1 if no control scheme with the given name could be found.

    FromJson(String)

    Replace the contents of the asset with the data in the given JSON string.

    Declaration
    public static InputActionAsset FromJson(string json)
    Parameters
    Type Name Description
    String json

    JSON contents of an .inputactions asset.

    Returns
    Type Description
    InputActionAsset

    The InputActionAsset instance created from the given JSON string.

    Remarks

    .inputactions assets are stored in JSON format. This method allows turning the JSON source text of such an asset into a new InputActionMap instance.

    Be aware that the format used by this method is different than what you get if you call JsonUtility.ToJson on an InputActionAsset instance. In other words, the JSON format is not identical to the Unity serialized object representation of the asset.

    var asset = InputActionAsset.FromJson(@"
    {
        ""maps"" : [
            {
                ""name"" : ""gameplay"",
                ""actions"" : [
                    { ""name"" : ""fire"", ""type"" : ""button"" },
                    { ""name"" : ""look"", ""type"" : ""value"" },
                    { ""name"" : ""move"", ""type"" : ""value"" }
                ],
                ""bindings"" : [
                    { ""path"" : ""<Gamepad>/buttonSouth"", ""action"" : ""fire"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""<Gamepad>/leftTrigger"", ""action"" : ""fire"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""<Gamepad>/leftStick"", ""action"" : ""move"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""<Gamepad>/rightStick"", ""action"" : ""look"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""dpad"", ""action"" : ""move"", ""groups"" : ""Gamepad"", ""isComposite"" : true },
                    { ""path"" : ""<Keyboard>/a"", ""name"" : ""left"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Keyboard>/d"", ""name"" : ""right"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Keyboard>/w"", ""name"" : ""up"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Keyboard>/s"", ""name"" : ""down"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Mouse>/delta"", ""action"" : ""look"", ""groups"" : ""Keyboard&Mouse"" },
                    { ""path"" : ""<Mouse>/leftButton"", ""action"" : ""fire"", ""groups"" : ""Keyboard&Mouse"" }
                ]
            },
            {
                ""name"" : ""ui"",
                ""actions"" : [
                    { ""name"" : ""navigate"" }
                ],
                ""bindings"" : [
                    { ""path"" : ""<Gamepad>/dpad"", ""action"" : ""navigate"", ""groups"" : ""Gamepad"" }
                ]
            }
        ],
        ""controlSchemes"" : [
            {
                ""name"" : ""Gamepad"",
                ""bindingGroup"" : ""Gamepad"",
                ""devices"" : [
                    { ""devicePath"" : ""<Gamepad>"" }
                ]
            },
            {
                ""name"" : ""Keyboard&Mouse"",
                ""bindingGroup"" : ""Keyboard&Mouse"",
                ""devices"" : [
                    { ""devicePath"" : ""<Keyboard>"" },
                    { ""devicePath"" : ""<Mouse>"" }
                ]
            }
        ]
    }");
    See Also
    LoadFromJson(String)
    ToJson()

    GetEnumerator()

    Enumerate all actions in the asset.

    Declaration
    public IEnumerator<InputAction> GetEnumerator()
    Returns
    Type Description
    IEnumerator<InputAction>

    Enumerate over all actions in the asset.

    Remarks

    Actions will be enumerated one action map in actionMaps after the other. The actions from each map will be yielded in turn.

    This method will allocate GC heap memory.

    IsUsableWithDevice(InputDevice)

    Return true if the asset contains bindings (in any of its action maps) that are usable with the given device.

    Declaration
    public bool IsUsableWithDevice(InputDevice device)
    Parameters
    Type Name Description
    InputDevice device

    An arbitrary input device.

    Returns
    Type Description
    Boolean
    Remarks
    // Find out if the actions of the given PlayerInput can be used with
    // a gamepad.
    if (playerInput.actions.IsUsableWithDevice(Gamepad.all[0]))
        /* ... */;
    See Also
    IsUsableWithDevice(InputDevice)
    SupportsDevice(InputDevice)

    LoadFromJson(String)

    Replace the contents of the asset with the data in the given JSON string.

    Declaration
    public void LoadFromJson(string json)
    Parameters
    Type Name Description
    String json

    JSON contents of an .inputactions asset.

    Remarks

    .inputactions assets are stored in JSON format. This method allows reading the JSON source text of such an asset into an existing InputActionMap instance.

    var asset = ScriptableObject.CreateInstance<InputActionAsset>();
    asset.LoadFromJson(@"
    {
        ""maps"" : [
            {
                ""name"" : ""gameplay"",
                ""actions"" : [
                    { ""name"" : ""fire"", ""type"" : ""button"" },
                    { ""name"" : ""look"", ""type"" : ""value"" },
                    { ""name"" : ""move"", ""type"" : ""value"" }
                ],
                ""bindings"" : [
                    { ""path"" : ""<Gamepad>/buttonSouth"", ""action"" : ""fire"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""<Gamepad>/leftTrigger"", ""action"" : ""fire"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""<Gamepad>/leftStick"", ""action"" : ""move"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""<Gamepad>/rightStick"", ""action"" : ""look"", ""groups"" : ""Gamepad"" },
                    { ""path"" : ""dpad"", ""action"" : ""move"", ""groups"" : ""Gamepad"", ""isComposite"" : true },
                    { ""path"" : ""<Keyboard>/a"", ""name"" : ""left"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Keyboard>/d"", ""name"" : ""right"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Keyboard>/w"", ""name"" : ""up"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Keyboard>/s"", ""name"" : ""down"", ""action"" : ""move"", ""groups"" : ""Keyboard&Mouse"", ""isPartOfComposite"" : true },
                    { ""path"" : ""<Mouse>/delta"", ""action"" : ""look"", ""groups"" : ""Keyboard&Mouse"" },
                    { ""path"" : ""<Mouse>/leftButton"", ""action"" : ""fire"", ""groups"" : ""Keyboard&Mouse"" }
                ]
            },
            {
                ""name"" : ""ui"",
                ""actions"" : [
                    { ""name"" : ""navigate"" }
                ],
                ""bindings"" : [
                    { ""path"" : ""<Gamepad>/dpad"", ""action"" : ""navigate"", ""groups"" : ""Gamepad"" }
                ]
            }
        ],
        ""controlSchemes"" : [
            {
                ""name"" : ""Gamepad"",
                ""bindingGroup"" : ""Gamepad"",
                ""devices"" : [
                    { ""devicePath"" : ""<Gamepad>"" }
                ]
            },
            {
                ""name"" : ""Keyboard&Mouse"",
                ""bindingGroup"" : ""Keyboard&Mouse"",
                ""devices"" : [
                    { ""devicePath"" : ""<Keyboard>"" },
                    { ""devicePath"" : ""<Mouse>"" }
                ]
            }
        ]
    }");
    See Also
    FromJson(String)
    ToJson()

    ToJson()

    Return a JSON representation of the asset.

    Declaration
    public string ToJson()
    Returns
    Type Description
    String

    A string in JSON format that represents the static/configuration data present in the asset.

    Remarks

    This will not save dynamic execution state such as callbacks installed on InputAction or enabled/disabled states of individual maps and actions.

    Use LoadFromJson(String) to deserialize the JSON data back into an InputActionAsset.

    Be aware that the format used by this method is different than what you get if you call JsonUtility.ToJson on an InputActionAsset instance. In other words, the JSON format is not identical to the Unity serialized object representation of the asset.

    See Also
    FromJson(String)

    Extension Methods

    InputActionRebindingExtensions.RemoveAllBindingOverrides(IInputActionCollection2)
    InputActionRebindingExtensions.SaveBindingOverridesAsJson(IInputActionCollection2)
    InputActionRebindingExtensions.LoadBindingOverridesFromJson(IInputActionCollection2, String, Boolean)
    InputActionSetupExtensions.AddActionMap(InputActionAsset, String)
    InputActionSetupExtensions.AddActionMap(InputActionAsset, InputActionMap)
    InputActionSetupExtensions.RemoveActionMap(InputActionAsset, InputActionMap)
    InputActionSetupExtensions.RemoveActionMap(InputActionAsset, String)
    InputActionSetupExtensions.RemoveAction(InputActionAsset, String)
    InputActionSetupExtensions.AddControlScheme(InputActionAsset, InputControlScheme)
    InputActionSetupExtensions.AddControlScheme(InputActionAsset, String)
    InputActionSetupExtensions.RemoveControlScheme(InputActionAsset, String)
    Back to top Copyright © 2022 Unity Technologies
    Generated by DocFX
    on Wednesday, January 5, 2022
    Terms of use