CMCL-1706: Added InputAxisControllerBase.GetController() and InputAxisControllerBase.TriggerRecentering() (#1072)

* Added InputAxisControllerBase.GetController() and InputAxisControllerBase.TriggerRecentering

* add missing XML doc

Author: glabute

com.unity.cinemachine/CHANGELOG.md

@@ -14,6 +14,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 - Added `CinemachineConfiner2D.CameraWasDisplaced()` and `CinemachineConfiner2D.GetCameraDisplacementDistance()` methods.
+- Added `InputAxisControllerBase.GetController()` method, to conveniently fetch an Input Controller having a specific name.
+- Added `InputAxisControllerBase.TriggerRecentering()` to trigger recentering of an axis having a specific name.
 
 
 ## [3.1.4] - 2025-06-10

com.unity.cinemachine/Runtime/Core/InputAxis.cs

@@ -303,8 +303,9 @@ public void UpdateRecentering(float deltaTime, bool forceCancel, float center)
             }
         }
 
-        /// <summary>Trigger re-centering immediately, regardless of whether re-centering
-        /// is enabled or the wait time has elapsed.</summary>
+        /// <summary>Trigger recentering immediately, regardless of whether recentering
+        /// is enabled or the wait time has elapsed.  Note that Recentering will be automatically canceled
+        /// if any change to the input value is detected.</summary>
         public void TriggerRecentering() => m_RecenteringState.m_ForceRecenter = true;
 
         /// <summary>Cancel any current re-centering in progress, and reset the wait time</summary>
@@ -398,5 +399,16 @@ public void Reset(ref InputAxis axis)
             m_CurrentSpeed = 0;
             axis.Reset();
         }
+
+        /// <summary>
+        /// Cancel any current input, resetting the speed to zero.  This will eliminate any 
+        /// residual acceleration or deceleration of the input value.
+        /// </summary>
+        /// <param name="axis">The axis in question</param>
+        public void CancelCurrentInput(ref InputAxis axis)
+        {
+            m_CurrentSpeed = 0;
+            axis.SetValueAndLastValue(axis.Value);
+        }
     }
 }

com.unity.cinemachine/Runtime/Core/InputAxisControllerBase.cs

@@ -195,8 +195,47 @@ public void UpdateControllers(UnityEngine.Object context, float deltaTime)
                 c.Driver.ProcessInput(ref m_Axes[i].DrivenAxis(), c.InputValue, deltaTime);
             }
         }
-    }
 
+        int GetControllerIndex(string axisName)
+        {
+            for (int i = 0; i < Controllers.Count; ++i)
+            {
+                var c = Controllers[i];
+                if (c.Name == axisName)
+                    return i;
+            }
+            return -1;
+        }
+
+        /// <summary>
+        /// Get the controller for a given axis name.  The axis name is the name displayed 
+        /// for the axis foldout on the inspector.
+        /// </summary>
+        /// <param name="axisName">The name of the axis, as it appears in the inspector.</param>
+        /// <returns>The first Controller object with the matching axis name, or null if not found.</returns>
+        public InputAxisControllerBase<T>.Controller GetController(string axisName)
+        {
+            int i = GetControllerIndex(axisName);
+            return i < 0 ? null : Controllers[i];
+        }
+
+        /// <summary>
+        /// Triggers recentering for a given axis, and also cancels any input currently in progrress for that axis.
+        /// </summary>
+        /// <param name="axisName">The name of the axis, as it appears in the inspector.</param>
+        /// <returns>True if the axis was found and recentering triggered, false otherwise</returns>
+        public bool TriggerRecentering(string axisName)
+        {
+            int i = GetControllerIndex(axisName);
+            if (i >= 0)
+            {
+                var c = Controllers[i];
+                c.Driver.CancelCurrentInput(ref m_Axes[i].DrivenAxis());
+                m_Axes[i].DrivenAxis().TriggerRecentering();
+            }
+            return i >= 0;
+        }
+    }
 
     /// <summary>
     /// This is a base class for a behaviour that is used to drive IInputAxisOwner behaviours,
@@ -331,6 +370,22 @@ protected void UpdateControllers(float deltaTime)
 
             m_ControllerManager.UpdateControllers(this, deltaTime);
         }
+        
+        /// <summary>
+        /// Get the controller for a given axis name.  The axis name is the name displayed 
+        /// for the axis foldout on the inspector.
+        /// </summary>
+        /// <param name="axisName">The name of the axis, as it appears in the inspector.</param>
+        /// <returns>The first Controller object with the matching axis name, or null if not found.</returns>
+        public Controller GetController(string axisName) => m_ControllerManager.GetController(axisName);
+
+        /// <summary>
+        /// Triggers recentering for a given axis, and also cancels any input currently in progress for that axis.
+        /// This ensures that the recentering begins immediately.
+        /// </summary>
+        /// <param name="axisName">The name of the axis, as it appears in the inspector.</param>
+        /// <returns>True if the axis was found and recentering triggered, false otherwise</returns>
+        public bool TriggerRecentering(string axisName) => m_ControllerManager.TriggerRecentering(axisName);
     }
 }