Class InputActionAsset
An asset that contains action maps and control schemes.
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 |
ArgumentNullException |
|
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 |
Returns
Type | Description |
---|---|
InputAction | The action with the corresponding name or |
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 |
|
ArgumentException | Thrown if |
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 |
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 |
Returns
Type | Description |
---|---|
InputActionMap | The InputActionMap with a name or ID matching |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException | If |
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 |
Returns
Type | Description |
---|---|
Int32 | Index into bindings of |
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 |
|
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 |
|
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 |
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 |
|
See Also
GetEnumerator()
Enumerate all actions in the asset.
Declaration
public IEnumerator<InputAction> GetEnumerator()
Returns
Type | Description |
---|---|
IEnumerator<InputAction> | Enumerate over all 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 |
|
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 |
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 |
|
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()
Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type | Description |
---|---|
IEnumerator |