Class InputActionAsset

An asset that contains action maps and control schemes.

Inheritance
Object
Object
ScriptableObject
InputActionAsset
Inherited Members
Namespace: UnityEngine.InputSystem
Syntax
public class InputActionAsset : ScriptableObject, IInputActionCollection2, IInputActionCollection, IEnumerable<InputAction>, IEnumerable
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 = "inputactions"
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

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

bindings

Iterate over all bindings in the asset.

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

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

See Also

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
See Also

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

enabled

True if any action in the asset is currently enabled.

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

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 KeyNotFoundException if no action with the given name or ID could be found.

Exceptions
Type Condition
KeyNotFoundException

No action was found matching actionNameOrId.
ArgumentNullException

actionNameOrId is null or empty.
See Also

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

Disable()

Disable all action maps in the asset.

Declaration
public void Disable()
Implements
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
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
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.
Exceptions
Type Condition
ArgumentNullException

actionNameOrId is null.
ArgumentException

Thrown if throwIfNotFound is true and the action could not be found. -Or- If actionNameOrId contains a slash but is missing either the action or the map name.

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

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.
Exceptions
Type Condition
ArgumentNullException

nameOrId is null.
ArgumentException

If throwIfNotFound is true, thrown if the action map cannot be found.
See Also

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

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.
Exceptions
Type Condition
ArgumentNullException

name is null or empty.

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.
Exceptions
Type Condition
ArgumentNullException

name is null or empty.

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>"" }
            ]
        }
    ]
}");
Exceptions
Type Condition
ArgumentNullException

json is null or empty.
See Also

GetEnumerator()

Enumerate all actions in the asset.

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

An enumerator going over the actions in the asset.
Implements
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]))
    /* ... */;
Exceptions
Type Condition
ArgumentNullException

device is null.
See Also

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>"" }
            ]
        }
    ]
}");
Exceptions
Type Condition
ArgumentNullException

json is null or empty.
See Also

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

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Enumerate all actions in the asset.

Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type Description
IEnumerator

An enumerator going over the actions in the asset.
Implements
See Also

Extension Methods