Class InputActionAsset

An asset that contains action maps and control schemes.

Inheritance

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.

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.

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.

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

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

enabled

True if any action in the asset is currently enabled.

Declaration

public bool enabled { get; }

Property Value

Type	Description
Boolean

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.

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.

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.

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

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

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]))
    /* ... */;

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

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.

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)

Class InputActionAsset

Inheritance

Namespace: UnityEngine.InputSystem

Syntax

Remarks

Fields

Extension

Declaration

Field Value

Remarks

Properties

actionMaps

Declaration

Property Value

See Also

bindingMask

Declaration

Property Value

Implements

Remarks

See Also

bindings

Declaration

Property Value

Implements

Remarks

See Also

controlSchemes

Declaration

Property Value

Implements

See Also

devices

Declaration

Property Value

Implements

Remarks

See Also

enabled

Declaration

Property Value

See Also

Item[String]

Declaration

Parameters

Property Value

Remarks

See Also

Methods

Contains(InputAction)

Declaration

Parameters

Returns

Implements

Disable()

Declaration

Implements

Remarks

Enable()

Declaration

Implements

Remarks

FindAction(Guid)

Declaration

Parameters

Returns

FindAction(String, Boolean)

Declaration

Parameters

Returns

Implements

Remarks

FindActionMap(Guid)

Declaration

Parameters

Returns

See Also

FindActionMap(String, Boolean)

Declaration

Parameters