README.md

Fast editor debugging and gizmo utilities for Unity.
Uses instanced rendering to draw shapes efficiently.

Note

Unity 2022.2+ (all features) - Version 3.0.0 and above.
2019.4+ No jobs and burst support, older API.

Should support all render pipelines.
Supports drawing from jobs and burst. This package depends on Burst and Mathematics.
All shapes are wireframe. There is currently no support for solid shapes planned.

vertx_debugging.mp4

Usage

Shape drawing

Example // Draw a sphere with the specified color. D.raw(new Shape.Sphere(position, radius), color, duration); // Draw green sphere if nothing was hit, // or draw a red sphere if something was. D.raw(new Shape.Sphere(position, radius), hit, duration); // Casts draw in green, with red where hits were detected if no color is provided. // Cast color and hit color can be overrided manually. D.raw(new Shape.SphereCastAll(position, direction, radius, hits, hitCount, 10), duration); Available contexts You can call these methods from most places, Update, LateUpdate, FixedUpdate, OnDrawGizmos, and with ExecuteAlways/ExecuteInEditMode. If drawn from a gizmo context, duration parameters will be ignored. Gizmos.matrix works, Gizmos.color is unsupported. Gizmos are not pickable. Code stripping Calls to these methods are stripped when building. You do not have to remove code or use defines. If your code spans many statements, only the method call will be stripped.

Drawing Physics and Physics2D operations

Example You can replace calls to Physics and Physics2D methods with DrawPhysics and DrawPhysics2D to simply draw the results of a physics operation. int count = DrawPhysics.RaycastNonAlloc(r, results, distance); Use DrawPhysicsSettings.SetDuration or Duration to override the length of time the casts draw for. You will need to reset this value manually. Calls to Duration cannot be stripped, I would recommend using SetDuration if this is important to you. Code stripping The drawing within these methods will be stripped, and the original method is attempted to be inlined, but this is not consistent. A single method call doesn't matter when compared to a physics operation, but you can completely strip these calls by instead declaring: #if UNITY_EDITOR using Physics = Vertx.Debugging.DrawPhysics; #endif

Note

If you find you have rendering issues like upside-down depth testing, or artifacts in the game view: This is a Unity bug.
You can disable Depth Write and Depth Test in the problematic view using the settings in Project Settings > Vertx > Debugging.
If you're on a version of Unity where the settings UI doesn't work, it's another Unity bug, thanks Unity!

Shapes

Drawable shapes and casts are contained within the Shape class. You can statically import the class if you use them often:

using static Vertx.Debugging.Shape;

Shape list

General

Name	Description
Text	A label in the scene at the provided position. (Text respects 3D gizmo fade distance)
ScreenText	A label in the top left of the view. Draws using an Overlay in the Scene view when available.

3D

Shapes

Name	Description
Sphere Hemisphere Box Capsule Cylinder	3D shapes.
Arc	An arc (using Angle1 to define its length).
Annulus	An annulus or annulus sector.
SurfacePoint	A ray with a circle to indicate the surface.
Point	A point without a specified direction.
Axis	An XYZ direction gizmo.
Arrow ArrowStrip	An arrow vector, or a collection of points forming an arrow.
Line LineStrip	A line, or a collection of points that make up a line.
DashedLine	A dashed line.
HalfArrow	An arrow with only one side of its head. Commonly used to represent the HalfEdge data structure.
Arrow2DFromNormal	An 2D arrow aligned in 3D space using a normal vector perpendicular to the direction.
Plane	A 3D rect drawn around a point on the plane.
Cone	A cone (with adjustable end radius, making a conical frustum).
Pyramid	A pyramid.
Frustum	A camera frustum.
FieldOfView	A 3D field of view, a spherical sector.
MeshNormals	The normals of a mesh.
Catenary	Similar to cable hanging between two points.
Ray	A line from a position and a direction vector.
Ray (Built-in)	Fallback to Ray.
Vector3 (Built-in)	Fallback to Point.
RaycastHit (Built-in)	Fallback to SurfacePoint.
Bounds (Built-in)	Fallback to Box.
Collider (Built-in)	Fallback to the correct shape matching the collider type (primitive colliders only).

Casts

Name	Description
Raycast Linecast SphereCast BoxCast CapsuleCast	Using similar parameters as Physics.Raycast Physics.Linecast Physics.SphereCast Physics.BoxCast Physics.CapsuleCast with an optional RaycastHit result.
RaycastAll SphereCastAll BoxCastAll CapsuleCastAll	RaycastHit[] results using similar parameters as Physics.RaycastAll Physics.SphereCastAll Physics.BoxCastAll Physics.CapsuleCastAll

2D

Shapes

Name	Description
Circle2D Box2D Area2D Capsule2D Rect	2D shapes.
Arc2D	An arc (using Angle1 to define its length).
Point2D	A point without a specified direction.
Axis2D	An XY direction gizmo.
Arrow2D ArrowStrip2D	An arrow vector, or a collection of points forming an arrow.
Ray2D	A line from a position and a direction vector.
Spiral2D	A spiral, useful for visualising rotation on wheels.
Vector2 (Built-in)	Fallback to Point2D.
RaycastHit2D (Built-in)	Fallback to Ray.
Rect (Built-in)	Fallback to Box2D.

Casts

Name	Description
Raycast2D Linecast2D CircleCast2D BoxCast2D CapsuleCast2D	Using similar parameters as Physics2D.Raycast Physics2D.Linecast Physics2D.SphereCast Physics2D.BoxCast Physics2D.CapsuleCast with an optional RaycastHit2D result.
RaycastAll2D CircleCastAll2D BoxCastAll2D CapsuleCastAll2D	RaycastHit2D[] results using similar parameters as Physics2D.RaycastAll Physics2D.SphereCastAll Physics2D.BoxCastAll Physics2D.CapsuleCastAll

Authoring new shapes

Extensions Use Assembly Definition References to add a class to the runtime assembly. The Shape class is partial. You can add IDrawable or IDrawableCast structs to the class, which will be compatible with D.raw<T>(T shape). Use the UnmanagedCommandBuilder Append functions to create your own shapes, or combine other shapes by directly calling their Draw functions. Warning Don't recursively call D.raw from inside of IDrawable/IDrawableCast.Draw, as it will cause issues with FixedUpdate drawing.

Components

Components to draw physics events and common object attributes.

Component list

Name	Description
Debug Transform	Draws up, right, forward axes of a Transform.
Debug Renderer Bounds	Draws the bounds of a Renderer.
Debug Collider Bounds	Draws the bounds of a Collider or Collider2D.
Debug Collision Events	Draws OnCollisionEnter, Stay and Exit events.
Debug Trigger Events	Draws OnTriggerEnter, Stay and Exit events.
Debug Mesh Normals	Draws normals for a (read/write) Mesh.

Drawing from jobs

Drawing from jobs is supported (parallel, and bursted).
Note that drawing from jobs scheduled from a fixed timestep context like FixedUpdate or FixedStepSimulationSystemGroup is not time-adjusted which may cause flickering based on the framerate, you must manually call DrawPhysicsUtility.GetFixedFrameJobDuration to get a time-adjusted duration, and pass it to D.raw to draw shapes correctly in this context.
Calls that are not jobified

Installation

Add the OpenUPM registry Open Edit/Project Settings/Package Manager Add a new Scoped Registry (or edit the existing OpenUPM entry): Name: OpenUPM URL: https://package.openupm.com/ Scope(s): com.vertx Save Add the package Open the Package Manager via Window/Package Manager. Select the + from the top left of the window. Select Add package by Name or Add package from Git URL. Enter com.vertx.debugging. Select Add. If Burst is added for the first time or its version is changed you will need to restart Unity.

Footnotes

1. The helper class Angle is used to define angles, author it with the static methods like Angle.FromDegrees. ↩ ↩²