tengri/Content/UE/MathLibrary.ts

// UE/SystemLibrary.ts

import { BlueprintFunctionLibrary } from '#root/UE/BlueprintFunctionLibrary.ts';
import type { Color } from '#root/UE/Color.ts';
import type { Float } from '#root/UE/Float.ts';
import { LinearColor } from '#root/UE/LinearColor.ts';
import type { Vector } from '#root/UE/Vector.ts';

/**
 * System Library: Core Mathematical Functions
 * Wrapper for JavaScript Math functions with UE5 compatibility
 * Provides deterministic mathematical operations for movement calculations
 */
class MathLibraryClass extends BlueprintFunctionLibrary {
  constructor(
    outer: null | BlueprintFunctionLibrary = null,
    name: string = 'MathLibrary'
  ) {
    super(outer, name);
  }

  // ════════════════════════════════════════════════════════════════════════════════════════
  //                                    FUNCTIONS
  // ════════════════════════════════════════════════════════════════════════════════════════

  /**
   * Convert degrees to radians
   * @param Degrees - Angle in degrees
   * @returns Angle in radians
   * @example
   * // Convert 90 degrees to radians
   * DegreesToRadians(90) // returns π/2
   */
  public DegreesToRadians(Degrees: Float): Float {
    return (Degrees * Math.PI) / 180;
  }

  /**
   * Calculate sine of angle in radians
   * @param Value - Angle in radians
   * @returns Sine value (-1 to 1)
   */
  public Sin(Value: Float): Float {
    return Math.sin(Value);
  }

  /**
   * Calculate cosine of angle in radians
   * @param Value - Angle in radians
   * @returns Cosine value (-1 to 1)
   */
  public Cos(Value: Float): Float {
    return Math.cos(Value);
  }

  /**
   * Calculate arccosine (inverse cosine) of value
   * @param Value - Input value (-1 to 1)
   * @returns Angle in radians (0 to π)
   */
  public Acos(Value: Float): Float {
    return Math.acos(Value);
  }

  /**
   * Calculate dot product of two vectors
   * @param Vector1 - First vector
   * @param Vector2 - Second vector
   * @returns Dot product scalar value
   * @example
   * // Dot product of perpendicular vectors
   * Dot(new Vector(1,0,0), new Vector(0,1,0)) // returns 0
   */
  public Dot(Vector1: Vector, Vector2: Vector): Float {
    return (
      Vector1.X * Vector2.X + Vector1.Y * Vector2.Y + Vector1.Z * Vector2.Z
    );
  }

  /**
   * Color to LinearColor conversion
   * @param color - Color with 0-255 RGBA components
   * @returns LinearColor with 0-1 RGBA components
   * @example
   * // Convert Color(255,0,0,255) to LinearColor
   * ColorToLinearColor(new Color(255,0,0,255)) // returns LinearColor(1,0,0,1)
   */
  public ColorToLinearColor(color: Color): LinearColor {
    return new LinearColor(
      color.R / 255,
      color.G / 255,
      color.B / 255,
      color.A / 255
    );
  }

  /**
   * Clamp a float value between a minimum and maximum
   * @param Value - Value to clamp
   * @param Min - Minimum limit
   * @param Max - Maximum limit
   * @returns Clamped value
   * @example
   * // Clamp 10 between 0 and 5
   * Clamp(10, 0, 5) // returns 5
   */
  public ClampFloat(Value: Float, Min: Float, Max: Float): Float {
    return Math.min(Math.max(Value, Min), Max);
  }

  /**
   * Calculate vector length (magnitude)
   * @param Vector - Input vector
   * @returns Length (magnitude) of vector
   * @example
   * // Length of vector (3,4,0)
   * VectorLength(new Vector(3,4,0)) // returns 5
   */
  public VectorLength(Vector: Vector): Float {
    return Math.sqrt(
      Vector.X * Vector.X + Vector.Y * Vector.Y + Vector.Z * Vector.Z
    );
  }

  /**
   * Interpolate a float value towards a target
   * @param Current - Current value
   * @param Target - Target value
   * @param DeltaTime - Time since last update
   * @param InterpSpeed - Speed of interpolation
   * @returns New interpolated value
   * @example
   * // Interpolate 0 towards 10 over 1 second at speed 5
   * FInterpTo(0, 10, 1, 5) // returns 5
   */
  public FInterpTo(
    Current: Float,
    Target: Float,
    DeltaTime: Float,
    InterpSpeed: Float
  ): Float {
    if (InterpSpeed <= 0) {
      return Target;
    }
    const Dist = Target - Current;
    if (Dist * Dist < 0.00001) {
      return Target;
    }
    const DeltaMove = Dist * Math.min(DeltaTime * InterpSpeed, 1);
    return Current + DeltaMove;
  }

  /**
   * Absolute value of a float
   * @param Value - Input value
   * @returns Absolute value
   * @example
   * // Absolute value of -5
   * abs(-5) // returns 5
   */
  public abs(Value: Float): Float {
    return Math.abs(Value);
  }
}

/**
 * Global instance of math library
 * Used throughout the movement system for mathematical calculations
 */
export const MathLibrary = new MathLibraryClass();