Class InputActionMap
A mechanism for collecting a series of input actions (see InputAction) and treating them as a group.
Namespace: UnityEngine.InputSystem
Syntax
public sealed class InputActionMap : ICloneable, ISerializationCallbackReceiver, IInputActionCollection2, IInputActionCollection, IEnumerable<InputAction>, IDisposable
Remarks
Each action map is a named collection of bindings and actions. Both are stored as a flat list. The bindings are available through the bindings property and the actions are available through the actions property.
The actions in a map are owned by the map. No action can appear in two maps
at the same time. To find the action map an action belongs to, use the
actionMap property. Note that actions can also stand
on their own and thus do not necessarily need to belong to a map (in which case
the actionMap property is null
).
Within a map, all actions have to have names and each action name must be unique. The action property of bindings in a map are resolved within the actions in the map. Looking up actions by name can be done through FindAction(String, Boolean).
The name of the map itself can be empty, except if the map is part of an InputActionAsset in which case it is required to have a name which also must be unique within the asset.
Action maps are most useful for grouping actions that contextually belong together. For example, one common usage is to separate the actions that can be performed in the UI or in the main menu from those that can be performed during gameplay. However, even within gameplay, multiple action maps can be employed. For example, one could have different action maps for driving and for walking plus one more map for the actions shared between the two modes.
Action maps are usually created in the action editor as part of InputActionAssets. However, they can also be created standing on their own directly in code or from JSON (see FromJson(String)).
// Create a free-standing action map.
var map = new InputActionMap();
// Add some actions and bindings to it.
map.AddAction("action1", binding: "<Keyboard>/space");
map.AddAction("action2", binding: "<Gamepad>/buttonSouth");
Actions in action maps, like actions existing by themselves outside of action maps, do not actively process input except if enabled. Actions can either be enabled individually (see Enable() and Disable()) or in bulk by enabling and disabling the entire map (see Enable() and Disable()).
Constructors
InputActionMap()
Declaration
public InputActionMap()
InputActionMap(String)
Construct an action map with the given name.
Declaration
public InputActionMap(string name)
Parameters
Type | Name | Description |
---|---|---|
String | name | Name to give to the action map. By default |
Properties
actions
List of actions contained in the map.
Declaration
public ReadOnlyArray<InputAction> actions { get; }
Property Value
Type | Description |
---|---|
ReadOnlyArray<InputAction> | Collection of actions belonging to the map. |
Remarks
Actions are owned by their map. The same action cannot appear in multiple maps.
Accessing this property. Note that values returned by the property become invalid if the setup of actions in a map is changed.
See Also
asset
If the action map is part of an asset, this refers to the asset. Otherwise it is null
.
Declaration
public InputActionAsset asset { get; }
Property Value
Type | Description |
---|---|
InputActionAsset | Asset to which the action map belongs. |
bindingMask
Binding mask to apply to all actions in the asset.
Declaration
public InputBinding? bindingMask { get; set; }
Property Value
Type | Description |
---|---|
Nullable<InputBinding> | Optional mask that determines which bindings in the action map to enable. |
Implements
Remarks
Binding masks can be applied at three different levels: for an entire asset through
bindingMask, for a specific map through this property,
and for single actions through bindingMask. By default,
none of the masks will be set (that is, 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
List of bindings contained in the map.
Declaration
public ReadOnlyArray<InputBinding> bindings { get; }
Property Value
Type | Description |
---|---|
ReadOnlyArray<InputBinding> | Collection of bindings in the map. |
Remarks
InputBindings are owned by action maps and not by individual actions.
Bindings that trigger actions refer to the action by name or id.
Accessing this property does not allocate. Note that values returned by the property become invalid if the setup of bindings in a map is changed.
See Also
controlSchemes
Control schemes defined for the action map.
Declaration
public ReadOnlyArray<InputControlScheme> controlSchemes { get; }
Property Value
Type | Description |
---|---|
ReadOnlyArray<InputControlScheme> | List of available control schemes. |
Implements
Remarks
Control schemes can only be defined at the level of InputActionAssets. For action maps that are part of assets, this property will return the control schemes from the asset. For free-standing action maps, this will return an empty list.
See Also
devices
Set of devices that bindings in the action map 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 map. |
Implements
Remarks
By default (with this property being null
), bindings will bind to any of the
controls available through devices, that is, 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 devices or to specific action maps by using this property. 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 action map containing a single action with a gamepad binding.
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.
actionMap.devices = new InputDevice[] { Gamepad.all[0] };
// Now this will print only one control.
Debug.Log(string.Join("\n", fireAction.controls));
See Also
enabled
Whether any action in the map is currently enabled.
Declaration
public bool enabled { get; }
Property Value
Type | Description |
---|---|
Boolean | True if any action in actions is currently enabled. |
See Also
id
A stable, unique identifier for the map.
Declaration
public Guid id { get; }
Property Value
Type | Description |
---|---|
Guid | Unique ID for the action map. |
Remarks
This can be used instead of the name to refer to the action map. Doing so allows referring to the map such that renaming it does not break references.
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 (as in name) or ID (as in id) of the action. Note that matching of names is case-insensitive. |
Property Value
Type | Description |
---|---|
InputAction |
Remarks
This method is equivalent to FindAction(String, Boolean) except it throws KeyNotFoundException
if no action with the given name or ID can be found.
See Also
name
Name of the action map.
Declaration
public string name { get; }
Property Value
Type | Description |
---|---|
String | Name of the action map. |
Remarks
For action maps that are part of InputActionAssets, this will always be a non-null, non-empty string that is unique within the maps in the asset. For action maps that are standing on their own, this can be null or empty.
Methods
Clone()
Produce an identical copy of the action map with its actions and bindings.
Declaration
public InputActionMap Clone()
Returns
Type | Description |
---|---|
InputActionMap | A copy of the action map. |
Remarks
If the action map is part of an InputActionAsset, the clone will not
be. It will be a free-standing action map and asset will be null
.
Note that the IDs for the map itself as well as for its actions and bindings are not copied. Instead, new IDs will be assigned. Also, callbacks installed on actions or on the map itself will not be copied over.
Contains(InputAction)
Return true
if the action map contains the given action.
Declaration
public bool Contains(InputAction action)
Parameters
Type | Name | Description |
---|---|---|
InputAction | action | An input action. Can be |
Returns
Type | Description |
---|---|
Boolean | True if the action map contains |
Implements
Disable()
Disable all the actions in the map.
Declaration
public void Disable()
Implements
Remarks
This is equivalent to calling Disable() on each action in actions, but is more efficient as the actions will get disabled in bulk.
See Also
Dispose()
Release internal state held on to by the action map.
Declaration
public void Dispose()
Remarks
Once actions in a map are enabled, the map will allocate a block of state internally that it will hold on to until disposed of. All actions in the map will share the same internal state. Also, if the map is part of an InputActionAsset all maps and actions in the same asset will share the same internal state.
Note that the internal state holds on to GC heap memory as well as memory from the unmanaged, C++ heap.
Enable()
Enable all the actions in the map.
Declaration
public void Enable()
Implements
Remarks
This is equivalent to calling Enable() on each action in actions, but is more efficient as the actions will get enabled in bulk.
See Also
FindAction(Guid)
Find an action by ID.
Declaration
public InputAction FindAction(Guid id)
Parameters
Type | Name | Description |
---|---|---|
Guid | id | ID (as in id) of the action. |
Returns
Type | Description |
---|---|
InputAction | The action with the given ID or null if no action in the map has the given ID. |
See Also
FindAction(String, Boolean)
Find an action in the map by name or ID.
Declaration
public InputAction FindAction(string actionNameOrId, bool throwIfNotFound = false)
Parameters
Type | Name | Description |
---|---|---|
String | actionNameOrId | Name (as in name) or ID (as in id) of the action. Note that matching of names is case-insensitive. |
Boolean | throwIfNotFound |
Returns
Type | Description |
---|---|
InputAction | The action with the given name or ID or |
Implements
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
FromJson(String)
Load one or more action maps from JSON.
Declaration
public static InputActionMap[] FromJson(string json)
Parameters
Type | Name | Description |
---|---|---|
String | json | JSON representation of the action maps. Can be empty. |
Returns
Type | Description |
---|---|
InputActionMap[] | The array of action maps (may be empty) read from the given JSON string. Will not be
|
Remarks
Note that the format used by this method is different than what you
get if you call JsonUtility.ToJson
on an InputActionMap instance. In other
words, the JSON format is not identical to the Unity serialized object representation
of the asset.
var maps = InputActionMap.FromJson(@"
{
""maps"" : [
{
""name"" : ""Gameplay"",
""actions"" : [
{ ""name"" : ""fire"", ""type"" : ""button"" }
],
""bindings"" : [
{ ""path"" : ""<Gamepad>/leftTrigger"", ""action"" : ""fire"" }
],
}
]
}
");
See Also
GetEnumerator()
Enumerate the actions in the map.
Declaration
public IEnumerator<InputAction> GetEnumerator()
Returns
Type | Description |
---|---|
IEnumerator<InputAction> | An enumerator going over the actions in the map. |
Remarks
This method supports to generically iterate over the actions in a map. However, it will usually lead to GC allocation. Iterating directly over actions avoids allocating GC memory.
IsUsableWithDevice(InputDevice)
Check whether there are any bindings in the action map that can bind to controls on the given device.
Declaration
public bool IsUsableWithDevice(InputDevice device)
Parameters
Type | Name | Description |
---|---|---|
InputDevice | device | An input device. |
Returns
Type | Description |
---|---|
Boolean | True if any of the bindings in the map can resolve to controls on the device, false otherwise. |
Remarks
The logic is entirely based on the contents of bindings and, more specifically,
effectivePath of each binding. Each path is checked using Matches(String, InputControl). If any path matches, the method returns true
.
Properties such as devices and bindingMask are ignored.
// Create action map with two actions and bindings.
var actionMap = new InputActionMap();
actionMap.AddAction("action1", binding: "<Gamepad>/buttonSouth");
actionMap.AddAction("action2", binding: "<XRController{LeftHand}>/{PrimaryAction}");
//
var gamepad = InputSystem.AddDevice<Gamepad>();
var xrController = InputSystem.AddDevice<XRController>();
// Returns true:
actionMap.IsUsableWith(gamepad);
// Returns false: (the XRController does not have the LeftHand usage assigned to it)
actionMap.IsUsableWith(xrController);
OnAfterDeserialize()
Called by Unity after the action map has been deserialized using Unity's serialization system.
Declaration
public void OnAfterDeserialize()
OnBeforeSerialize()
Called by Unity before the action map is serialized using Unity's serialization system.
Declaration
public void OnBeforeSerialize()
ToJson()
Convert the action map to JSON format.
Declaration
public string ToJson()
Returns
Type | Description |
---|---|
String | A JSON representation of the action map. |
Remarks
The result of this method can be loaded with FromJson(String).
Note that the format used by this method is different than what you
get if you call JsonUtility.ToJson
on an InputActionMap instance. In other
words, the JSON format is not identical to the Unity serialized object representation
of the asset.
ToJson(IEnumerable<InputActionMap>)
Convert a set of action maps to JSON format.
Declaration
public static string ToJson(IEnumerable<InputActionMap> maps)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<InputActionMap> | maps | List of action maps to serialize. |
Returns
Type | Description |
---|---|
String | JSON representation of the given action maps. |
Remarks
The result of this method can be loaded with FromJson(String).
Note that the format used by this method is different than what you
get if you call JsonUtility.ToJson
on an InputActionMap instance. In other
words, the JSON format is not identical to the Unity serialized object representation
of the asset.
See Also
ToString()
Return a string representation of the action map useful for debugging.
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
String | A string representation of the action map. |
Remarks
For unnamed action maps, this will always be "<Unnamed Action Map>"
.
Events
actionTriggered
Add or remove a callback that is triggered when an action in the map changes its InputActionPhase.
Declaration
public event Action<InputAction.CallbackContext> actionTriggered
Event Type
Type | Description |
---|---|
Action<InputAction.CallbackContext> |
See Also
Explicit Interface Implementations
IInputActionCollection2.bindings
Declaration
IEnumerable<InputBinding> IInputActionCollection2.bindings { get; }
Returns
Type | Description |
---|---|
IEnumerable<InputBinding> |