Class InputActionMap

A mechanism for collecting a series of input actions (see InputAction) and treating them as a group.

Inheritance
Object
InputActionMap
Namespace: UnityEngine.InputSystem
Syntax
[Serializable]
public sealed class InputActionMap : ICloneable, ISerializationCallbackReceiver, IInputActionCollection, IEnumerable<InputAction>, IEnumerable, 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 null, i.e. does not assign a name to the map.

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

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

Exceptions
Type Condition
ArgumentNullException

actionNameOrId is null.
KeyNotFoundException

No action with the name or ID of actionNameOrId was found in the action map.
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 null.
Returns
Type Description
Boolean

True if the action map contains action, false otherwise.
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()
Implements
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.

FindAction(String, Boolean)

Find an action in the map by name or ID.

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

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 null if no matching action was found.
Exceptions
Type Condition
ArgumentNullException

nameOrId is null.
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 null.
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"" }
                ],
            }
        ]
    }
");
Exceptions
Type Condition
ArgumentNullException

json is null.
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.
Implements
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);
Exceptions
Type Condition
ArgumentNullException

device is null.

OnAfterDeserialize()

Called by Unity after the action map has been deserialized using Unity's serialization system.

Declaration
public void OnAfterDeserialize()
Implements

OnBeforeSerialize()

Called by Unity before the action map is serialized using Unity's serialization system.

Declaration
public void OnBeforeSerialize()
Implements

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.

Exceptions
Type Condition
ArgumentNullException

maps is null.
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.
Overrides
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

IEnumerable.GetEnumerator()

Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type Description
IEnumerator
Implements

ICloneable.Clone()

Declaration
object ICloneable.Clone()
Returns
Type Description
Object
Implements

Extension Methods

See Also