Class InputActionMap

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

Inheritance

object

InputActionMap

Implements

ICloneable

ISerializationCallbackReceiver

IInputActionCollection2

IInputActionCollection

IEnumerable<InputAction>

IEnumerable

IDisposable

Namespace: UnityEngine.InputSystem

Assembly: Unity.InputSystem.dll

Syntax

[Serializable]
public sealed class InputActionMap : ICloneable, ISerializationCallbackReceiver, IInputActionCollection2, 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, bool).

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

Construct an action map with default values.

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

this[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, bool) 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.

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.

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
InputBinding?	Optional mask that determines which bindings in the action map to enable.

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.

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.

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.

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.

devices

Set of devices that bindings in the action map can bind to.

Declaration

public ReadOnlyArray<InputDevice>? devices { get; set; }

Property Value

Type	Description
ReadOnlyArray<InputDevice>?	Optional set of devices to use by bindings in the map.

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

enabled

Whether any action in the map is currently enabled.

Declaration

public bool enabled { get; }

Property Value

Type	Description
bool	True if any action in actions is currently enabled.

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.

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
bool	True if the action map contains `action`, false otherwise.

Disable()

Disable all the actions in the map.

Declaration

public void Disable()

Remarks

This is equivalent to calling Disable() on each action in actions, but is more efficient as the actions will get disabled in bulk.

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

Remarks

This is equivalent to calling Enable() on each action in actions, but is more efficient as the actions will get enabled in bulk.

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.

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.
bool	throwIfNotFound	If set to true will cause an exception to be thrown when the action was not found.

Returns

Type	Description
InputAction	The action with the given name or ID or `null` if no matching action was found.

Exceptions

Type	Condition
ArgumentNullException	`actionNameOrId` is `null`.

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
int	Index into bindings of `action` of the binding that matches `mask`. If no binding matches, will return -1.

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}");</code></pre></example>

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

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

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

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

Exceptions

Type	Condition
ArgumentNullException	`maps` is `null`.

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

object.ToString()

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

Declaration

public event Action<InputAction.CallbackContext> actionTriggered

Event Type

Type	Description
Action<InputAction.CallbackContext>

Implements

ICloneable

ISerializationCallbackReceiver

IInputActionCollection2

IInputActionCollection

IEnumerable<T>

IEnumerable

IDisposable

Extension Methods

InputActionRebindingExtensions.LoadBindingOverridesFromJson(IInputActionCollection2, string, bool)

InputActionRebindingExtensions.RemoveAllBindingOverrides(IInputActionCollection2)

InputActionRebindingExtensions.SaveBindingOverridesAsJson(IInputActionCollection2)

InputActionRebindingExtensions.ApplyBindingOverride(InputActionMap, int, InputBinding)

InputActionRebindingExtensions.ApplyBindingOverride(InputActionMap, InputBinding)

InputActionRebindingExtensions.ApplyBindingOverrides(InputActionMap, IEnumerable<InputBinding>)

InputActionRebindingExtensions.ApplyBindingOverridesOnMatchingControls(InputActionMap, InputControl)

InputActionRebindingExtensions.ApplyParameterOverride(InputActionMap, string, PrimitiveValue, InputBinding)

InputActionRebindingExtensions.ApplyParameterOverride<TObject, TValue>(InputActionMap, Expression<Func<TObject, TValue>>, TValue, InputBinding)

InputActionRebindingExtensions.GetBindingIndex(InputActionMap, InputBinding)

InputActionRebindingExtensions.RemoveBindingOverrides(InputActionMap, IEnumerable<InputBinding>)

InputActionSetupExtensions.AddAction(InputActionMap, string, InputActionType, string, string, string, string, string)

InputActionSetupExtensions.AddBinding(InputActionMap, string, Guid, string, string)

InputActionSetupExtensions.AddBinding(InputActionMap, string, string, string, string, string)

InputActionSetupExtensions.AddBinding(InputActionMap, string, InputAction, string, string)

InputActionSetupExtensions.AddBinding(InputActionMap, InputBinding)

InputActionSetupExtensions.ChangeBinding(InputActionMap, int)

Class InputActionMap

Inheritance

Implements

Namespace: UnityEngine.InputSystem

Assembly: Unity.InputSystem.dll

Syntax

Remarks

Constructors

InputActionMap()

Declaration

See Also

InputActionMap(string)

Declaration

Parameters

See Also

Properties

this[string]

Declaration

Parameters

Property Value

Remarks

Exceptions

See Also

actions

Declaration

Property Value

Remarks

See Also

asset

Declaration

Property Value

See Also

bindingMask

Declaration

Property Value

Remarks

See Also

bindings

Declaration

Property Value

Remarks

See Also

controlSchemes

Declaration

Property Value

Remarks

See Also

devices

Declaration

Property Value

Remarks

See Also

enabled

Declaration

Property Value

See Also

id

Declaration

Property Value

Remarks

See Also

name

Declaration

Property Value

Remarks

See Also

Methods

Clone()

Declaration

Returns

Remarks

See Also

Contains(InputAction)

Declaration

Parameters

Returns

See Also

Disable()

Declaration

Remarks