数学工具

MathUtil 提供一组常用的数学扩展方法，用于补足 Unity 内置 Mathf 未覆盖的功能。 这些方法在 数据解析、数值处理、插值、范围判定、角度转换、几何工具 等场景中常被使用。

MathUtil 的设计目标：

• 补齐缺失的常用数学功能（例如范围限定、比例换算）
• 简化业务代码中重复出现的数学逻辑
• 与 Unity 的 Vector2 / Vector3 无缝协作
• 提供游戏开发常见的数学辅助工具

1. 数值范围处理

1.1 限制数值（Clamp）

等同于 Mathf.Clamp，但提供更广泛的重载版本（int、float、double）。

float v = MathUtil.Clamp(12.5f, 0f, 10f);
// 输出：10

1.2 是否在范围内（InRange）

判断 value 是否位于 [min, max] 区间（包含边界）

bool ok = MathUtil.InRange(5, 0, 10);
// true

2. 百分比 / 比例工具

这些方法在数值 UI、进度条、经验条中非常常用。

2.1 计算百分比（0–1）

float p = MathUtil.Percent01(30, 0, 100);
// 输出：0.3

2.2 从百分比反推出值

float v = MathUtil.PercentToValue(0.75f, 0, 200);
// 输出：150

2.3 区间映射（Remap）

将一个区间的值映射到另一个区间：

float v = MathUtil.Remap(5, 0, 10, 0, 1);
// 输出：0.5

适用于难度、速度、数值归一化。

3. 插值工具

3.1 外插（LerpUnclamped）

标准 Lerp 在 t>1 时会被限制，而本方法不会：

float v = MathUtil.LerpUnclamped(0, 10, 1.5f);
// 输出：15

常用于：

• 过冲 / 回弹动画
• 相机外推预测
• 曲线外插

3.2 平滑进度（SmoothProgress）

用于“假进度条”“加载条模拟”“缓动逼近”等场景：

float p = MathUtil.SmoothProgress(progress, 0.9f, 0.05f);

行为说明：

• current 会逐帧向 target 逼近
• speed 越大，逼近速度越快
• 不会超越目标值
• 常用于模拟加载条在 0~90% 之间平滑增加

适合：

• Loading 页面伪进度动画
• AI 读条动画
• boss 蓄力动画
• 任意数值缓动趋近效果

4. 平面类型（参与计算的坐标系）

MathUtil 支持四种空间平面：

• XY（俯视 2D 游戏）
• XZ（3D 地面游戏主要使用）
• YZ
• XYZ（完整三维）

5. 角度工具

5.1 角度与弧度转换

float rad = MathUtil.Deg2Rad(180); // 3.14
float deg = MathUtil.Rad2Deg(3.14f); // 180

6. 距离计算

6.1 获取两点之间的距离

计算两个向量坐标点之间的距离，支持手动指定多平面

float d = MathUtil.GetObjDistance(pos1, pos2, MathUtil.PlaneType.XZ);

6.2 判断是否进入距离范围

判断两点之间的距离是否小于等于目标值（平方比较避免开方，性能更优）

bool near = MathUtil.CheckObjDistance(pos1, pos2, 5f);

7. 屏幕相关

7.1 判断点是否在屏幕外

bool outScreen = MathUtil.IsWorldPosOutScreen(worldPos);

支持相机背面判定（z<=0）。

8. 扇形 / 圆锥范围检测

用于敌人视野锥、攻击扇形等技能判定。

bool hit = MathUtil.IsInSectorRange(center, forward, targetPos, 8f, 60f);

特性：

• 支持 XY / XZ / YZ / XYZ
• 使用点积判断角度
• 提供半径 + 角度双判定
• DebugMode 下自动使用 GizmosDrawer 可视化扇形

9. 射线检测（Raycast）

MathUtil 对 Unity 物理射线做了更强封装。

9.1 单个结果（RayCast）

MathUtil.RayCast<RaycastHit>(ray, hit =>
{
    Debug.Log(hit.point);
}, 30f);

支持返回：

• RaycastHit
• GameObject
• Collider
• 任意 Component（自动 GetComponent）

9.2 多结果（RayCastAll）

MathUtil.RayCastAll<GameObject>(ray, go =>
{
    Debug.Log(go.name);
}, 50f);

自动可视化 Debug。

10. 范围检测（Overlap）

10.1 盒子检测（Box）

MathUtil.OverlapBox<Collider>(center, rotation, half, c =>
{
    Debug.Log("Hit: " + c.name);
});

10.2 球体检测（Sphere）

MathUtil.OverlapSphere<GameObject>(pos, 3f, go =>
{
    Debug.Log("Found: " + go);
});

11. 可视化调试（GizmosDrawer）

MathUtil 的多项功能内置了 可视化 Gizmos 调试绘制，用于在 Scene 视图中直观显示检测范围、射线、扇形、盒子等。具体可见可视化工具

这些绘制行为由以下两个条件共同控制：

• GlobalConfig.DebugMode = true（编辑器与开发版默认开启）
• 调用方法时的 gizmosToggle 参数为 true（默认开启）

只要满足条件，以下方法都会自动调用 GizmosDrawer：

11.1 扇形 / 圆锥检测

在 Scene 视图绘制扇形、圆锥范围：

MathUtil.IsInSectorRange(center, forward, target, 8f, 60f);

绘制内容：

扇形 / 圆锥轮廓、半径、面朝方向向量、命中/未命中使用不同颜色

11.2 射线可视化

MathUtil.RayCast(ray, cb, 30f);

绘制内容：

射线方向、最大距离、命中点（命中时变色）

11.3 范围检测可视化

MathUtil.OverlapBox(center, rot, half, cb);
MathUtil.OverlapSphere(center, r, cb);

绘制内容：

盒子范围（含旋转）、球体范围、包含与不包含的不同颜色

可视化调试用途：

调试敌人视野范围、调试攻击判定扇形、调试碰撞检测是否正确、调试射线最大检测范围、调试技能轰炸范围是否对齐等方面。

数学工具总结

MathUtil 提供以下核心能力：

• 数值扩展函数（Clamp / Remap / Percent）
• 插值扩展（LerpUnclamped）
• 多平面距离计算
• 屏幕位置判断
• 扇形 / 圆锥范围检测（可视化调试）
• 射线封装（raycast + 泛型支持）
• 范围检测（OverlapBox / OverlapSphere）

它是战斗系统、AI 系统、UI 动画与游戏逻辑中最常用的数学基础工具。