As you may recall, Gizmos are visual aids used to represent magnitudes related to an object’s fields and properties. They are primarily used in the editor to assist during the development phase. For example, it’s always easier to visualize the shooting range of a tank in a game if that range is represented as a circle around the tank. Another example is when you edit the shape of a Collider; what is displayed on the screen is its Gizmo.
In Unity, any MonoBehaviour can implement two methods for drawing Gizmos: OnDrawGizmos() and OnDrawGizmosSelected(). The first one draws Gizmos at all times, while the second only does so when the GameObject containing the script is selected. It's important to note a significant caveat about OnDrawGizmos(): it is not called if its script is minimized in the inspector.
 |
| The script SeekSteeringBehavior is minimized. |
In theory, you can interact with the Gizmos drawn in OnDrawGizmos(), but not with those drawn in OnDrawGizmosSelected(). Practically, knowledge of how to interact with Gizmos was lost a long time ago. In the past, it was possible to click on them, but this functionality seems to have disappeared around Unity version 2.5. The mention in Unity’s OnDrawGizmos() documentation about being able to click on Gizmos seems more like a sign that the documentation hasn’t been fully updated.
In any case, Unity’s editor is full of Gizmos you can interact with, but that’s because they include an additional element: Handles. In this article, we’ll focus on Gizmos as a means of passive visual representation, leaving the explanation of interactive Gizmos via Handles for a future article. To simplify further, I’ll refer only to OnDrawGizmos(); the other method is identical, but is only called when its GameObject is selected in the hierarchy.
The OnDrawGizmos() method is only called in the editor during an update or when the focus is on the Scene View. We should avoid overloading this method with complex calculations, as we could degrade the editor’s performance. Although it’s only called from the editor, we could implement it as-is, knowing that Gizmos won’t appear in the final compiled game. However, I prefer to wrap the method’s implementation in #if UNITY_EDITOR ... #endif. It’s an old habit. While redundant when using only Gizmos, this guard becomes necessary if you include Handles in the method, as we’ll see in a later article.
Let’s assume we’re designing an agent that interposes itself between two others (Agent-A and Agent-B). The movement algorithm for the interposing agent isn’t relevant here, but its effect will be to measure a vector between Agents A and B and position the interposing agent at the midpoint. In such a case, we’d want to draw this midpoint on the screen to verify that the interposing agent is actually heading toward it. This is an ideal use case for Gizmos.
The MonoBehaviour responsible for calculating this midpoint also implements the OnDrawGizmos() method with the following code:
 |
| Example of OnDrawGizmos() implementation. |
Let’s analyze it line by line to understand how to draw any figure within this method.
Lines 127–128: These lines prevent the method from executing if we’ve decided to make the Gizmos invisible by setting the predictedPositionMarkerVisible variable to false, or if _predictedPositionMarker is null. This variable refers to the implementation of the interposing agent. For reasons not covered here, when the MonoBehaviour starts, I create a GameObject linked to _predictedPositionMarker. As the script calculates the midpoints between Agents A and B, it positions this GameObject at those midpoints. For our purposes, _predictedPositionMarker is a GameObject that acts as a marker for the position where the interposing agent should be. If it’s null, there’s nothing to draw.
Line 130: This line sets the color used for drawing all Gizmos until a different value is assigned to Gizmos.color.
Lines 131–133: Here, we use the Gizmos.DrawLine() call to draw a line between Agent A’s position and the marker.
Line 134: This line changes the drawing color to magenta (purple) to draw a circle at the marker’s position using Gizmos.DrawSphere(). This method draws a filled circle. If we only wanted an outline, we could use Gizmos.DrawWireSphere().
Lines 137–139: These lines use Gizmos.DrawLine() to draw another line (with its own color) between Agent B’s position and the marker.
The result can be seen when running the game from the editor:
 |
| Gizmos drawn when running the game from the editor. |
Agents A and B are colored blue and red, respectively, while the interposing agent is green. The Gizmos are the blue and red lines and the purple circle.
And that’s it! Using these primitives, along with the rest of the module’s Gizmos offerings, we can draw any shape we want. These shapes will update in the editor when we change the fields they depend on in the inspector or, if tied to variables, as those variables change while running the game in the editor.
One last note: I often use booleans like predictedPositionMarkerVisible to decide which specific scripts can draw their Gizmos. However, Unity’s editor allows you to disable the drawing of all Gizmos. To do this, just click the button on the far right of the toolbar at the top of the Scene tab.
 |
| Button to toggle Gizmo visibility. |
I recommend ensuring this button is enabled. The internet is full of posts from people asking why their Gizmos aren’t being drawn... only to realize they had inadvertently disabled this button.
