可视化工具

可视化工具用于在 Scene 视图中以 Gizmos 的方式绘制调试图形，包括射线、扇形、盒体、球体等。
该模块在开发阶段主要用于调试范围检测、朝向判断、技能判定区、碰撞区域、AI 视野等场景。

在框架中，可视化调试由 MathUtil 等运行时工具自动调用，无需手动挂载脚本。
所有可视化功能只在 DebugMode 开启时生效，打包后会自动失效（零运行成本）。

1. 功能概述

可视化工具提供以下能力：

  • 扇形（视野、攻击扇形、圆锥判定）
  • 射线（Raycast 可视化）
  • 盒体（OverlapBox 可视化）
  • 球体（OverlapSphere 可视化）
  • 支持 XY / XZ / YZ 平面绘制（不同游戏维度）
  • 可单独开启/关闭某一类绘制
  • 每帧自动收集绘制请求，绘制后自动清空
  • 完全 Editor Only，运行时零损耗

调用方式简单，只需在任意逻辑中调用可视化 API，即可在 Scene 视图中实时显示。

2. 使用方式：GizmosAdapter（运行时桥接层）

由于 Runtime 程序集不能引用 UnityEditor，无法直接绘制 Gizmos。
因此框架提供 GizmosAdapter：

GizmosAdapter.DrawRayAction?.Invoke(...);
GizmosAdapter.DrawSectorAction?.Invoke(...);
GizmosAdapter.DrawBoxAction?.Invoke(...);
GizmosAdapter.DrawSphereAction?.Invoke(...);

特点：

  • Runtime 可以安全调用（不会产生 Editor 引用）
  • Editor 环境下由 EditorBridge 自动绑定真正的绘制逻辑
  • 非 Editor（游戏运行时）这些委托为 null → 自动跳过 → 不绘制
  • 运行时代码必须使用 GizmosAdapter，而不是 GizmosDrawer。

3. 全局开关

可通过以下字段控制整个可视化系统的开关：

GizmosDrawer.EnableDrawer = true;

若 EnvironmentState.DebugMode == false：

  • 所有可视化自动关闭
  • 无任何性能开销

4. 绘制方法示例

以下示例需使用 GizmosAdapter：

4.1 绘制射线 Ray

GizmosAdapter.DrawRayAction?.Invoke(
    transform.position,
    transform.forward,
    5f,
    hit: true
);

4.2 绘制扇形 / 圆锥范围

GizmosAdapter.DrawSectorAction?.Invoke(
    transform.position,
    transform.forward,
    5f,
    60f,
    MathUtil.PlaneType.XZ,
    result: true
);

4.3 绘制盒子（OverlapBox）

GizmosAdapter.DrawBoxAction?.Invoke(
    transform.position,
    transform.rotation,
    new Vector3(1, 1, 1),
    hit: false
);

4.4 绘制球体（OverlapSphere）

GizmosAdapter.DrawSphereAction?.Invoke(
    transform.position,
    3f,
    hit: true
);

5. 开启/关闭特定绘制类型

你可以只开启某一类调试图形，例如只显示扇形：

GizmosDrawer.SetFeature(GizmosDrawer.GizmoFeature.Sector, true);
GizmosDrawer.SetFeature(GizmosDrawer.GizmoFeature.Ray, false);

重置全部开启：

GizmosDrawer.ResetFeatures(true);

6. 可视化平滑度（Segments）

扇形和球体采用默认细分段数 segments = 20，以保证：

  • 视觉圆滑
  • 性能开销极低

可在 EditorBridge 中修改默认值以实现更高精度。

7. 编辑器桥接层（EditorBridge）

可视化绘制的真实执行者为 GizmosDrawer（Editor 程序集）。

Runtime 调用 Adapter → EditorBridge 自动绑定 → Editor 模式中真正绘制图形：

GizmosAdapter.DrawRayAction = GizmosDrawer.DrawRay;
GizmosAdapter.DrawSectorAction = (...)=>
{
    GizmosDrawer.DrawSector(..., segments: 20);
};

打包时 UNITY_EDITOR 会被剔除，因此可视化功能完全不会进入游戏包体。

8. 工作机制简述

Runtime 工具调用 GizmosAdapter →  
（Editor 环境）EditorBridge 自动绑定委托 →  
GizmosDrawer 收到绘制请求 →  
MonoManager 调用 OnDrawGizmos →  
Scene 视图渲染调试图形 →  
绘制后自动清空队列

特点：

  • 不需要 MonoBehaviour 挂载
  • 不污染场景
  • 完全自动化
  • DebugMode 控制启用/禁用

9. 使用场景示例

  • AI 视野检测

  • 技能扇形范围可视化

  • 攻击距离调试

  • 射线检测位置调试

  • 敌人侦测范围展示

  • 圆形爆炸范围可视化

  • OverlapBox 调试角色周围区域

  • 所有绘制同时适用于 2D/3D（XY/XZ/YZ）。

10. 总结

可视化工具提供：

  • Runtime → Editor 的安全可视化桥接（GizmosAdapter）

  • 完整射线/扇形/盒体/球体绘制能力

  • DebugMode 自动启用，不影响正式版本

  • 自动化收集与绘制机制（零维护）

  • 配合 MathUtil 可实现非常强大的 AI / 战斗调试功能

  • 无需任何额外设置，只需在 Debug 模式下调用对应方法即可。