Visual Debugging with Gizmos

We’re going to keep this post short and sweet, cause that’s what I do here…

A few weeks ago, or maybe months ago, I rediscovered Unity’s gizmos as a fantastic visual debugging tool. It might be a little bit of a niche use case for some, but when you need gizmos they can be super useful.

Now there’s a ton that you can do with gizmos (and handles) in making custom tools. I’m not going there. For this post, we’re keeping it simple and using Gizmos just for debugging and visualizations with the big goal of adding one more easy-to-use tool to your toolbox.

Simple Example

Let’s look at a simple example. Someone on my Discord was creating a power-up for their 2D platformer. When the power-up was collected or used the player would do a zigzag jump upward. The path of the jump was to be predetermined by the position of some empty children objects. Using empty children objects is easy, but often all we really need is a Vector3 position. The empty child is just a stand-in that can be easily moved and visualized in the sceneview.

But! In the case of the zigzag jump, gizmos could remove the need for those empty objects cleaning up the hierarchy while still providing a visualization of those positions. So let’s take a look at how that would work.

First, we need to create a list of Vector3’s - these will be positions relative to the player. Then we need to add the function OnDrawGizmos(). In the function we can check if the list is empty if it’s not then we can draw our gizmos.

To start drawing, we first need to set a color for the gizmos.

Side note: It’s important here to know that you are setting the color for all the gizmos that will be drawn after setting the color or until the color is set to a different value. You are not setting the color for a particular gizmo. It’s a bit different than other Unity objects, but it’s pretty easy all the same.

Make sure the Show gizmos button is toggled on

With the color set we can then iterate through the points in our list and call Gizmo.DrawSphere(). This function takes in a position, which is in world space, as well as the radius of the sphere to be drawn.

And that’s it.

If we jump back into Unity, making sure the component is added to an object, we can then set values in our list and the gizmos will be drawn in realtime as we adjust the Vector3 values.

If you’re not seeing the gizmos make sure you are looking at the scene view, gizmos will not be drawn in the game view, and that the “show gizmos” button is toggled on.

Adding Lines

Okay, let’s take a it a step further. Let’s imagine you want to now want to add a line to the path to make an even better visualization. Which could have the added bonus of making sure you points are in the correct order!

Now we could definitely do this all in one for loop, but for the sake of clarity I’m going to add a second loop.

However, before the start of the second loop, I’m going to change the color of the gizmos to blue.

In our case, we need a bit of special handling as we don’t have a starting point in the list. So if the index is zero, we’re going to draw the line from “this” object to the first point. If the index isn’t zero, we’ll draw from the previous point to the current point.

Once again, noting that our points are in local space and we are drawing in world space so we have to add the position of “this” object to each point.

Quick style comment, if you don’t like the lines showing through the spheres or in reality being drawn on top of the spheres, you can move the line drawing code above the sphere drawing code - this will cause the lines to get drawn first making things look a bit nicer.

Drawing When Selected

If you’d like your gizmos to only be drawn when the object is selected you can put all of your code into OnDrawGizmosSelected() instead of OnDrawGizmos().

Or, if you want to get wild and crazy you could put the line drawing code in OnDrawGizmosSelected() and leave the sphere drawing code in OnDrawGizmos().

Options. You’ve ‘em.

More Things to Draw

There are several more types of gizmos that can be drawn such as rays, icons, wire spheres, and all kinds of other good stuff. Check out the Unity documentation for more details. Each gizmo has its own use, but the big-picture functionality is largely the same. Add one of the DrawGizmo functions, set the color, and then draw your gizmo with whatever logic you might need.

Personally, I’ve found gizmos immensely useful with data generated at runtime. If you look, you’ll find gizmos used in all kinds of 3rd party assets or tools to help debug or find the correct settings for a particular use case.