Add angle distance functions PR #7092

Author: zekeatchan

src/math/angle/GetClockwiseDistance.js

@@ -0,0 +1,25 @@
+/**
+ * @author       samme
+ * @copyright    2025 Phaser Studio Inc.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+var NormalizeAngle = require('./Normalize');
+
+/**
+ * Gets the shortest nonnegative angular distance from angle1 to angle2.
+ *
+ * @function Phaser.Math.Angle.GetClockwiseDistance
+ * @since 4.0.0
+ *
+ * @param {number} angle1 - The starting angle in radians.
+ * @param {number} angle2 - The target angle in radians.
+ *
+ * @return {number} The distance in radians, in the range [0, 2pi).
+ */
+var GetClockwiseDistance = function (angle1, angle2)
+{
+    return NormalizeAngle(angle2 - angle1);
+};
+
+module.exports = GetClockwiseDistance;

src/math/angle/GetCounterClockwiseDistance.js

@@ -0,0 +1,35 @@
+/**
+ * @author       samme
+ * @copyright    2025 Phaser Studio Inc.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+var MATH_CONST = require('../const');
+var NormalizeAngle = require('./Normalize');
+
+var TAU = MATH_CONST.TAU;
+
+/**
+ * Gets the shortest nonpositive angular distance from angle1 to angle2.
+ *
+ * @function Phaser.Math.Angle.GetCounterClockwiseDistance
+ * @since 4.0.0
+ *
+ * @param {number} angle1 - The starting angle in radians.
+ * @param {number} angle2 - The target angle in radians.
+ *
+ * @return {number} The distance in radians, in the range (-2pi, 0].
+ */
+var GetCounterClockwiseDistance = function (angle1, angle2)
+{
+    var distance = NormalizeAngle(angle2 - angle1);
+
+    if (distance > 0)
+    {
+        distance -= TAU;
+    }
+
+    return distance;
+};
+
+module.exports = GetCounterClockwiseDistance;

src/math/angle/GetShortestDistance.js

@@ -0,0 +1,29 @@
+/**
+ * @author       samme
+ * @copyright    2025 Phaser Studio Inc.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+var WrapAngle = require('./Wrap');
+
+/**
+ * Gets the shortest signed angular distance from angle1 to angle2.
+ * A positive distance is a clockwise rotation.
+ * A negative distance is a counter-clockwise rotation.
+ *
+ * For calculation in degrees use {@link Phaser.Math.Angle.ShortestBetween} instead.
+ *
+ * @function Phaser.Math.Angle.GetShortestDistance
+ * @since 4.0.0
+ *
+ * @param {number} angle1 - The first angle in radians.
+ * @param {number} angle2 - The second angle in radians.
+ *
+ * @return {number} The distance in radians, in the range [-pi, pi).
+ */
+var GetShortestDistance = function (angle1, angle2)
+{
+    return WrapAngle(angle2 - angle1);
+};
+
+module.exports = GetShortestDistance;

src/math/angle/ShortestBetween.js

@@ -15,6 +15,8 @@
  * greater than 0 then it's a counter-clockwise rotation, if < 0 then it's
  * a clockwise rotation.
  *
+ * For calculation in radians use {@link Phaser.Math.Angle.GetShortestDistance} instead.
+ *
  * @function Phaser.Math.Angle.ShortestBetween
  * @since 3.0.0
  *

src/math/angle/index.js

@@ -15,6 +15,9 @@ module.exports = {
     BetweenPointsY: require('./BetweenPointsY'),
     BetweenY: require('./BetweenY'),
     CounterClockwise: require('./CounterClockwise'),
+    GetClockwiseDistance: require('./GetClockwiseDistance'),
+    GetCounterClockwiseDistance: require('./GetCounterClockwiseDistance'),
+    GetShortestDistance: require('./GetShortestDistance'),
     Normalize: require('./Normalize'),
     Random: require('./Random'),
     RandomDegrees: require('./RandomDegrees'),