Class InputAction

A named input signal that can flexibly decide which input data to tap.

Inheritance
System.Object
InputAction
Namespace: UnityEngine.InputSystem
Syntax
[Serializable]
public sealed class InputAction : ICloneable, IDisposable
Remarks

An input action is an abstraction over the source of input(s) it receives. They are most useful for representing input as "logical" concepts (e.g. "jump") rather than as "physical" inputs (e.g. "space bar on keyboard pressed").

In its most basic form, an action is simply an object along with a collection of bindings that trigger the action.

// A simple action can be created directly using `new`. If desired, a binding
// can be specified directly as part of construction.
var action = new InputAction(binding: "<Gamepad>/buttonSouth");

// Additional bindings can be added using `AddBinding`.
action.AddBinding("<Mouse>/leftButton");

Bindings use control path expressions to reference controls. See InputBinding for more details. There may be arbitrary many bindings targeting a single action. The list of bindings targeting an action can be obtained through bindings.

By itself an action does not do anything until it is enabled:

action.Enable();

Once enabled, the action will actively monitor all controls on devices present in the system (see devices) that match any of the binding paths associated with the action. If you want to restrict the set of bindings used at runtime or restrict the set of devices which controls are chosen from, you can do so using bindingMask or, if the action is part of an InputActionMap, by setting the devices property of the action map. The controls that an action uses can be queried using the controls property.

When input is received on controls bound to an action, the action will trigger callbacks in response. These callbacks are started, performed, and canceled. The callbacks are triggered as part of input system updates (see Update()), i.e. they happen before the respective or methods get executed (depending on which updateMode the system is set to).

In what order and how those callbacks get triggered depends on both the type of the action as well as on the interactions (see IInputInteraction) present on the bindings of the action. The default behavior is that when a control is actuated (i.e. moving away from its resting position), started is called and then performed. Subsequently, whenever the a control further changes value to anything other than its default value, performed will be called again. Finally, when the control moves back to its default value (i.e. resting position), canceled is called.

To hook into the callbacks, there are several options available to you. The most obvious one is to hook directly into started, performed, and/or canceled. In these callbacks, you will receive a InputAction.CallbackContext with information about how the action got triggered. For example, you can use ReadValue<TValue>() to read the value from the binding that triggered or use interaction to find the interaction that is in progress.

action.started += context => Debug.Log($"{context.action} started");
action.performed += context => Debug.Log($"{context.action} performed");
action.canceled += context => Debug.Log($"{context.action} canceled");

Alternatively, you can use the actionTriggered callback for actions that are part of an action map or the global onActionChange callback to globally listen for action activity. To simply record action activity instead of responding to it directly, you can use InputActionTrace.

If you prefer to poll an action directly as part of your or logic, you can do so using the triggered and ReadValue<TValue>() methods.

protected void Update()
{
    // For a button type action.
    if (action.triggered)
        /* ... */;

    // For a value type action.
    // (Vector2 is just an example; pick the value type that is the right
    // one according to the bindings you have)
    var v = action.ReadValue<Vector2>();
}

Note that actions are not generally frame-based. What this means is that an action will observe any value change on its connected controls, even if the control changes value multiple times in the same frame. In practice, this means that, for example, no button press will get missed.

Please note that actions are a player-only feature. They are not supported in edit mode.

Constructors

InputAction()

Declaration
public InputAction()

InputAction(String, InputActionType, String, String, String, String)

Declaration
public InputAction(string name = null, InputActionType type = default(InputActionType), string binding = null, string interactions = null, string processors = null, string expectedControlType = null)
Parameters
Type Name Description
System.String name
InputActionType type
System.String binding
System.String interactions
System.String processors
System.String expectedControlType

Properties

actionMap

The map the action belongs to.

Declaration
public InputActionMap actionMap { get; }
Property Value
Type Description
InputActionMap
Remarks

If the action is a loose action created in code, this will be null.

activeControl

The currently active control that is driving the action. Null while the action is in waiting (Waiting) or canceled (Canceled) state. Otherwise the control that last had activity on it which wasn't ignored.

Declaration
public InputControl activeControl { get; }
Property Value
Type Description
InputControl
Remarks

Note that the control's value does not necessarily correspond to the value of the action (ReadValue<TValue>()) as the control may be part of a composite.

See Also

bindingMask

Declaration
public InputBinding? bindingMask { get; set; }
Property Value
Type Description
System.Nullable<InputBinding>

bindings

The list of bindings associated with the action.

Declaration
public ReadOnlyArray<InputBinding> bindings { get; }
Property Value
Type Description
ReadOnlyArray<InputBinding>
Remarks

This will include only bindings that directly trigger the action. If the action is part of a InputActionMap that triggers the action through a combination of bindings, for example, only the bindings that ultimately trigger the action are included in the list.

May allocate memory on first hit.

controls

The set of controls to which the action's bindings resolve.

Declaration
public ReadOnlyArray<InputControl> controls { get; }
Property Value
Type Description
ReadOnlyArray<InputControl>
Remarks

May allocate memory each time the control setup changes on the action.

enabled

Whether the action is currently enabled, i.e. responds to input, or not.

Declaration
public bool enabled { get; }
Property Value
Type Description
System.Boolean

True if the action is currently enabled.
Remarks

An action is enabled by either calling Enable() on it directly or by calling Enable() on the InputActionMap containing the action. When enabled, an action will listen for changes on the controls it is bound to and trigger callbacks such as started, performed, and canceled in response.

See Also

expectedControlType

Name of control layout expected for controls bound to this action.

Declaration
public string expectedControlType { get; set; }
Property Value
Type Description
System.String
Remarks

This is optional and is null by default.

Constraining an action to a particular control layout allows determine the value type and expected input behavior of an action without being reliant on any particular binding.

id

A stable, unique identifier for the action.

Declaration
public Guid id { get; }
Property Value
Type Description
System.Guid
Remarks

This can be used instead of the name to refer to the action. Doing so allows referring to the action such that renaming the action does not break references.

interactions

Declaration
public string interactions { get; }
Property Value
Type Description
System.String

name

Name of the action.

Declaration
public string name { get; }
Property Value
Type Description
System.String

Plain-text name of the action.
Remarks

Can be null for anonymous actions created in code.

If the action is part of an InputActionMap, it will have a name and the name will be unique in the set. The name is just the name of the action alone, not a "mapName/actionName" combination.

The name should not contain slashes or dots but can contain spaces and punctuation.

phase

The current phase of the action.

Declaration
public InputActionPhase phase { get; }
Property Value
Type Description
InputActionPhase
Remarks

When listening for control input and when responding to control value changes, actions will go through several possible phases. TODO

processors

Declaration
public string processors { get; }
Property Value
Type Description
System.String

triggered

Whether the action was triggered (i.e. had performed called) this frame.

Declaration
public bool triggered { get; }
Property Value
Type Description
System.Boolean
Remarks

Unlike ReadValue<TValue>(), which will reset when the action goes back to waiting state, this property will stay true for the duration of the current frame (i.e. until the next Update() runs) as long as the action was triggered at least once.

if (myControls.gameplay.fire.triggered)
    Fire();
See Also

type

Behavior type of the action.

Declaration
public InputActionType type { get; }
Property Value
Type Description
InputActionType

General behavior type of the action.
Remarks

Determines how the action gets triggered in response to control value changes.

Methods

Clone()

Declaration
public InputAction Clone()
Returns
Type Description
InputAction

Disable()

Declaration
public void Disable()

Dispose()

Declaration
public void Dispose()

Enable()

Declaration
public void Enable()

ReadValue<TValue>()

Read the current value of the action. This is the last value received on started, or performed. If the action is in canceled or waiting phase, returns default(TValue).

Declaration
public TValue ReadValue<TValue>()
    where TValue : struct
Returns
Type Description
TValue

The current value of the action or default(TValue) if the action is not currently in-progress.
Type Parameters
Name Description
TValue

Value type to read. Must match the value type of the binding/control that triggered.
Remarks

This method can be used as an alternative to hooking into started, performed, and/or canceled and reading out the value using ReadValue<TValue>() there. Instead, this API acts more like a polling API that can be called, for example, as part of .

// Let's say you have a MyControls.inputactions file with "Generate C# Class" enabled
// and it has an action map called "gameplay" with a "move" action of type Vector2.
public class MyBehavior : MonoBehaviour
{
    public MyControls controls;
    public float moveSpeed = 4;

    protected void Awake()
    {
        controls = new MyControls();
    }

    protected void OnEnable()
    {
        controls.gameplay.Enable();
    }

    protected void OnDisable()
    {
        controls.gameplay.Disable();
    }

    protected void Update()
    {
        var moveVector = controls.gameplay.move.ReadValue<Vector2>() * (moveSpeed * Time.deltaTime);
        //...
    }
}

If the action has button-like behavior, then triggered is usually a better alternative to reading out a float and checking if it is above the button press point.

Exceptions
Type Condition
System.InvalidOperationException

The given TValue type does not match the value type of the control or composite currently driving the action.
See Also

ReadValueAsObject()

Same as ReadValue<TValue>() but read the value without having to know the value type of the action.

Declaration
public object ReadValueAsObject()
Returns
Type Description
System.Object

The current value of the action or null if the action is not currently in Started or Performed phase.
Remarks

This method allocates GC memory and is thus not a good choice for getting called as part of gameplay logic.

See Also

ToString()

Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

Events

canceled

Event that is triggered when the action has been started but then canceled before being fully performed.

Declaration
public event Action<InputAction.CallbackContext> canceled
Event Type
Type Description
System.Action<InputAction.CallbackContext>

performed

Event that is triggered when the action has been fully performed.

Declaration
public event Action<InputAction.CallbackContext> performed
Event Type
Type Description
System.Action<InputAction.CallbackContext>

started

Event that is triggered when the action has been started.

Declaration
public event Action<InputAction.CallbackContext> started
Event Type
Type Description
System.Action<InputAction.CallbackContext>

Extension Methods

See Also