【Unity】Getting Started with Unity Gizmos: Visualizing Debug Information in the Scene View

Overview

Tested with: Unity 2022.3 LTS / Unity 6

"Where is that empty GameObject?" "How far does this trigger extend?" "I want to visually check and adjust the AI detection range..."

This is where Gizmos come in. Gizmos are a powerful tool for visualizing debug information in the Scene View. They are only displayed in the Scene View and are not included in builds.

Basic Usage of Gizmos

OnDrawGizmos: Always Draw Gizmos

using UnityEngine;

public class GizmosExample : MonoBehaviour
{
    void OnDrawGizmos()
    {
        // Draw a yellow sphere
        Gizmos.color = Color.yellow;
        Gizmos.DrawSphere(transform.position, 1.0f);
    }
}

OnDrawGizmosSelected: Draw Gizmos Only When Selected

void OnDrawGizmosSelected()
{
    // Draw a red sphere
    Gizmos.color = Color.red;
    Gizmos.DrawSphere(transform.position, 1.0f);
}

Combining Both

void OnDrawGizmos()
{
    // Green when not selected
    Gizmos.color = Color.green;
    Gizmos.DrawSphere(transform.position, 1.0f);
}

void OnDrawGizmosSelected()
{
    // Red when selected
    Gizmos.color = Color.red;
    Gizmos.DrawSphere(transform.position, 1.0f);
}

Key Methods of the Gizmos Class

Method	Description
Gizmos.color	Sets the draw color
Gizmos.DrawSphere	Draws a sphere
Gizmos.DrawWireSphere	Draws a wireframe sphere
Gizmos.DrawCube	Draws a cube
Gizmos.DrawWireCube	Draws a wireframe cube
Gizmos.DrawLine	Draws a line between two points
Gizmos.DrawRay	Draws a ray
Gizmos.DrawIcon	Draws an icon
Gizmos.DrawMesh	Draws a mesh
Gizmos.matrix	Sets the transformation matrix

Usage Examples

// Draw a sphere
Gizmos.color = Color.red;
Gizmos.DrawSphere(transform.position, 1.0f);

// Draw a wireframe cube
Gizmos.color = Color.yellow;
Gizmos.DrawWireCube(transform.position, new Vector3(2, 2, 2));

// Draw a line
Gizmos.color = Color.blue;
Gizmos.DrawLine(transform.position, transform.position + Vector3.forward * 5);

// Draw a ray
Gizmos.DrawRay(transform.position, transform.forward * 5);

Semi-Transparent Drawing

You can draw semi-transparent Gizmos by using a Color with an alpha value.

// Semi-transparent red (alpha 0.3)
Gizmos.color = new Color(1f, 0f, 0f, 0.3f);
Gizmos.DrawSphere(transform.position, 2.0f);

// Draw the outline as opaque
Gizmos.color = Color.red;
Gizmos.DrawWireSphere(transform.position, 2.0f);

Combining a filled shape with an outline makes it easier to see the range.

Gizmos vs Debug.Draw

Feature	Gizmos	Debug.Draw
Where to call	OnDrawGizmos / OnDrawGizmosSelected	Update / FixedUpdate, etc.
Use case	Editor design and adjustment	Runtime debugging
Display timing	Always (even in edit mode)	Only during play mode
Duration	Drawn every frame	Configurable via duration parameter

Debug.Draw Example

void Update()
{
    // Draw a ray at runtime (red, displayed for 1 second)
    Debug.DrawRay(transform.position, transform.forward * 10f, Color.red, 1f);

    // Draw a line between two points
    Debug.DrawLine(pointA, pointB, Color.green);
}

When to use which: Use Gizmos for range visualization and design work in the Editor. Use Debug.Draw for runtime behavior verification (such as raycast trajectories).

Practical Examples

Example 1: Visualizing an Empty GameObject

public class EmptyObjectGizmo : MonoBehaviour
{
    [SerializeField] private Color normalColor = Color.green;
    [SerializeField] private Color selectedColor = Color.red;
    [SerializeField] private float radius = 0.5f;

    void OnDrawGizmos()
    {
        Gizmos.color = normalColor;
        Gizmos.DrawSphere(transform.position, radius);
    }

    void OnDrawGizmosSelected()
    {
        Gizmos.color = selectedColor;
        Gizmos.DrawSphere(transform.position, radius);
    }
}

Example 2: Visualizing a Trigger Zone

public class TriggerGizmo : MonoBehaviour
{
    [SerializeField] private BoxCollider boxCollider;

    void OnDrawGizmos()
    {
        if (boxCollider == null) return;

        Gizmos.color = Color.green;
        Gizmos.matrix = transform.localToWorldMatrix;
        Gizmos.DrawWireCube(boxCollider.center, boxCollider.size);
    }
}

Example 3: Visualizing AI Detection Range

public class AIDetectionGizmo : MonoBehaviour
{
    [SerializeField] private float detectionRange = 10.0f;

    void OnDrawGizmos()
    {
        Gizmos.color = Color.yellow;
        Gizmos.DrawWireSphere(transform.position, detectionRange);
    }

    void OnDrawGizmosSelected()
    {
        Gizmos.color = Color.red;
        Gizmos.DrawWireSphere(transform.position, detectionRange);
        // Display the forward direction as a line
        Gizmos.DrawRay(transform.position, transform.forward * detectionRange);
    }
}

Example 4: Visualizing a Path

public class PathGizmo : MonoBehaviour
{
    [SerializeField] private Transform[] waypoints;

    void OnDrawGizmos()
    {
        if (waypoints == null || waypoints.Length < 2) return;

        Gizmos.color = Color.cyan;

        // Display waypoints as spheres
        foreach (var waypoint in waypoints)
        {
            if (waypoint != null)
                Gizmos.DrawSphere(waypoint.position, 0.3f);
        }

        // Connect waypoints with lines
        for (int i = 0; i < waypoints.Length - 1; i++)
        {
            if (waypoints[i] != null && waypoints[i + 1] != null)
                Gizmos.DrawLine(waypoints[i].position, waypoints[i + 1].position);
        }
    }
}

Example 5: Debugging Raycasts

public class RaycastGizmo : MonoBehaviour
{
    [SerializeField] private float rayDistance = 10.0f;

    void OnDrawGizmos()
    {
        // Display the raycast direction as a line
        Gizmos.color = Color.red;
        Gizmos.DrawRay(transform.position, transform.forward * rayDistance);

        // Display a sphere at the hit position
        if (Physics.Raycast(transform.position, transform.forward, out RaycastHit hit, rayDistance))
        {
            Gizmos.color = Color.green;
            Gizmos.DrawSphere(hit.point, 0.2f);
        }
    }
}

Performance note: Running Physics.Raycast inside OnDrawGizmos can cause the Editor to slow down when attached to many objects. Limit this to debugging purposes only, and for production use OnDrawGizmosSelected (which only runs when selected) instead.

Showing and Hiding Gizmos

Click the "Gizmos" button at the top-right of the Scene View to open the Gizmos menu.

• You can toggle Gizmos visibility for each component individually
• Adjust the Gizmos size using the "3D Icons" slider
• Gizmos can be displayed in both the Scene View and Game View

Displaying in the Game View

Turn on the "Gizmos" button at the top-right of the Game View to display Gizmos in the Editor's Game View as well. This is convenient for debugging.

About builds: OnDrawGizmos is not called in built games, but the method itself is included in the build as IL (Intermediate Language). There is virtually no harm, but if you want to strictly exclude it from the build, wrap it with #if UNITY_EDITOR.

#if UNITY_EDITOR
void OnDrawGizmos()
{
    Gizmos.color = Color.yellow;
    Gizmos.DrawSphere(transform.position, 1.0f);
}
#endif

Conclusion: In most cases, you do not need #if UNITY_EDITOR. There is no performance impact. Only use it when you want to make the code's intent explicit or when strict build size management is required.

Next Step: The Handles Class

For more advanced Scene View drawing, there is the Handles class.

Feature	Gizmos	Handles
Location	Regular scripts	Editor folder
Interaction	Display only	Values can be changed by dragging
Use case	Debug visualization	Custom editor tools

With Handles, you can implement interactive operations such as dragging to adjust ranges in the Scene View. Once you are comfortable with Gizmos, learning Handles is a great next step.

Best Practices

• Choose between OnDrawGizmos and OnDrawGizmosSelected - Select appropriately whether to always display or only when selected
• Use different colors - Green for normal, red for selected, yellow for warnings, etc.
• Expose settings with SerializeField - Make colors and sizes adjustable in the Inspector
• Always add null checks - Prevent errors when references are null
• Leverage Gizmos.matrix - Handle rotated and scaled objects properly

[SerializeField] private BoxCollider boxCollider;
[SerializeField] private Color gizmoColor = Color.green;

void OnDrawGizmos()
{
    if (boxCollider == null) return;

    Gizmos.matrix = transform.localToWorldMatrix;
    Gizmos.color = gizmoColor;
    Gizmos.DrawWireCube(boxCollider.center, boxCollider.size);
}

Summary

Gizmos are a powerful tool for visualizing debug information in the Scene View.

• Visualize empty GameObjects - Makes positions easy to identify
• Display trigger and collider ranges - Simplifies collision detection verification
• Display AI detection ranges - Enables visual parameter tuning
• Display paths and waypoints - Makes it easy to verify movement routes
• Debug raycasts - Provides visual hit detection confirmation

Make the most of Gizmos to debug more efficiently.

Further Learning

• Unity Documentation - Gizmos
• Unity Documentation - Handles