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 class InputAction : ICloneable, IDisposable
Remarks

Unlike controls, actions signal value changes rather than the values themselves. They sit on top of controls (and each single action may reference several controls collectively) and monitor the system for change.

Unlike InputControls, InputActions are not passive. They will actively perform processing each frame they are active whereas InputControls just sit there as long as no one is asking them directly for a value.

Processors on controls are NOT taken into account by actions. A state is considered changed if its underlying memory changes not if the final processed value changes.

Actions are agnostic to update types. They trigger in whatever update detects a change in value.

Actions are not supported in edit mode.

Constructors

InputAction(String)

Declaration
public InputAction(string name = null)
Parameters
Type Name Description
System.String name

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

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

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.

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.

continuous

If true, the action will continuously trigger performed on every input update while the action is in the Performed phase.

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

This is off by default.

An action must be disabled when setting this property.

Continuous actions are useful when otherwise it would be necessary to manually set up an action response to run a piece of logic every update. Instead, the fact that input already updates in sync with the player loop can be leveraged to have actions triggered continuously.

A typical use case is "move" and "look" functionality tied to gamepad sticks. Even if the gamepad stick is not moved in a particular update, the current value of the stick should be applied. A simple way to achieve this is by toggling on "continuous" mode through this property.

Note that continuous mode does not affect phases other than Performed. This means that, for example, Started (and the associated started) will not be triggered repeatedly even if continuous mode is toggled on for an action.

// Set up an action that will be performed continuously while the right stick on the gamepad
// is moved out of its deadzone.
var action = new InputAction("Look", binding: "<Gamepad>/rightStick);
action.continuous = true;
action.performed = ctx => Look(ctx.ReadValue<Vector2>());
action.Enable();
Exceptions
Type Condition
System.InvalidOperationException

The action is enabled. Continuous mode can only be changed while an action is disabled.
See Also

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 or not.

Declaration
public bool enabled { get; }
Property Value
Type Description
System.Boolean
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 ...

expectedControlLayout

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

Declaration
public string expectedControlLayout { 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.

initialStateCheck

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

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
Remarks

Can be null for anonymous actions created in code.

If the action is part of a set, 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 "setName/actionName" combination.

passThrough

If enabled, the action will not gate any control changes but will instead pass through any change on any of the bound controls as is.

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

This behavior is useful for actions that are not meant to model any kind of interaction but should rather just listen for input of any kind. By default, an action will be driven based on the amount of actuation on the bound controls. Any control with the highest amount of actuation gets to drive an action. This can be undesirable. For example, an action may want to listen for any kind of activity on any of the bound controls. In this case, set this property to true.

This behavior is disabled by default.

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

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

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