docs.unity3d.com
    Show / Hide Table of Contents

    Enum InputActionPhase

    Trigger phase of an InputAction.

    Namespace: UnityEngine.InputSystem
    Syntax
    public enum InputActionPhase : int
    Remarks

    Actions can be triggered in steps. For example, a SlowTapInteraction will put an action into Started phase when a button the action is bound to is pressed. At that point, however, the action still has to wait for the expiration of a timer in order to make it a 'slow tap'. If the button is release before the timer expires, the action will be Canceled whereas if the button is held long enough, the action will be Performed.

    Fields

    Name Description Value
    Disabled

    The action is not enabled.

    0
    Waiting

    The action is enabled and waiting for input on its associated controls.

    This is the phase that an action goes back to once it has been Performed or Canceled.

    1
    Started

    An associated control has been actuated such that it may lead to the action being triggered. Will lead to started getting called.

    This phase will only be invoked if there are interactions on the respective control binding. Without any interactions, an action will go straight from Waiting into Performed and back into Waiting whenever an associated control changes value.

    An example of an interaction that uses the Started phase is SlowTapInteraction. When the button it is bound to is pressed, the associated action goes into the Started phase. At this point, the interaction does not yet know whether the button press will result in just a tap or will indeed result in slow tap. If the button is released before the time it takes to recognize a slow tap, then the action will go to Canceled and then back to Waiting. If, however, the button is held long enough for it to qualify as a slow tap, the action will progress to Performed and then go back to Waiting.

    Started can be useful for UI feedback. For example, in a game where the weapon can be charged, UI feedback can be initiated when the action is Started.

    fireAction.started +=
        ctx =>
        {
            if (ctx.interaction is SlowTapInteraction)
            {
                weaponCharging = true;
                weaponChargeStartTime = ctx.time;
            }
        }
    fireAction.canceled +=
        ctx =>
        {
            weaponCharging = false;
        }
    fireAction.performed +=
        ctx =>
        {
            Fire();
            weaponCharging = false;
        }

    By default, an action is started as soon as a control moves away from its default value. This is the case for both Button actions (which, however, does not yet have to mean that the button press threshold has been reached; see defaultButtonPressPoint) and Value actions. PassThrough does not use the Started phase and instead goes straight to Performed.

    For Value actions, Started will immediately be followed by Performed.

    Note that interactions (see IInputInteraction) can alter how an action does or does not progress through the phases.

    2
    Performed

    The action has been performed. Leads to performed getting called.

    By default, a Button action performs when a control crosses the button press threshold (see defaultButtonPressPoint), a Value action performs on any value change that isn't the default value, and a PassThrough action performs on any value change including going back to the default value.

    Note that interactions (see IInputInteraction) can alter how an action does or does not progress through the phases.

    For a given action, finding out whether it was performed in the current frame can be done with WasPerformedThisFrame().

    action.WasPerformedThisFrame();
    3
    Canceled

    The action has stopped. Leads to canceled getting called.

    By default, a Button action cancels when a control falls back below the button press threshold (see defaultButtonPressPoint) and a Value action cancels when a control moves back to its default value. A PassThrough action does not generally cancel based on input on its controls.

    An action will also get canceled when it is disabled while in progress (see Disable()). Also, when an InputDevice that is

    Note that interactions (see IInputInteraction) can alter how an action does or does not progress through the phases.

    4

    Extension Methods

    InputExtensions.IsInProgress()
    Back to top
    Terms of use
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023