"""
FreeExile Common Mathematical Utilities.
Pure, stateless mathematical and spatial calculation functions.
High performance, zero-allocation, suitable for real-time game loops.
"""

from __future__ import annotations
import math


def euclidean_distance_2d(x1: float, y1: float, x2: float, y2: float) -> float:
    """Calculates 2D Euclidean distance between two points."""
    return math.hypot(x1 - x2, y1 - y2)


def euclidean_distance_squared_2d(x1: float, y1: float, x2: float, y2: float) -> float:
    """Calculates squared 2D Euclidean distance (avoids costly sqrt in proximity checks)."""
    dx = x1 - x2
    dy = y1 - y2
    return dx * dx + dy * dy


def is_within_radius_2d(x1: float, y1: float, x2: float, y2: float, radius: float) -> bool:
    """Fast check whether two points are within a circular radius using squared distance."""
    return euclidean_distance_squared_2d(x1, y1, x2, y2) <= (radius * radius)


def clamp(val: float, min_val: float, max_val: float) -> float:
    """Clamps a numeric value between [min_val, max_val]."""
    if val < min_val:
        return min_val
    if val > max_val:
        return max_val
    return val


def lerp(a: float, b: float, t: float) -> float:
    """Linear interpolation between a and b by factor t (clamped to [0.0, 1.0])."""
    clamped_t = clamp(t, 0.0, 1.0)
    return a + (b - a) * clamped_t