A game about forced loneliness, made by TACStudios
tacstudios.tngl.sh
1using UnityEngine.InputSystem.Interactions;
2
3////REVIEW: this goes beyond just actions; is there a better name? just InputPhase?
4
5////REVIEW: what about opening up phases completely to interactions and allow them to come up with whatever custom phases?
6
7namespace UnityEngine.InputSystem
8{
9 /// <summary>
10 /// Trigger phase of an <see cref="InputAction"/>.
11 /// </summary>
12 /// <remarks>
13 /// Actions can be triggered in steps. For example, a <see cref="SlowTapInteraction">
14 /// 'slow tap'</see> will put an action into <see cref="Started"/> phase when a button
15 /// the action is bound to is pressed. At that point, however, the action still
16 /// has to wait for the expiration of a timer in order to make it a 'slow tap'. If
17 /// the button is release before the timer expires, the action will be <see cref="Canceled"/>
18 /// whereas if the button is held long enough, the action will be <see cref="Performed"/>.
19 /// </remarks>
20 /// <seealso cref="InputAction.phase"/>
21 /// <seealso cref="InputAction.CallbackContext.phase"/>
22 /// <seealso cref="InputAction.started"/>
23 /// <seealso cref="InputAction.performed"/>
24 /// <seealso cref="InputAction.canceled"/>
25 public enum InputActionPhase
26 {
27 /// <summary>
28 /// The action is not enabled.
29 /// </summary>
30 Disabled,
31
32 /// <summary>
33 /// The action is enabled and waiting for input on its associated controls.
34 ///
35 /// This is the phase that an action goes back to once it has been <see cref="Performed"/>
36 /// or <see cref="Canceled"/>.
37 /// </summary>
38 Waiting,
39
40 /// <summary>
41 /// An associated control has been actuated such that it may lead to the action
42 /// being triggered. Will lead to <see cref="InputAction.started"/> getting called.
43 ///
44 /// This phase will only be invoked if there are interactions on the respective control
45 /// binding. Without any interactions, an action will go straight from <see cref="Waiting"/>
46 /// into <see cref="Performed"/> and back into <see cref="Waiting"/> whenever an associated
47 /// control changes value.
48 ///
49 /// An example of an interaction that uses the <see cref="Started"/> phase is <see cref="SlowTapInteraction"/>.
50 /// When the button it is bound to is pressed, the associated action goes into the <see cref="Started"/>
51 /// phase. At this point, the interaction does not yet know whether the button press will result in just
52 /// a tap or will indeed result in slow tap. If the button is released before the time it takes to
53 /// recognize a slow tap, then the action will go to <see cref="Canceled"/> and then back to <see cref="Waiting"/>.
54 /// If, however, the button is held long enough for it to qualify as a slow tap, the action will progress
55 /// to <see cref="Performed"/> and then go back to <see cref="Waiting"/>.
56 ///
57 /// <see cref="Started"/> can be useful for UI feedback. For example, in a game where the weapon can be charged,
58 /// UI feedback can be initiated when the action is <see cref="Started"/>.
59 ///
60 /// <example>
61 /// <code>
62 /// fireAction.started +=
63 /// ctx =>
64 /// {
65 /// if (ctx.interaction is SlowTapInteraction)
66 /// {
67 /// weaponCharging = true;
68 /// weaponChargeStartTime = ctx.time;
69 /// }
70 /// }
71 /// fireAction.canceled +=
72 /// ctx =>
73 /// {
74 /// weaponCharging = false;
75 /// }
76 /// fireAction.performed +=
77 /// ctx =>
78 /// {
79 /// Fire();
80 /// weaponCharging = false;
81 /// }
82 /// </code>
83 /// </example>
84 ///
85 /// By default, an action is started as soon as a control moves away from its default value. This is
86 /// the case for both <see cref="InputActionType.Button"/> actions (which, however, does not yet have to mean
87 /// that the button press threshold has been reached; see <see cref="InputSettings.defaultButtonPressPoint"/>)
88 /// and <see cref="InputActionType.Value"/> actions. <see cref="InputActionType.PassThrough"/> does not use
89 /// the <c>Started</c> phase and instead goes straight to <see cref="Performed"/>.
90 ///
91 /// For <see cref="InputActionType.Value"/> actions, <c>Started</c> will immediately be followed by <see cref="Performed"/>.
92 ///
93 /// Note that interactions (see <see cref="IInputInteraction"/>) can alter how an action does or does not progress through
94 /// the phases.
95 /// </summary>
96 Started,
97
98 /// <summary>
99 /// The action has been performed. Leads to <see cref="InputAction.performed"/> getting called.
100 ///
101 /// By default, a <see cref="InputActionType.Button"/> action performs when a control crosses the button
102 /// press threshold (see <see cref="InputSettings.defaultButtonPressPoint"/>), a <see cref="InputActionType.Value"/>
103 /// action performs on any value change that isn't the default value, and a <see cref="InputActionType.PassThrough"/>
104 /// action performs on any value change including going back to the default value.
105 ///
106 /// Note that interactions (see <see cref="IInputInteraction"/>) can alter how an action does or does not progress through
107 /// the phases.
108 ///
109 /// For a given action, finding out whether it was performed in the current frame can be done with <see cref="InputAction.WasPerformedThisFrame"/>.
110 ///
111 /// <example>
112 /// <code>
113 /// action.WasPerformedThisFrame();
114 /// </code>
115 /// </example>
116 /// </summary>
117 Performed,
118
119 /// <summary>
120 /// The action has stopped. Leads to <see cref="InputAction.canceled"/> getting called.
121 ///
122 /// By default, a <see cref="InputActionType.Button"/> action cancels when a control falls back below the button
123 /// press threshold (see <see cref="InputSettings.defaultButtonPressPoint"/>) and a <see cref="InputActionType.Value"/>
124 /// action cancels when a control moves back to its default value. A <see cref="InputActionType.PassThrough"/> action
125 /// does not generally cancel based on input on its controls.
126 ///
127 /// An action will also get canceled when it is disabled while in progress (see <see cref="InputAction.Disable"/>).
128 /// Also, when an <see cref="InputDevice"/> that is
129 ///
130 /// Note that interactions (see <see cref="IInputInteraction"/>) can alter how an action does or does not progress through
131 /// the phases.
132 /// </summary>
133 Canceled
134 }
135}