Add API additions to assist with polling workflow (#1795)

NEW: Adding new fields and methods InputAction.activeValueType, InputAction.GetMagnitude and InputAction.WasCompletedThisFrame

Author: chris-massie

.gitignore

@@ -28,6 +28,8 @@ docerrors.log
 
 Assets/**/*.api
 Assets/**/*.api.meta
+Assets/__TestInputAsset.inputactions
+Assets/__TestInputAsset.inputactions.meta
 
 Packages/packages-lock.json
 Packages/com.unity.inputsystem/artifacts/**

Assets/Tests/InputSystem/CoreTests_Actions.cs

@@ -13,7 +13,14 @@ however, it has to be formatted properly to pass verification tests.
 ### Changed
 - From 2023.2 forward: UI toolkit now uses the "UI" action map of project-wide actions as their default input actions. Previously, the actions were hardcoded and were based on `DefaultInputActions` asset which didn't allow user changes. Also, removing bindings or renaming the 'UI' action map of project wide actions will break UI input for UI toolkit.
 
+### Added
+- Added new methods and properties to [`InputAction`](xref:UnityEngine.InputSystem.InputAction):
+  - [`InputAction.activeValueType`](xref:UnityEngine.InputSystem.InputAction.activeValueType) returns the `Type` expected by `ReadValue<TValue>` based on the currently active control that is driving the action.
+  - [`InputAction.GetMagnitude`](xref:UnityEngine.InputSystem.InputAction.GetMagnitude) returns the current amount of actuation of the control that is driving the action.
+  - [`InputAction.WasCompletedThisFrame`](xref:UnityEngine.InputSystem.InputAction.WasCompletedThisFrame) returns `true` on the frame that the action stopped being in the performed phase. This allows for similar functionality to [`WasPressedThisFrame`](xref:UnityEngine.InputSystem.InputAction.WasPressedThisFrame)/[`WasReleasedThisFrame`](xref:UnityEngine.InputSystem.InputAction.WasReleasedThisFrame) when paired with [`WasPerformedThisFrame`](xref:UnityEngine.InputSystem.InputAction.WasPerformedThisFrame) except it is directly based on the interactions driving the action. For example, you can use it to distinguish between the button being released or whether it was released after being held for long enough to perform when using the Hold interaction.
+
 ### Fixed
+- Fixed syntax of code examples in API documentation for [`AxisComposite`](xref:UnityEngine.InputSystem.Composites.AxisComposite).
 - Fixed missing confirmation popup when deleting a control scheme.
 - Fixed support for menu bar/customisable keyboard shortcuts used when interacting with Actions and Action Maps.
 - Fixed add bindings button to support left button click.

Packages/com.unity.inputsystem/CHANGELOG.md

@@ -35,7 +35,7 @@ An Interaction has a set of distinct phases it can go through in response to rec
 |`Waiting`|The Interaction is waiting for input.|
 |`Started`|The Interaction has been started (that is, it received some of its expected input), but is not complete yet.|
 |`Performed`|The Interaction is complete.|
-|`Canceled`|The Interaction was interrupted and aborted. For example, the user pressed and then released a button before the minimum time required for a [hold  Interaction](#hold) to complete.|
+|`Canceled`|The Interaction was interrupted and aborted. For example, the user pressed and then released a button before the minimum time required for a [hold Interaction](#hold) to complete.|
 
 Not every Interaction triggers every phase, and the pattern in which specific Interactions trigger phases depends on the Interaction type.
 
@@ -163,7 +163,7 @@ If you haven't specifically added an Interaction to a Binding or its Action, the
 
 |__Callback__|[`InputActionType.Value`](RespondingToActions.md#value)|[`InputActionType.Button`](RespondingToActions.md#button)|[`InputActionType.PassThrough`](RespondingToActions.md#pass-through)|
 |-----------|-------------|------------|-----------------|
-|[`started`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_started)|Control(s) changed value away from the default value.|Button started being pressed but has not necessarily crossed the press threshold yet.|First Control actuation after Action was enabled.|
+|[`started`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_started)|Control(s) changed value away from the default value.|Button started being pressed but has not necessarily crossed the press threshold yet.|not used|
 |[`performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed)|Control(s) changed value.|Button was pressed to at least the button [press threshold](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint).|Control changed value.|
 |[`canceled`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_canceled)|Control(s) are no longer actuated.|Button was released. If the button was pressed above the press threshold, the button has now fallen to or below the [release threshold](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_buttonReleaseThreshold). If the button was never fully pressed, the button is now back to completely unpressed.|Action is disabled.|
 

Packages/com.unity.inputsystem/Documentation~/Interactions.md

@@ -3,7 +3,7 @@
 
 There are two main techniques you can use to respond to Actions in your project. These are to either use **polling** or an **event-driven** approach.
 
-- The **Polling** approach refers to the technique of repeatedly checking the current state of the Actions you are interested in. Typically you would do this in the Update() method of a Monobehaviour script.
+- The **Polling** approach refers to the technique of repeatedly checking the current state of the Actions you are interested in. Typically you would do this in the `Update()` method of a `MonoBehaviour` script.
 - The **Event-driven** approach involves creating your own methods in code that are automatically called when an action is performed.
 
 For most common scenarios, especially action games where the user's input should have a continuous effect on an in-game character, **Polling** is usually simpler and easier to implement.
@@ -39,27 +39,40 @@ public class Example : MonoBehaviour
 
 Note that the value type has to correspond to the value type of the control that the value is being read from.
 
-To determine whether an action was performed in the current frame, you can use [`InputAction.WasPerformedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame):
+There are two methods you can use to poll for `performed` [action callbacks](#action-callbacks) to determine whether an action was performed or stopped performing in the current frame.
 
+These methods differ from [`InputAction.WasPressedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame) and [`InputAction.WasReleasedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame) in that these depend directly on the [Interactions](Interactions.md) driving the action (including the [default Interaction](Interactions.md#default-interaction) if no specific interaction has been added to the action or binding).
+
+|Method|Description|
+|------|-----------|
+|[`InputAction.WasPerformedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame)|True if the [`InputAction.phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase) of the action has, at any point during the current frame, changed to [`Performed`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Performed).|
+|[`InputAction.WasCompletedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasCompletedThisFrame)|True if the [`InputAction.phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase) of the action has, at any point during the current frame, changed away from [`Performed`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Performed) to any other phase. This can be useful for [Button](#button) actions or [Value](#value) actions with interactions like [Press](Interactions.md#press) or [Hold](Interactions.md#hold) when you want to know the frame the interaction stops being performed. For actions with the [default Interaction](Interactions.md#default-interaction), this method will always return false for [Value](#value) and [Pass-Through](#pass-through) actions (since the phase stays in [`Started`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Started) for Value actions and stays in [`Performed`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Performed) for Pass-Through).|
+
+This example uses the Interact action from the [default actions](ActionsEditor.md#the-default-actions), which has a [Hold](Interactions.md#hold) interaction to make it perform only after the bound control is held for a period of time (for example, 0.4 seconds):
 
 ```CSharp
 using UnityEngine;
 using UnityEngine.InputSystem;
 
 public class Example : MonoBehaviour
 {
-    InputAction jumpAction;
+    InputAction interactAction;
 
     private void Start()
     {
-        jumpAction = InputSystem.actions.FindAction("Jump");
+        interactAction = InputSystem.actions.FindAction("Interact");
     }
 
     void Update()
     {
-        if (jumpAction.WasPerformedThisFrame())
+        if (interactAction.WasPerformedThisFrame())
         {
-            // your code to respond to the Jump action here
+            // your code to respond to the first frame that the Interact action is held for enough time
+        }
+
+        if (interactAction.WasCompletedThisFrame())
+        {
+            // your code to respond to the frame that the Interact action is released after being held for enough time
         }
     }
 }
@@ -73,7 +86,7 @@ Finally, there are three methods you can use to poll for button presses and rele
 |[`InputAction.WasPressedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame)|True if the level of [actuation](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude) on the action has, at any point during the current frame, reached or gone above the [press point](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint).|
 |[`InputAction.WasReleasedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame)|True if the level of [actuation](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude) on the action has, at any point during the current frame, gone from being at or above the [press point](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint) to at or below the [release threshold](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_buttonReleaseThreshold).|
 
-This example uses three actions called Shield, Teleport and Submit (which are not included in the [default actions]()):
+This example uses three actions called Shield, Teleport and Submit (which are not included in the [default actions](ActionsEditor.md#the-default-actions)):
 
 ```CSharp
 using UnityEngine;
@@ -101,15 +114,13 @@ public class Example : MonoBehaviour
 
         if (teleportAction.WasPressedThisFrame())
         {
-            // teleport occurs on the first frame that the action was performed, and not again until the button is released
+            // teleport occurs on the first frame that the action is pressed, and not again until the button is released
         }
 
         if (submit.WasReleasedThisFrame())
         {
             // submit occurs on the frame that the action is released, a common technique for buttons relating to UI controls.
         }
-
-
     }
 }
 ```

Packages/com.unity.inputsystem/Documentation~/RespondingToActions.md

@@ -16,7 +16,7 @@ namespace UnityEngine.InputSystem.Composites
     /// <example>
     /// <code>
     /// var action = new InputAction();
-    /// action.AddCompositeBinding("Axis(minValue=0,maxValue=2")
+    /// action.AddCompositeBinding("Axis(minValue=0,maxValue=2)")
     ///     .With("Negative", "&lt;Keyboard&gt;/a")
     ///     .With("Positive", "&lt;Keyboard&gt;/d");
     /// </code>
@@ -73,7 +73,7 @@ public class AxisComposite : InputBindingComposite<float>
         /// <example>
         /// <code>
         /// var action = new InputAction();
-        /// action.AddCompositeBinding("Axis(minValue=0,maxValue=2")
+        /// action.AddCompositeBinding("Axis(minValue=0,maxValue=2)")
         ///     .With("Negative", "&lt;Keyboard&gt;/a")
         ///     .With("Positive", "&lt;Keyboard&gt;/d");
         /// </code>
@@ -95,7 +95,7 @@ public class AxisComposite : InputBindingComposite<float>
         /// <example>
         /// <code>
         /// var action = new InputAction();
-        /// action.AddCompositeBinding("Axis(minValue=0,maxValue=2")
+        /// action.AddCompositeBinding("Axis(minValue=0,maxValue=2)")
         ///     .With("Negative", "&lt;Keyboard&gt;/a")
         ///     .With("Positive", "&lt;Keyboard&gt;/d");
         /// </code>