Visual Debugging in Unity With Gizmos Draw Methods

ByPavee

Testing and debugging are important to make sure your game doesn’t behave in a way that it isn’t supposed to. Especially, when it comes to judging the distance of something or when you’re building a scene, it is helpful to have some sort of visual aid to help make a more accurate spacing.

The Gizmos class is a collection of methods that can be used to draw lines or shapes onto the Scene view in Unity Editor. The visuals drawn via these methods will not be visible in the game window in the editor and the built version of the game.

These methods are commonly used for confirming the distance of Raycasts and aiding with setting up your game’s scenes.

Table of Contents

How To Use Gizmos

First of all, all Gizmos methods have to be called from inside either the OnDrawGizmos event method or the OnDrawGizmosSelected event method of a script.

This is because these 2 event methods are called whenever there’s an update within the Scene view in Unity Editor.

So, what are the difference between these 2 events?

OnDrawGizmos

The OnDrawGizmos event displays the Gizmos drawings on the Scene view at all times.

A Ray drawn in OnDrawGizmos event.
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        Gizmos.color = Color.green;
        Vector2 direction = new Vector2(1.5f, 0);
        Gizmos.DrawRay(transform.position, direction);
    }
}


Code language: C# (cs)

OnDrawGizmosSelected

On the other hand, the OnDrawGizmosSelected event displays the Gizmos drawings only when the game object that the script is attached to is selected.

A Ray drawn in OnDrawGizmosSelected event.
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmosSelected()
    {
        Gizmos.color = Color.green;
        Vector2 direction = new Vector2(1.5f, 0);
        Gizmos.DrawRay(transform.position, direction);
    }
}


Code language: C# (cs)

Changing The Color Of Gizmos

The color of the lines being drawn by the Gizmos methods can be changed by setting the color property of the Gizmos class before drawing.

Any Gizmos drawn after setting the color will have the same color until a new color is set.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        // Set the color of Gizmos to green
        Gizmos.color = Color.green;

        Vector2 direction = new Vector2(1.5f, 0);
        Vector2 direction2 = new Vector2(1.5f, 0.5f);

        // These 2 rays will be drawn in green
        Gizmos.DrawRay(transform.position, direction);
        Gizmos.DrawRay(transform.position, direction2);

        // Then we set the color of Gizmos to red
        Gizmos.color = Color.red;

        Vector2 direction3 = new Vector2(1.5f, -0.5f);

        // This ray below will be red
        Gizmos.DrawRay(transform.position, direction3);
    }
}


Code language: C# (cs)

The code above draws 2 rays in green color and 1 ray in red color.

Multiple Gizmos rays with different colors

Note that the lines and shapes drawn with the Gizmos methods are not visible in the game view and the built version of the game. Gizmos are meant for debugging only.

Visual Debugging in Unity With Gizmos Draw Methods
Debug lines are not visible in the game view

How To Draw A Debug Line With Gizmos in Unity

Gizmos.DrawLine(fromPosition, toPosition);
Code language: C# (cs)

The Gizmos.DrawLine method is used to draw a debug line onto the Scene view starting from a specified position to a specified position.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        // Set the color of Gizmos to green
        Gizmos.color = Color.green;

        Vector2 from = new Vector2(-1f, -0.5f);
        Vector2 to = new Vector2(1f, 0.5f);

        // Draw a line from (-1, -0.5) to (1, 0.5)
        Gizmos.DrawLine(from, to);
    }
}


Code language: C# (cs)

The example above draws a green line from the position (-1, -0.5) to the position (1, 0.5).

Line drawn with the Gizmos.DrawLine method.

Use Vector3 instead if you want to draw a line in a 3D space.

Note that these positions are not relative to the game object’s position. Adjust the positions accordingly if you want them to be based on the object’s position.

How To Draw A Debug Ray With Gizmos in Unity

Gizmos.DrawRay(startPosition, direction);
Code language: C# (cs)

The Gizmos.DrawRay method is similar to the Gizmos.DrawLine method in which it draws a line.

The difference is the Gizmos.DrawRay method draws a line from the starting position to a specified direction for a specified distance.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        // Set the color of Gizmos to green
        Gizmos.color = Color.green;

        Vector2 direction = new Vector2(2.5f, 0);

        // Draw a line from the position of this object
        // 2.5 units to the right
        Gizmos.DrawRay(transform.position, direction);
    }
}


Code language: C# (cs)

The example above draws a green debug ray starting from the center of the game object with a length of 2.5 units to the right.

A ray drawn with Gismoz.DrawRay with a length of 2.5 units and pointing to the right.

This method is useful for determining the range of a Raycast or a projectile that moves in a straight line.

How To Draw A Debug Sphere With Gizmos In Unity

Gizmos.DrawSphere(centerPosition, radius);
Gizmos.DrawWireSphere(centerPosition, radius);
Code language: C# (cs)

There are 2 methods for drawing a debug sphere onto the Scene view in Unity Editor.

The Gizmos.DrawSphere method draws a solid sphere at a specified position with a specified radius, whereas the Gizmos.DrawWireSphere method draws a wireframe sphere instead.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        // Set the color of Gizmos to green
        Gizmos.color = Color.green;

        Gizmos.DrawSphere(transform.position, 1.5f);
    }
}


Code language: C# (cs)

The example above draws a solid sphere with a radius of 1.5 units positioned at the center of the game object.

A 2D view of the solid sphere drawn by the DrawSphere method.
2D view
A 3D view of the solid sphere drawn by the DrawSphere method.
3D view
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        // Set the color of Gizmos to green
        Gizmos.color = Color.green;

        Gizmos.DrawWireSphere(transform.position, 1.5f);
    }
}


Code language: C# (cs)

The example above draws a wireframe sphere with a radius of 1.5 units positioned at the center of the game object.

A 2D view of the wireframe sphere drawn by the DrawWireSphere method.
2D view
A 3D view of the wireframe sphere drawn by the DrawWireSphere method.
3D view

How To Draw A Debug Cube With Gizmos In Unity

Gizmos.DrawCube(centerPosition, radius);
Gizmos.DrawWireCube(centerPosition, radius);
Code language: C# (cs)

There are 2 methods for drawing a debug sphere onto the Scene view in Unity Editor.

The Gizmos.DrawCube method draws a solid cube at a specified position with a specified size, whereas the Gizmos.DrawWireCube method draws a wireframe cube instead.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        // Set the color of Gizmos to green
        Gizmos.color = Color.green;

        Gizmos.DrawCube(transform.position, new Vector3(2f, 1f, 1f));
    }
}


Code language: C# (cs)

The example above draws a solid cube with a size of 2x1x1 positioned at the center of the game object.

A 2D view of the solid cube drawn by the DrawCube method.
2D view
A 3D view of the solid cube drawn by the DrawWireCube method.
3D view
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class VisualAid : MonoBehaviour
{
    private void OnDrawGizmos()
    {
        // Set the color of Gizmos to green
        Gizmos.color = Color.green;

        Gizmos.DrawWireCube(transform.position, new Vector3(2f, 1f, 1f));
    }
}


Code language: C# (cs)

The example above draws a wireframe cube with a size of 2x1x1 positioned at the center of the game object.

A 2D view of the wireframe sphere drawn by the DrawWireSphere method.
2D view
A 3D view of the wireframe sphere drawn by the DrawWireSphere method.
3D view

Conclusion

Knowing how to use the debugging tools provided by Unity can help you out quite a lot. The Gismoz class is one of those tools you’ll find yourself be using often. Especially, if you deal with Raycasting or object collisions a lot.

I hope you’ve learned something new today.

Cheers!

Hi, I'm Pavee. I'm a software developer, an aspiring pixel artist, and the owner of Game Dev Planet. I love learning new things and have a passion for game development.

Similar Posts