// Math/Libraries/BFL_Vectors.ts

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

/**
 * Blueprint Function Library: Vector Mathematics
 * Pure mathematical functions for vector operations and surface angle calculations
 * Used by movement system for deterministic surface classification
 */
export class BFL_VectorsClass extends BlueprintFunctionLibrary {
  constructor(
    outer: null | BlueprintFunctionLibrary = null,
    name: string = 'BFL_Vectors'
  ) {
    super(outer, name);
  }

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

  /**
   * Calculate angle between two normalized vectors
   * @param Vector1 - First normalized vector
   * @param Vector2 - Second normalized vector
   * @returns Angle between vectors in radians (0 to π)
   * @example
   * // 90° angle between X and Z axes
   * GetAngleBetweenVectors(new Vector(1,0,0), new Vector(0,0,1)) // returns π/2
   */
  public GetAngleBetweenVectors(Vector1: Vector, Vector2: Vector): Float {
    /**
     * Internal calculation using dot product and arccosine
     */
    const CalculateAngleBetweenVectors = (v1: Vector, v2: Vector): Float =>
      MathLibrary.Acos(MathLibrary.Dot(v1, v2));

    return CalculateAngleBetweenVectors(Vector1, Vector2);
  }

  /**
   * Generate surface normal vector from angle in degrees
   * @param AngleDegrees - Angle from horizontal in degrees (0-180)
   * @returns Normalized surface normal vector
   * @example
   * // Flat surface (0°)
   * GetNormalFromAngle(0) // returns Vector(0,0,1)
   * // Vertical wall (90°)
   * GetNormalFromAngle(90) // returns Vector(1,0,0)
   */
  public GetNormalFromAngle(AngleDegrees: Float): Vector {
    /**
     * Calculate X component using sine of angle
     */
    const CalculateX = (angle: Float): Float =>
      MathLibrary.Sin(MathLibrary.DegreesToRadians(angle));

    /**
     * Calculate Z component using cosine of angle
     */
    const CalculateZ = (angle: Float): Float =>
      MathLibrary.Cos(MathLibrary.DegreesToRadians(angle));

    return new Vector(CalculateX(AngleDegrees), 0, CalculateZ(AngleDegrees));
  }

  /**
   * Calculate angle between surface normal and up vector
   * @param SurfaceNormal - Normalized surface normal vector
   * @returns Angle from horizontal plane in radians (0 = flat, π/2 = vertical)
   * @example
   * // Flat surface
   * GetSurfaceAngle(new Vector(0,0,1)) // returns 0
   * // Vertical wall
   * GetSurfaceAngle(new Vector(1,0,0)) // returns π/2
   */
  public GetSurfaceAngle(SurfaceNormal: Vector): Float {
    return this.GetAngleBetweenVectors(SurfaceNormal, new Vector(0, 0, 1));
  }
}

export const BFL_Vectors = new BFL_VectorsClass();