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. https://user-images.githubusercontent.com/21963717/194199755-a63d8ebc-0cc7-4268-9316-78f7d4fbea1a.mp4 ## Usage

Shape drawing

#### Example ```csharp // 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. ```csharp 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: ```csharp #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: ```csharp 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](https://docs.unity3d.com/Manual/overlays.html) in the Scene view when available. | ### 3D #### Shapes | Name | Description | |--------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | `Sphere`
`Hemisphere`
`Box`
`Capsule`
`Cylinder` | 3D shapes. | | `Arc` | An arc (using `Angle`[^1] 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 `Angle`[^1] 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` | [^1]: The helper class `Angle` is used to define angles, author it with the static methods like `Angle.FromDegrees`.

Authoring new shapes

### Extensions 1. Use Assembly Definition References to add a class to the runtime assembly. 2. The `Shape` class is partial. You can add `IDrawable` or `IDrawableCast` structs to the class, which will be compatible with `D.raw(T shape)`. 3. 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 [![openupm](https://camo.githubusercontent.com/5cbf997a0391a06b1f0d8a0d8bc1aff7821080a5bff707203b09f6ae3b2391dc/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f636f6d2e76657274782e646562756767696e673f6c6162656c3d6f70656e75706d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d)](https://openupm.com/packages/com.vertx.debugging/)

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