🔍 Unity Gizmos 完全指南：让调试可视化如此简单

💡 可视化调试的价值：

• 调试时想看到攻击范围、视野角度，不知道怎么画？
• Gizmos 和 Handles 有什么区别，该怎么选？
• 如何让调试信息既直观又不影响性能？
• 想在 Scene 视图中看到更多可视化信息？

这篇文章！ 将系统讲解 Unity Gizmos 机制，让你的调试工作事半功倍！

一、Gizmos 概述

Gizmos 类提供了一套在 Scene 视图中绘制调试可视化元素的能力，与 Handles 不同，Gizmos 绘制的是不可交互的纯显示元素。

1.1 Gizmos 与 Handles 对比

特性	Gizmos	Handles
作用	纯可视化显示	可交互的编辑手柄
位置	OnDrawGizmos()	OnSceneGUI()
交互	❌ 不可交互	✅ 可拖动、点击
运行状态	✅ 运行时显示	❌ 仅编辑器
典型用途	调试辅助线、范围显示	路径编辑、参数调节

1.2 使用场景

┌─────────────────────────────────────────────────────────┐
│                    Scene 场景视图                       │
│                                                         │
│    ┌───────────────────────────────────────────┐       │
│    │            Gizmos 可视化元素               │       │
│    │                                           │       │
│    │    ◎ ← DrawWireSphere (范围检测)         │       │
│    │    │                                       │       │
│    │    ─── ← DrawLine (辅助线)               │       │
│    │    │                                       │       │
│    │    ┌─────────┐ ← DrawWireCube (碰撞盒)   │       │
│    │    │  ICON   │ ← DrawIcon (位置标记)     │       │
│    │    └─────────┘                             │       │
│    └───────────────────────────────────────────┘       │
│                                                         │
│  所有元素仅供调试查看，不可交互操作                      │
└─────────────────────────────────────────────────────────┘

应用场景	描述
🎯 范围可视化	显示触发区域、攻击范围、检测范围
📐 辅助线	绘制射线、方向、连接线
📦 碰撞盒	显示实际的物理碰撞体积
🔍 调试信息	显示路径、轨迹、预测位置
📍 位置标记	使用 Icon 标记重要位置

---

二、绘制生命周期

2.1 OnDrawGizmos 与 OnDrawGizmosSelected

方法	调用时机	典型用途
OnDrawGizmos()	始终调用	持续显示的调试信息
OnDrawGizmosSelected()	仅选中对象时调用	选中时的额外信息

2.2 基本结构

using UnityEngine;

public class GizmosExample : MonoBehaviour
{
    // 始终绘制的 Gizmos
    private void OnDrawGizmos()
    {
        // 设置绘制颜色
        Gizmos.color = Color.yellow;

        // 绘制各种形状...
    }

    // 仅选中对象时绘制
    private void OnDrawGizmosSelected()
    {
        // 选中时才显示的额外信息...
    }
}

2.3 执行时机

Unity 编辑器循环
│
├─ Update()
├─ LateUpdate()
├─ OnDrawGizmos()        ← 每帧绘制（所有对象）
├─ OnDrawGizmosSelected() ← 每帧绘制（仅选中对象）
└─ GUI()

⚠️ 注意：Gizmos 只在 Scene 视图中显示，Game 视图中不显示（除非开启 Gizmos 显示）。

---

三、基本形状绘制

3.1 线框形状（Wire）

方法	描述	参数
Gizmos.DrawWireSphere()	线框球体	center, radius
Gizmos.DrawWireCube()	线框立方体	center, size
Gizmos.DrawWireCapsule()	线框胶囊体	point, radius, height

private void OnDrawGizmos()
{
    // 绘制黄色线框球体
    Gizmos.color = Color.yellow;
    Gizmos.DrawWireSphere(transform.position, 2f);

    // 绘制青色线框立方体
    Gizmos.color = Color.cyan;
    Gizmos.DrawWireCube(transform.position + Vector3.right * 5, Vector3.one * 2);
}

┌────────────────────────────────────┐
│         Wire Shapes                │
│                                    │
│         ╔═════════╗                │
│         ║         ║  ← WireCube   │
│         ║         ║                │
│         ╚═════════╝                │
│                                    │
│         ┌─────────┐                │
│        ╱           ╲               │
│       │  ○ ● ○    │  ← WireSphere │
│        ╲           ╱               │
│         └─────────┘                │
└────────────────────────────────────┘

3.2 实心形状（Solid）

方法	描述	参数
Gizmos.DrawSphere()	实心球体	center, radius
Gizmos.DrawCube()	实心立方体	center, size
Gizmos.DrawMesh()	绘制网格	mesh, position, rotation

private void OnDrawGizmos()
{
    // 绘制半透明红色球体
    Gizmos.color = new Color(1, 0, 0, 0.5f);
    Gizmos.DrawSphere(transform.position, 1f);

    // 绘制半透明绿色立方体
    Gizmos.color = new Color(0, 1, 0, 0.5f);
    Gizmos.DrawCube(transform.position + Vector3.left * 3, Vector3.one);
}

3.3 线条绘制

方法	描述	参数
Gizmos.DrawLine()	绘制线段	start, end
Gizmos.DrawRay()	绘制射线	origin, direction

private void OnDrawGizmos()
{
    // 绘制线段
    Gizmos.color = Color.white;
    Gizmos.DrawLine(transform.position, transform.position + transform.forward * 5);

    // 绘制射线
    Gizmos.color = Color.red;
    Gizmos.DrawRay(transform.position, transform.right * 3);
}

---

四、常用绘制方法

4.1 完整方法表

方法	描述	返回值
基础形状
DrawWireSphere()	线框球体	-
DrawSphere()	实心球体	-
DrawWireCube()	线框立方体	-
DrawCube()	实心立方体	-
DrawWireCapsule()	线框胶囊体	-
线条相关
DrawLine()	线段	-
DrawRay()	射线	-
DrawFrustum()	视锥体	-
其他
DrawIcon()	图标	-
DrawWireDisc()	线框圆	-
DrawGUITexture()	GUI 纹理	-

4.2 视锥体绘制

// 摄像机视锥体可视化
private void OnDrawGizmosSelected()
{
    Camera camera = GetComponent<Camera>();
    if (camera == null) return;

    Gizmos.matrix = transform.localToWorldMatrix;
    Gizmos.DrawFrustum(Vector3.zero, camera.fieldOfView, camera.farClipPlane, camera.nearClipPlane, camera.aspect);
}

4.3 圆形绘制

private void OnDrawGizmos()
{
    // 绘制水平圆形
    Gizmos.color = Color.yellow;
    Gizmos.DrawWireSphere(transform.position, 3f);

    // 更精确的圆形（通过矩阵变换）
    Gizmos.matrix = Matrix4x4.TRS(transform.position, Quaternion.Euler(90, 0, 0), Vector3.one);
    Gizmos.DrawWireSphere(Vector3.zero, 3f);
}

---

五、颜色与矩阵

5.1 设置颜色

private void OnDrawGizmos()
{
    // 设置纯色
    Gizmos.color = Color.red;
    Gizmos.DrawWireSphere(transform.position, 1f);

    // 设置带透明度的颜色
    Gizmos.color = new Color(1, 0, 0, 0.3f); // 30% 不透明度
    Gizmos.DrawSphere(transform.position + Vector3.right * 2, 1f);

    // 重置为默认颜色
    Gizmos.color = Color.white;
}

5.2 使用矩阵变换

private void OnDrawGizmos()
{
    // 保存当前矩阵
    Matrix4x4 originalMatrix = Gizmos.matrix;

    // 应用自定义变换
    Gizmos.matrix = transform.localToWorldMatrix;

    // 在局部空间中绘制
    Gizmos.color = Color.cyan;
    Gizmos.DrawWireCube(Vector3.zero, Vector3.one); // 在物体局部坐标系原点绘制

    // 恢复原始矩阵
    Gizmos.matrix = originalMatrix;
}

---

六、图标绘制

6.1 DrawIcon 基本用法

private void OnDrawGizmos()
{
    // 在物体位置绘制图标
    // 参数：位置, 图标名称, 是否允许缩放
    Gizmos.DrawIcon(transform.position, "enemy_icon.png", true);
}

6.2 图标资源设置

1. 在 Assets/Gizmos 文件夹中放置图标文件
2. 图标文件支持：.png, .jpg, .gif
3. 可以在 Gizmos 窗口设置图标大小

6.3 完整图标示例

public class GizmosIconExample : MonoBehaviour
{
    public enum ObjectType
    {
        Enemy,
        Player,
        Pickup,
        Waypoint
    }

    public ObjectType type = ObjectType.Enemy;

    private void OnDrawGizmos()
    {
        string iconName = type.ToString().ToLower() + "_icon";
        Gizmos.DrawIcon(transform.position + Vector3.up * 2, iconName, true);
    }
}

---

七、完整示例：AI 感知范围可视化

using UnityEngine;

/// <summary>
/// AI 感知系统 - 可视化检测范围
/// </summary>
public class AIPerception : MonoBehaviour
{
    [Header("感知设置")]
    [Tooltip("视野角度（度）")]
    [Range(0, 360)]
    public float viewAngle = 90f;

    [Tooltip("视野距离")]
    public float viewDistance = 10f;

    [Tooltip("听觉范围")]
    public float hearDistance = 5f;

    [Header("检测层级")]
    public LayerMask targetMask;

    [Header("可视化颜色")]
    public Color viewColor = new Color(1, 0.5f, 0, 0.2f); // 半透明橙色
    public Color hearColor = new Color(0, 1, 0, 0.1f);    // 半透明绿色

    // 私有变量用于计算
    private Vector3[] viewPoints;
    private int viewPointCount = 20;

    private void OnDrawGizmos()
    {
        // 绘制听觉范围（圆形）
        Gizmos.color = hearColor;
        Gizmos.DrawWireSphere(transform.position, hearDistance);

        // 绘制前方向射线
        Gizmos.color = Color.yellow;
        Gizmos.DrawRay(transform.position, transform.forward * 2);
    }

    private void OnDrawGizmosSelected()
    {
        // 选中时显示详细的可视化

        // 1. 绘制视野扇形
        DrawViewField();

        // 2. 绘制听觉范围
        Gizmos.color = hearColor;
        Gizmos.DrawSphere(transform.position, hearDistance);

        // 3. 显示距离标注
        UnityEditor.Handles.Label(
            transform.position + transform.forward * viewDistance,
            $"<color=yellow>视野: {viewDistance}m</color>"
        );
    }

    private void DrawViewField()
    {
        // 计算视野边界点
        Vector3 leftDir = DirFromAngle(-viewAngle / 2, false);
        Vector3 rightDir = DirFromAngle(viewAngle / 2, false);

        // 绘制视野边界线
        Gizmos.color = Color.red;
        Gizmos.DrawRay(transform.position, leftDir * viewDistance);
        Gizmos.DrawRay(transform.position, rightDir * viewDistance);

        // 绘制视野扇形区域
        DrawViewSector();
    }

    private void DrawViewSector()
    {
        // 使用半透明颜色填充扇形
        Gizmos.color = viewColor;

        // 计算扇形的所有点
        if (viewPoints == null || viewPoints.Length != viewPointCount + 2)
        {
            viewPoints = new Vector3[viewPointCount + 2];
        }

        // 起始点（物体位置）
        viewPoints[0] = transform.position;

        // 计算扇形弧线上的点
        float stepAngle = viewAngle / viewPointCount;
        for (int i = 0; i <= viewPointCount; i++)
        {
            float angle = -viewAngle / 2 + stepAngle * i;
            Vector3 dir = DirFromAngle(angle, false);
            viewPoints[i + 1] = transform.position + dir * viewDistance;
        }

        // 绘制连接线
        for (int i = 0; i < viewPoints.Length - 1; i++)
        {
            Gizmos.DrawLine(viewPoints[i], viewPoints[i + 1]);
        }
    }

    private Vector3 DirFromAngle(float angleInDegrees, bool angleIsGlobal)
    {
        if (!angleIsGlobal)
        {
            angleInDegrees += transform.eulerAngles.y;
        }
        return new Vector3(Mathf.Sin(angleInDegrees * Mathf.Deg2Rad), 0, Mathf.Cos(angleInDegrees * Mathf.Deg2Rad));
    }

    // 运行时的检测逻辑
    public Transform[] GetVisibleTargets()
    {
        Collider[] targetsInViewRadius = Physics.OverlapSphere(transform.position, viewDistance, targetMask);
        List<Transform> visibleTargets = new List<Transform>();

        foreach (Collider target in targetsInViewRadius)
        {
            Transform targetTransform = target.transform;
            Vector3 dirToTarget = (targetTransform.position - transform.position).normalized;

            if (Vector3.Angle(transform.forward, dirToTarget) < viewAngle / 2)
            {
                float distanceToTarget = Vector3.Distance(transform.position, targetTransform.position);

                if (!Physics.Linecast(transform.position, targetTransform.position, ~targetMask))
                {
                    visibleTargets.Add(targetTransform);
                }
            }
        }

        return visibleTargets.ToArray();
    }
}

效果展示

┌─────────────────────────────────────────────────────────┐
│                    Scene 场景视图                       │
│                                                         │
│                    AI 感知范围                         │
│                                                         │
│              ┌─────────────────────┐                   │
│            ╱                         ╲                 │
│          ╱    ← 视野扇形区域 →       ╲                │
│        ╱                               ╲               │
│      │  ● ← 听觉范围 (圆形)             │              │
│        ╲                               ╱               │
│          ╲  ▲ (朝向)                   ╱                 │
│            ╲                         ╱                 │
│              └─────────────────────┘                   │
│                                                         │
│  ── = 视野边界线                                       │
│  ● = 听觉范围圆形                                       │
│  ▲ = AI 朝向                                           │
└─────────────────────────────────────────────────────────┘

---

八、完整示例：路径点可视化

using UnityEngine;

/// <summary>
/// 路径点组件 - 可视化路径连接
/// </summary>
public class Waypoint : MonoBehaviour
{
    [Header("路径设置")]
    public Waypoint nextWaypoint;
    public Color pathColor = Color.cyan;
    public float sphereSize = 0.3f;

    private void OnDrawGizmos()
    {
        // 绘制自身位置标记
        Gizmos.color = Color.yellow;
        Gizmos.DrawWireSphere(transform.position, sphereSize);

        // 绘制到下一个路径点的连接线
        if (nextWaypoint != null)
        {
            Gizmos.color = pathColor;
            Gizmos.DrawLine(transform.position, nextWaypoint.transform.position);

            // 绘制箭头方向
            Vector3 direction = (nextWaypoint.transform.position - transform.position).normalized;
            Vector3 midPoint = (transform.position + nextWaypoint.transform.position) * 0.5f;
            Gizmos.DrawWireSphere(midPoint, sphereSize * 0.5f);
        }
    }

    private void OnDrawGizmosSelected()
    {
        // 选中时显示更多信息
        Gizmos.color = Color.green;
        Gizmos.DrawSphere(transform.position, sphereSize * 1.5f);

        // 显示序号标签
        UnityEditor.Handles.Label(
            transform.position + Vector3.up * 0.5f,
            $"<color=yellow>{gameObject.name}</color>"
        );

        // 显示连接距离
        if (nextWaypoint != null)
        {
            float distance = Vector3.Distance(transform.position, nextWaypoint.transform.position);
            Vector3 midPoint = (transform.position + nextWaypoint.transform.position) * 0.5f;
            UnityEditor.Handles.Label(
                midPoint + Vector3.up * 0.5f,
                $"<color=cyan>{distance:F1}m</color>"
            );
        }
    }
}

/// <summary>
/// 路径管理器 - 显示完整路径
/// </summary>
public class PathManager : MonoBehaviour
{
    public Waypoint[] waypoints;

    private void OnDrawGizmos()
    {
        if (waypoints == null || waypoints.Length == 0)
            return;

        // 绘制完整路径
        Gizmos.color = Color.cyan;
        for (int i = 0; i < waypoints.Length - 1; i++)
        {
            if (waypoints[i] != null && waypoints[i + 1] != null)
            {
                Gizmos.DrawLine(waypoints[i].transform.position, waypoints[i + 1].transform.position);
            }
        }
    }
}

---

九、完整示例：触发区域可视化

using UnityEngine;

/// <summary>
/// 触发区域可视化组件
/// </summary>
public class TriggerZone : MonoBehaviour
{
    [Header("区域设置")]
    public Vector3 zoneSize = new Vector3(3, 2, 3);
    public Color zoneColor = new Color(1, 0, 0, 0.2f);
    public Color borderColor = Color.red;

    [Header("触发信息")]
    public string triggerTag = "Player";
    public bool oneTime = false;
    public bool hasTriggered = false;

    private void OnDrawGizmos()
    {
        // 根据触发状态选择颜色
        Gizmos.color = hasTriggered ? Color.gray : zoneColor;

        // 绘制触发区域
        Gizmos.DrawCube(transform.position, zoneSize);

        // 绘制边框
        Gizmos.color = hasTriggered ? Color.gray : borderColor;
        Gizmos.DrawWireCube(transform.position, zoneSize);

        // 绘制向上指示箭头
        Gizmos.DrawRay(transform.position, Vector3.up * 2);
    }

    private void OnDrawGizmosSelected()
    {
        // 选中时显示详细信息
        string info = $"<color=yellow>{gameObject.name}</color>\n";
        info += $"Tag: {triggerTag}\n";
        info += $"OneTime: {oneTime}\n";
        info += $"Triggered: {hasTriggered}\n";
        info += $"Size: {zoneSize}";

        UnityEditor.Handles.Label(transform.position + Vector3.up * 2.5f, info);

        // 显示碰撞盒大小标注
        UnityEditor.Handles.Label(
            transform.position + Vector3.right * (zoneSize.x / 2 + 0.5f),
            $"<color=cyan>{zoneSize.x}m</color>"
        );
    }

    private void OnTriggerEnter(Collider other)
    {
        if (other.CompareTag(triggerTag))
        {
            if (oneTime && hasTriggered)
                return;

            hasTriggered = true;
            Debug.Log($"{gameObject.name} triggered by {other.name}");
        }
    }

    private void OnTriggerExit(Collider other)
    {
        if (!oneTime && other.CompareTag(triggerTag))
        {
            hasTriggered = false;
        }
    }
}

---

十、Gizmos 与 Handles 配合使用

using UnityEngine;
using UnityEditor;

/// <summary>
/// 配合使用 Gizmos 和 Handles 的完整示例
/// </summary>
public class ZoneEditor : MonoBehaviour
{
    public float radius = 5f;
    public Color color = Color.cyan;
}

#if UNITY_EDITOR
[CustomEditor(typeof(ZoneEditor))]
public class ZoneEditorEditor : Editor
{
    private ZoneEditor zone;
    private SerializedProperty radiusProp;
    private SerializedProperty colorProp;

    void OnEnable()
    {
        zone = (ZoneEditor)target;
        radiusProp = serializedObject.FindProperty("radius");
        colorProp = serializedObject.FindProperty("color");
    }

    void OnSceneGUI()
    {
        // 使用 Handles 创建可交互的编辑手柄
        EditorGUI.BeginChangeCheck();

        float newRadius = Handles.RadiusHandle(
            Quaternion.identity,
            zone.transform.position,
            zone.radius
        );

        if (EditorGUI.EndChangeCheck())
        {
            Undo.RecordObject(zone, "Change Radius");
            zone.radius = newRadius;
            EditorUtility.SetDirty(zone);
        }
    }
}
#endif

/// <summary>
/// 运行时的 Gizmos 可视化
/// </summary>
public class ZoneEditor : MonoBehaviour
{
    public float radius = 5f;
    public Color color = Color.cyan;

    private void OnDrawGizmos()
    {
        // 使用 Gizmos 绘制不可交互的调试显示
        Gizmos.color = new Color(color.r, color.g, color.b, 0.3f);
        Gizmos.DrawSphere(transform.position, radius);

        Gizmos.color = color;
        Gizmos.DrawWireSphere(transform.position, radius);
    }

    private void OnDrawGizmosSelected()
    {
        // 选中时显示额外信息
        UnityEditor.Handles.Label(
            transform.position + Vector3.up * (radius + 1),
            $"<color=yellow>{gameObject.name}</color>\n" +
            $"Radius: {radius:F1}m"
        );
    }
}

---

十一、最佳实践

11.1 性能考虑

// ❌ 避免：在 OnDrawGizmos 中进行复杂计算
private void OnDrawGizmos()
{
    // 避免每帧重复计算
    var allEnemies = FindObjectsOfType<Enemy>();
    foreach (var enemy in allEnemies)
    {
        Gizmos.DrawWireSphere(enemy.transform.position, 1f);
    }
}

// ✅ 推荐：缓存数据，简单绘制
private List<Transform> cachedTargets;

void Start()
{
    // 只在初始化时计算一次
    cachedTargets = new List<Transform>();
    // ... 填充数据
}

private void OnDrawGizmos()
{
    // 只负责绘制
    foreach (var target in cachedTargets)
    {
        Gizmos.DrawWireSphere(target.position, 1f);
    }
}

11.2 条件渲染

// 使用条件编译确保只在编辑器中编译
#if UNITY_EDITOR
private void OnDrawGizmos()
{
    // Gizmos 代码...
}
#endif

// 或者使用宏定义
private void OnDrawGizmos()
{
    #if UNITY_EDITOR
    Gizmos.DrawWireSphere(transform.position, radius);
    #endif
}

11.3 颜色编码规范

// 推荐的颜色编码约定
private void OnDrawGizmos()
{
    // 🟢 绿色 = 安全/友好
    Gizmos.color = Color.green;
    Gizmos.DrawWireSphere(safeZone.position, safeZone.radius);

    // 🟡 黄色 = 警告/注意
    Gizmos.color = Color.yellow;
    Gizmos.DrawWireSphere(warningZone.position, warningZone.radius);

    // 🔴 红色 = 危险/敌人
    Gizmos.color = Color.red;
    Gizmos.DrawWireSphere(enemyZone.position, enemyZone.radius);

    // 🔵 蓝色 = 中立/信息
    Gizmos.color = Color.blue;
    Gizmos.DrawWireSphere(infoZone.position, infoZone.radius);

    // 🟣 紫色 = 特殊
    Gizmos.color = Color.magenta;
    Gizmos.DrawWireSphere(specialZone.position, specialZone.radius);
}

---

十二、Gizmos 速查表

方法	描述	参数
线框形状
DrawWireSphere()	线框球体	center, radius
DrawWireCube()	线框立方体	center, size
DrawWireCapsule()	线框胶囊体	point, radius, height
实心形状
DrawSphere()	实心球体	center, radius
DrawCube()	实心立方体	center, size
线条
DrawLine()	线段	start, end
DrawRay()	射线	origin, direction
其他
DrawIcon()	图标	position, name
DrawFrustum()	视锥体	position, fov, far, near, aspect
DrawWireDisc()	线框圆	position, normal, radius

---

十三、总结

本文介绍了 Unity Gizmos 的核心知识：

主题	要点
基本概念	Scene 视图中的纯可视化调试元素
绘制时机	OnDrawGizmos（始终）/ OnDrawGizmosSelected（选中时）
常用方法	DrawWireSphere, DrawLine, DrawCube, DrawIcon
颜色设置	Gizmos.color 控制绘制颜色
矩阵变换	Gizmos.matrix 实现局部空间绘制
与 Handles 区别	Gizmos 不可交互，Handles 可编辑
最佳实践	条件编译、性能优化、颜色编码

💡 开发建议：

• Gizmos 只用于调试，不要用于游戏逻辑
• 使用 #if UNITY_EDITOR 条件编译
• 为不同类型的范围使用统一颜色编码
• 复杂计算放在 Update 中，OnDrawGizmos 只负责绘制
• 与 Handles 配合使用，实现完整的可视化编辑

---

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 1487842110@qq.com