Unity-DebugX

Readme Languages:
Русский	English	中文

A multifunctional, extensible, and high-performance Gizmos drawing utility for Unity. It works both in the editor and in the build, and drawing can be done both in OnDrawGizmos and in Update. HDRP, URP, and BRP are supported, but drawing in the OnDrawGizmos callbacks is not supported in BRP.

Syntax:

DebugX.Draw(duration, color).*Gizmo Function*(...);

Table of Contents

• Installation
• Basic API
• Settings
• API Extension
• Loading Static Assets
• Define Symbols

Installation

Versioning semantics - Открыть

Unity-Package

Supports installation as a Unity module. Copy the Git-URL into PackageManager or into Packages/manifest.json. Copy this Git-URL to install the latest working version:

https://github.com/DCFApixels/Unity-DebugX.git

Source Code

The Package can also be directly copied into the project folder.

Basic API

The general syntax for drawing predefined Gizmos:

DebugX.Draw(duration, color).*Gizmo Function*(...);

Among the predefined Gizmos, there are various primitives, lines, points, and text. Examples of some Gizmos:

// Draws a regular line similar to Debug.DrawLine(...).
// The line will be displayed for one second and will be red.
DebugX.Draw(1, Color.red).Line(startPoint, endPoint);

// Draws a cube, but for just one frame and in yellow.
DebugX.Draw(Color.yellow).Cube(center, rotation, size);

// Draws a sphere.
DebugX.Draw(Color.yellow).Cube(center, radius);

// Draws a point. The point has a screen space size. 
DebugX.Draw(Color.yellow).Dot(startPoint, endPoint);

// Draws text. The text can also be displayed for the specified time.
DebugX.Draw(1, Color.red).Text(center, text);
// For advanced display settings, use DebugXTextSettings.
DebugX.Draw(Color.yellow).Text(center, text, DebugXTextSettings.Default.SetBackgroundColor(Color.black));

In case the predefined primitives are not enough, there are methods for drawing custom meshes and materials:

//Рисования любого меша lit материалом. Без GPU instancing. 
DebugX.Draw(...).Mesh(mesh, pos, rot, sc);
//UnlitMesh - меш с unlit материалом
//WireMesh - меш с wireframe материалом

//Рисования статического меша lit материалом. В режиме GPU instancing. 
DebugX.Draw(...).Mesh<IStaticMesh>(pos, rot, sc);
//UnlitMesh<IStaticMesh> - меш с unlit материалом
//WireMesh<IStaticMesh> - меш с wireframe материалом

//Рисования статического меша статическим материалом. В режиме GPU instancing. 
DebugX.Draw(...).Mesh<IStaticMesh, IStaticMat>(pos, rot, sc);

Static data is used to optimize the rendering:

// Static mesh. Required for drawing with GPU instancing.
public struct SomeMesh : IStaticMesh
{
    public Mesh GetMesh() => StaticStorage.SomeMesh;
}

// Static material.
public struct SomeMesh : IStaticMesh
{
    // Control the drawing order.
    public int GetExecuteOrder() => 100;
    public Mesh GetMaterial() => StaticStorage.SomeMaterial;
} 

In the example, StaticStorage is a conditional implementation of a static asset storage. Since in Unity static data cannot be filled through the inspector, the solution to this problem is described in the section Loading Static Assets.

Settings

Settings window "Tools -> DebugX -> Settings":

API Extension

The simplest option is to create an extension method that combines predefined gizmos, for example:

public static class SomeGizmoExtensions
{
    public static DebugX.DrawHandler Distance(this DebugX.DrawHandler self, Vector3 start, Vector3 end)
    {
        // Draw a line.
        self.Line(start, end);
        // Draw text in the middle of the line showing the length of the line.
        self.Text(Vector3.Lerp(start, end, 0.5f), Vector3.Distance(start, end), DebugXTextSettings.Default.SetAnchor(TextAnchor.UpperCenter));
        // for support Method Chaining syntax.
        return self;
    }
}

You can also use the Mesh methods to create drawing methods for other primitives.

Extended implementation of Gizmo, in case the built-in drawing methods are not enough:

public readonly struct SomeGizmo : IGizmo<SomeGizmo>
{
    // Gizmo Data.

    public SomeGizmo(/*...*/)
    {
        // Fill the data.
    } 
    
    public IGizmoRenderer<SomeGizmo> RegisterNewRenderer() => new Renderer();
    private class Renderer : IGizmoRenderer<SomeGizmo>
    {
        // Control the execution order of renderers.
        public int ExecuteOrder => 0; // can use default(SomeMat).GetExecutionOrder();
        // Flag for the system about optimization.
        // If the drawing or preparation method depends on the current camera, set to false, otherwise true.
        // If unsure, choose false.
        public bool IsStaticRender => false;

        // Prepare data before rendering, you can perform additional calculations or schedule a Job here.
        public void Prepare(Camera camera, GizmosList<SomeGizmo> list) 
        {
            foreach (var item in list)
            {
                //... 
            }
        } 

        // Render, you can directly use the graphics API or add a command to CommandBuffer here.
        public void Render(Camera camera, GizmosList<SomeGizmo> list, CommandBuffer cb)
        {
            foreach (var item in list)
            {
                //... 
            }
        }
    }
}

// Create an extension method. 
public static class SomeGizmoExtensions
{
    public static DebugX.DrawHandler SomeGizmo(this DebugX.DrawHandler self, /*...*/) 
    {
        self.Gizmo(new SomeGizmo(/*...*/);
        return self;
    }
}

Loading Static Assets

Для загрузки имеется утилита DebugXUtility.LoadStaticData(...);.

1. First, create a storage for the assets.

public readonly struct SomeAssets
{
    public readonly Mesh SomeMesh;
    public readonly Material SomeMaterial;
} 

2. Next, create a prefab with a list of assets. Each child GameObject of the prefab is treated as one asset, and its name must match the field where the asset will be loaded. To load meshes, add a MeshFilter component to the GameObject with a reference to the desired mesh. To load a material, add any component inherited from Renderer with the specified material. The prefab itself must be located in the Resources folder.

3. Once the repository and prefab list are prepared, assets can be uploaded.

SomeAssets assets = DebugXUtility.LoadStaticData(new SomeAssets(), "SomeAssets");
// Done.

An example of how to work with this utility can be found in the source code in the file DebugXAssets.cs.

Define Symbols

All Define Symbols can be changed in the settings window

• DEBUGX_DISABLE_INBUILD - By default, Gizmos will be drawn in the project build. This define disables drawing.
• DEBUGX_ENABLE_PHYSICS2D - Enable Physics2D Gizmos.
• DEBUGX_ENABLE_PHYSICS3D - Enable Physics3D Gizmos.