Enum InputActionType
Determines the behavior with which an Input
Namespace: UnityEngine .InputSystem
Assembly: Unity.InputSystem.dll
Syntax
public enum InputActionType
Remarks
While all actions essentially function the same way, there are differences in how an action will react to changes in values on the controls it is bound to.
The most straightforward type of behavior is Pass
// An action that triggers every time any button on the gamepad is
// pressed or released.
var action = new InputAction(
type: InputActionType.PassThrough,
binding: "<Gamepad>/<Button>");
action.performed +=
ctx =>
{
var button = (ButtonControl)ctx.control;
if (button.wasPressedThisFrame)
Debug.Log($"Button {ctx.control} was pressed");
else if (button.wasReleasedThisFrame)
Debug.Log($"Button {ctx.control} was released");
// NOTE: We may get calls here in which neither the if nor the else
// clause are true here. A button like the gamepad left and right
// triggers, for example, do not just have a binary on/off state
// but rather a [0..1] value range.
};
action.Enable();
Note that pass-through actions do not perform any kind of disambiguation of input which makes them great for just forwarding input from any connected controls but makes them a poor choice when only one input should be generated from however many connected controls there are. For more details, see here.
The other two behavior types are Button and Value.
A Value action starts (started) as soon as its input moves away from its default value. After that it immediately performs (performed) and every time the input changes value it performs again except if the input moves back to the default value -- in which case the action cancels (canceled).
Also, unlike both Button and Pass
Button and Pass
// An action that starts when the left stick on the gamepad is actuated
// and stops when the stick is released.
var action = new InputAction(
type: InputActionType.Value,
binding: "<Gamepad>/leftStick");
action.started +=
ctx =>
{
Debug.Log("--- Stick Starts ---");
};
action.performed +=
ctx =>
{
Debug.Log("Stick Value: " + ctx.ReadValue<Vector2D>();
};
action.canceled +=
ctx =>
{
Debug.Log("# Stick Released");
};
action.Enable();
A Button action essentially operates like a Value action except that it does not perform an initial state check.
One final noteworthy difference of both Button and Value compared
to Pass
Button and Value, on the other hand, will treat input differently
if it is coming from several sources at the same time. Note that this can only happen when there
are multiple controls bound to a single actions -- either by a single binding resolving to
more than one control (e.g. "*/{PrimaryAction}"
) or by multiple bindings all targeting
the same action and being active at the same time. If only a single control is bound to an
action, then the disambiguation code is automatically bypassed.
Disambiguation works the following way: when an action has not yet been started, it will react
to the first input that has a non-default value. Once it receives such an input, it will start
tracking the source of that input. While the action is in-progress, if it receives input from
a source other than the control it is currently tracking, it will check whether the input has
a greater magnitude (see Evaluate
Note that this process does also works in reverse. When the control currently driving the action lowers its value below that of another control that is also actuated and bound to the action, the action will switch to that control.
Put simply, a Button or Value action bound to multiple controls will always track the control with the strongest input.
Fields
Name | Description |
---|---|
Button | An action that acts as a trigger. A button action has a defined trigger point that corresponds to Performed. After being performed, the action goes back to waiting state to await the next triggering. Note that a button action may still use Started and does not necessarily
trigger immediately on input. For example, if Hold Irrespective of which type an action is set to, it is possible to find out whether it was or is considered
pressed and/or released using Is
|
PassThrough | An action that has no specific type of behavior and instead acts as a simple pass-through for any value change on any bound control. In effect, this turns an action from a single value producer into a mere input "sink". This is in some ways similar to Value. However, there are two key differences. For one, the action will not perform any disambiguation when bound to multiple controls concurrently. This means that if, for example, the action is bound to both the left and the right stick on a Gamepad, and the left stick goes to (0.5,0.5) and the right stick then goes to (0.25,0.25), the action will perform twice yielding a value of (0.5,0.5) first and a value of (0.25, 0.25) next. This is different from Value where upon actuation to (0.5,0.5), the left stick would get to drive the action and the actuation of the right stick would be ignored as it does not exceed the magnitude of the actuation on the left stick. The second key difference is that only Performed is used and will get triggered on every value change regardless of what the value is. This is different from Value where the action will trigger Started when moving away from its default value and will trigger Canceled when going back to the default value. Note that a pass-through action my still get cancelled and thus see canceled getting called.
This happens when a factor other than input on a device causes an action in progress to be cancelled. An example
of this is when an action is disabled (see Disable()) or when focus is lost (see background Also note that for a pass-through action, calling Read |
Value | An action that reads a single value from its connected sources. If multiple bindings actuate at the same time, performs disambiguation (see ../manual/ActionBindings.html#conflicting-inputs) to detect the highest value contributor at any one time. A value action starts (Started) and then performs (Performed)
as soon as a bound control changes to a non-default value. For example, if an action is bound to left After being started, the action will perform on every value change that is not the default value. In the example here, if the stick goes to (0.75,0.75) and then to (1,1), the action will perform twice. Finally, if the control value changes back to the default value, the action is canceled (Canceled). Meaning that if the stick moves back to (0,0), canceled will be triggered. |