Add doc changes and changelog entry.

Author: Darren-Kelly-Unity

Packages/com.unity.inputsystem/CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Fixed an issue where `UIToolkit` `ClickEvent` could be fired on Android after device rotation due to inactive touch state being replayed during action initial state checks [UUM-100125](https://jira.unity3d.com/browse/UUM-100125).
 - Fixed InputSystem.onAnyButtonPress fails to trigger when the device receives a touch [UUM-137930](https://issuetracker.unity3d.com/product/unity/issues/guid/UUM-137930).
 - Fixed an incorrect ArraysHelper.HaveDuplicateReferences implementation that didn't use its arguments right [ISXB-1792] (https://github.com/Unity-Technologies/InputSystem/pull/2376)
+- Fixed `InputAction.IsPressed`, `WasPressedThisFrame`, and `WasReleasedThisFrame` using the control's `pressPoint` when a binding also had an explicit `PressInteraction` with its own `pressPoint`, which could make those APIs disagree with the interaction's press and release behavior. Action-level press APIs now follow the interaction threshold when both are set explicitly.
 
 ### Changed
 - Removed 32-bit compilation check for HID on Windows players, which had no impact anymore. (ISX-2543)

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

@@ -90,13 +90,14 @@ Finally, there are three methods you can use to poll for button presses and rele
 
 The applicable press point is chosen from, in order:
 
-1. A positive [`pressPoint`](xref:UnityEngine.InputSystem.Controls.ButtonControl.pressPoint) on the driving control when it is a [ButtonControl](xref:UnityEngine.InputSystem.Controls.ButtonControl).
-2. A positive [`pressPoint`](xref:UnityEngine.InputSystem.Controls.Vector2Control.pressPoint) when it is a [Vector2Control](xref:UnityEngine.InputSystem.Controls.Vector2Control) or [StickControl](xref:UnityEngine.InputSystem.Controls.StickControl).
-3. If the binding lists one or more [Press](xref:UnityEngine.InputSystem.Interactions.PressInteraction) interactions, the `pressPoint` from the first interaction order whose `pressPoint` is greater than zero (any interactions before this that are either not `Press`, or `Press` with the default `pressPoint` of zero, are skipped for this step).
-4. [defaultButtonPressPoint](xref:UnityEngine.InputSystem.InputSettings.defaultButtonPressPoint).
+1. If the binding lists one or more [Press](xref:UnityEngine.InputSystem.Interactions.PressInteraction) interactions, the `pressPoint` from the first `Press` interaction in list order whose `pressPoint` is greater than zero (any interactions before this that are either not `Press`, or `Press` with the default `pressPoint` of zero, are skipped) so action-level press APIs stay aligned with the interaction.
+2. Otherwise, the driving [ButtonControl](xref:UnityEngine.InputSystem.Controls.ButtonControl), [Vector2Control](xref:UnityEngine.InputSystem.Controls.Vector2Control), or [StickControl](xref:UnityEngine.InputSystem.Controls.StickControl) [`pressPointOrDefault`](xref:UnityEngine.InputSystem.Controls.ButtonControl.pressPointOrDefault).
+3. [defaultButtonPressPoint](xref:UnityEngine.InputSystem.InputSettings.defaultButtonPressPoint).
 
 On [composites](xref:input-system-action-bindings#composite-bindings), interaction parameters are taken from the composite binding.
 
+[`InputControl.IsPressed`](xref:UnityEngine.InputSystem.InputControlExtensions.IsPressed) on a control always uses that control's threshold and does not consider binding interactions.
+
 This example uses three actions called Shield, Teleport and Submit (which are not included in the [default actions](xref:project-wide-actions#the-default-actions)):
 
 ```CSharp

Packages/com.unity.inputsystem/InputSystem/Runtime/Actions/InputAction.cs

@@ -1156,18 +1156,18 @@ public void Reset()
         ///
         /// Press threshold (based on <see cref="InputControl.EvaluateMagnitude()"/> for the driving control):
         ///
-        /// 1. For a <see cref="ButtonControl"/>, <see cref="Vector2Control"/>, or <see cref="StickControl"/>, consult
-        ///    <see cref="ButtonControl.pressPoint"/> / <see cref="ButtonControl.pressPointOrDefault"/> or
-        ///    <see cref="Vector2Control.pressPoint"/> / <see cref="Vector2Control.pressPointOrDefault"/> (sticks use the vector rules)
-        ///    when a positive control <c>pressPoint</c> is set.
-        /// 2. If not set on the control but the binding has a <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
-        ///    with <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> greater than zero, use that value so this
-        ///    API stays aligned with the interaction.
-        /// 3. If the binding lists several <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
-        ///    instances, use the first in interaction list order with an explicit
-        ///    <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> greater than zero.
-        /// 4. For composite bindings, read interaction parameters from the composite binding.
-        /// 5. Otherwise use <see cref="InputSettings.defaultButtonPressPoint"/>.
+        /// 1. If the binding lists one or more <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
+        ///    instances, use the <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> from the first
+        ///    in interaction list order whose <c>pressPoint</c> is greater than zero (earlier interactions that are not
+        ///    <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>, or that leave <c>pressPoint</c> at the
+        ///    default of zero, are skipped) so this API stays aligned with the interaction.
+        /// 2. Otherwise, for a <see cref="ButtonControl"/>, <see cref="Vector2Control"/>, or <see cref="StickControl"/>, use
+        ///    <see cref="ButtonControl.pressPointOrDefault"/> or <see cref="Vector2Control.pressPointOrDefault"/>.
+        /// 3. For composite bindings, read interaction parameters from the composite binding.
+        /// 4. Otherwise use <see cref="InputSettings.defaultButtonPressPoint"/>.
+        ///
+        /// <see cref="InputControl.IsPressed"/> on the control itself always uses the control threshold and does not
+        /// consider binding interactions.
         ///
         /// <example>
         /// <code>
@@ -1244,18 +1244,18 @@ private int ExpectedFrame()
         ///
         /// Press threshold (based on <see cref="InputControl.EvaluateMagnitude()"/> for the driving control):
         ///
-        /// 1. For a <see cref="ButtonControl"/>, <see cref="Vector2Control"/>, or <see cref="StickControl"/>, consult
-        ///    <see cref="ButtonControl.pressPoint"/> / <see cref="ButtonControl.pressPointOrDefault"/> or
-        ///    <see cref="Vector2Control.pressPoint"/> / <see cref="Vector2Control.pressPointOrDefault"/> (sticks use the vector rules)
-        ///    when a positive control <c>pressPoint</c> is set.
-        /// 2. If not set on the control but the binding has a <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
-        ///    with <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> greater than zero, use that value so this
-        ///    API stays aligned with the interaction.
-        /// 3. If the binding lists several <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
-        ///    instances, use the first in interaction list order with an explicit
-        ///    <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> greater than zero.
-        /// 4. For composite bindings, read interaction parameters from the composite binding.
-        /// 5. Otherwise use <see cref="InputSettings.defaultButtonPressPoint"/>.
+        /// 1. If the binding lists one or more <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
+        ///    instances, use the <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> from the first
+        ///    in interaction list order whose <c>pressPoint</c> is greater than zero (earlier interactions that are not
+        ///    <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>, or that leave <c>pressPoint</c> at the
+        ///    default of zero, are skipped) so this API stays aligned with the interaction.
+        /// 2. Otherwise, for a <see cref="ButtonControl"/>, <see cref="Vector2Control"/>, or <see cref="StickControl"/>, use
+        ///    <see cref="ButtonControl.pressPointOrDefault"/> or <see cref="Vector2Control.pressPointOrDefault"/>.
+        /// 3. For composite bindings, read interaction parameters from the composite binding.
+        /// 4. Otherwise use <see cref="InputSettings.defaultButtonPressPoint"/>.
+        ///
+        /// <see cref="InputControl.IsPressed"/> on the control itself always uses the control threshold and does not
+        /// consider binding interactions.
         ///
         /// <example>
         /// <code>
@@ -1352,18 +1352,18 @@ public unsafe bool WasPressedThisDynamicUpdate()
         ///
         /// Press threshold (based on <see cref="InputControl.EvaluateMagnitude()"/> for the driving control):
         ///
-        /// 1. For a <see cref="ButtonControl"/>, <see cref="Vector2Control"/>, or <see cref="StickControl"/>, consult
-        ///    <see cref="ButtonControl.pressPoint"/> / <see cref="ButtonControl.pressPointOrDefault"/> or
-        ///    <see cref="Vector2Control.pressPoint"/> / <see cref="Vector2Control.pressPointOrDefault"/> (sticks use the vector rules)
-        ///    when a positive control <c>pressPoint</c> is set.
-        /// 2. If not set on the control but the binding has a <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
-        ///    with <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> greater than zero, use that value so this
-        ///    API stays aligned with the interaction.
-        /// 3. If the binding lists several <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
-        ///    instances, use the first in interaction list order with an explicit
-        ///    <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> greater than zero.
-        /// 4. For composite bindings, read interaction parameters from the composite binding.
-        /// 5. Otherwise use <see cref="InputSettings.defaultButtonPressPoint"/>.
+        /// 1. If the binding lists one or more <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>
+        ///    instances, use the <see cref="UnityEngine.InputSystem.Interactions.PressInteraction.pressPoint"/> from the first
+        ///    in interaction list order whose <c>pressPoint</c> is greater than zero (earlier interactions that are not
+        ///    <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/>, or that leave <c>pressPoint</c> at the
+        ///    default of zero, are skipped) so this API stays aligned with the interaction.
+        /// 2. Otherwise, for a <see cref="ButtonControl"/>, <see cref="Vector2Control"/>, or <see cref="StickControl"/>, use
+        ///    <see cref="ButtonControl.pressPointOrDefault"/> or <see cref="Vector2Control.pressPointOrDefault"/>.
+        /// 3. For composite bindings, read interaction parameters from the composite binding.
+        /// 4. Otherwise use <see cref="InputSettings.defaultButtonPressPoint"/>.
+        ///
+        /// <see cref="InputControl.IsPressed"/> on the control itself always uses the control threshold and does not
+        /// consider binding interactions.
         ///
         /// <example>
         /// <code>

Packages/com.unity.inputsystem/InputSystem/Runtime/Actions/InputActionState.cs

@@ -1598,9 +1598,10 @@ private void ProcessControlStateChange(int mapIndex, int controlIndex, int bindi
             return bindingStatePtr;
         }
 
-        // Resolves the explicit press threshold used to keep IsPressed / WasPressedThisFrame / WasReleasedThisFrame aligned
-        // with PressInteraction when the driving control does not set IActuationPressPoint.pressPoint. When multiple
-        // PressInteraction instances exist on the binding, uses the first in interaction list order with pressPoint > 0.
+        // Resolves the explicit press threshold from PressInteraction on the binding. When multiple PressInteraction
+        // instances exist, uses the first in interaction list order with pressPoint > 0. GetActuationPressThreshold
+        // prefers this over a control pressPoint so IsPressed / WasPressedThisFrame / WasReleasedThisFrame stay aligned
+        // with PressInteraction.
         private bool TryGetExplicitPressInteractionPressPoint(BindingState* bindingStateForInteractions, ref float explicitPressInteraction)
         {
             var count = bindingStateForInteractions->interactionCount;

Packages/com.unity.inputsystem/InputSystem/Runtime/Controls/Vector2Control.cs

@@ -42,9 +42,10 @@ public class Vector2Control : InputControl<Vector2>, IActuationPressPoint
         /// </summary>
         /// <remarks>
         /// By default, this field is set to -1. If the value of the property is negative,
-        /// <see cref="UnityEngine.InputSystem.InputSettings.defaultButtonPressPoint"/> is used unless a
-        /// <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/> on the binding sets an explicit
-        /// <c>pressPoint</c> (see <see cref="UnityEngine.InputSystem.InputAction.IsPressed"/> remarks).
+        /// <see cref="UnityEngine.InputSystem.InputSettings.defaultButtonPressPoint"/> is used for action-level press
+        /// APIs unless a <see cref="UnityEngine.InputSystem.Interactions.PressInteraction"/> on the binding sets an
+        /// explicit <c>pressPoint</c>, in which case that interaction threshold takes priority (see
+        /// <see cref="UnityEngine.InputSystem.InputAction.IsPressed"/> remarks).
         /// </remarks>
         /// <seealso cref="pressPointOrDefault"/>
         /// <seealso cref="ButtonControl"/>