diff --git a/Packages/com.unity.inputsystem/InputSystem/Actions/InputInteractionContext.cs b/Packages/com.unity.inputsystem/InputSystem/Actions/InputInteractionContext.cs index 60db9dd869..16df3c68c0 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Actions/InputInteractionContext.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Actions/InputInteractionContext.cs @@ -123,8 +123,8 @@ public bool ControlIsActuated(float threshold = 0) /// Mark the interaction has having begun. /// /// - /// Note that this affects the current interaction only. There may be multiple interactions on a binding - /// and arbitrary many interactions may concurrently be in started state. However, only one interaction + /// This affects the current interaction only. There might be multiple interactions on a binding + /// and arbitrary many interactions might concurrently be in started state. However, only one interaction /// (usually the one that starts first) is allowed to drive the action's state as a whole. If an interaction /// that is currently driving an action is canceled, however, the next interaction in the list that has /// been started will take over and continue driving the action. @@ -161,6 +161,18 @@ public void Started() m_State.ChangePhaseOfInteraction(InputActionPhase.Started, ref m_TriggerState); } + /// + /// Marks the interaction as being performed and then transitions back to + /// to wait for input. This behavior is desirable for interaction events that are instant and reflect + /// a transitional interaction pattern such as or . + /// + /// + /// Note that this affects the current interaction only. There might be multiple interactions on a binding + /// and arbitrary many interactions might concurrently be in started state. However, only one interaction + /// (usually the one that starts first) is allowed to drive the action's state as a whole. If an interaction + /// that is currently driving an action is canceled, however, the next interaction in the list that has + /// been started will take over and continue driving the action. + /// public void Performed() { if (m_TriggerState.phase == InputActionPhase.Waiting) @@ -168,6 +180,12 @@ public void Performed() m_State.ChangePhaseOfInteraction(InputActionPhase.Performed, ref m_TriggerState); } + /// + /// Marks the interaction as being performed and then transitions into I + /// to wait for an initial trigger condition to be true before being performed again. This behavior + /// may be desirable for interaction events that reflect transitional interaction patterns but should + /// be considered as started until a cancellation condition is true, such as releasing a button. + /// public void PerformedAndStayStarted() { if (m_TriggerState.phase == InputActionPhase.Waiting) @@ -176,6 +194,12 @@ public void PerformedAndStayStarted() phaseAfterPerformed: InputActionPhase.Started); } + /// + /// Marks the interaction as being performed and then stays in that state waiting for an input to + /// cancel the interactions active state. This behavior is desirable for interaction events that + /// are active for a duration until a cancellation condition is true, such as or where releasing + /// the associated button cancels the interaction.. + /// public void PerformedAndStayPerformed() { if (m_TriggerState.phase == InputActionPhase.Waiting) @@ -184,6 +208,16 @@ public void PerformedAndStayPerformed() phaseAfterPerformed: InputActionPhase.Performed); } + /// + /// Marks the interaction as being interrupted or aborted. This is relevant to signal that the interaction + /// pattern was not completed, for example, the user pressed and then released a button before the minimum + /// time required for a to complete. + /// + /// + /// This is used by most existing interactions to cancel the transitions in the interaction state machine + /// when a condition required to proceed turned false or other indirect requirements were not met, such as + /// time-based conditions. + /// public void Canceled() { if (m_TriggerState.phase != InputActionPhase.Canceled)