README-ZH.md

Unity-DebugX

Warning

The translation of the Readme is not completely finished

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

一个多功能、可扩展且高性能的 Unity Gizmos 绘图工具。 它既可以在编辑器中运行，也可以在 Build 中运行，绘制可以在 OnDrawGizmos 和 Update 中进行. 支持 HDRP、URP 和 BRP，但在 BRP 中不支持在 OnDrawGizmos 回调中进行绘制。

语法：

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

目录

• 安装
• 基础API
• 设置
• API Extension
• Loading Static Assets
• Define Symbols

Installation

版本的语义 - Открыть

Unity-软件包

支持以 Unity 模块的形式安装，只需将 Git-URL 复制到 PackageManager 或 Packages/manifest.json中. 复制此 Git-URL 以安装最新的工作版本:

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

作为源代码

该包也可以直接复制到项目文件夹中。

基础 API

绘制预定义 Gizmo 的通用语法：

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

预定义的 Gizmo 包括各种图元、线条、点和文本。以下是一些 Gizmo 的示例：

// 绘制一条普通线条，类似于 Debug.DrawLine(...)。
// 线条将显示一秒钟，并且为红色。
DebugX.Draw(1, Color.red).Line(startPoint, endPoint);

// 绘制一个立方体，但仅显示一帧，并且为黄色。
DebugX.Draw(Color.yellow).Cube(center, rotation, size);

// 绘制一个球体。
DebugX.Draw(Color.yellow).Cube(center, radius);

// 绘制一个点，点的大小为屏幕空间大小。
DebugX.Draw(Color.yellow).Dot(startPoint, endPoint);

// 绘制文本。文本也可以显示指定的时间。
DebugX.Draw(1, Color.red).Text(center, text);
// 使用 DebugXTextSettings 进行高级显示设置。
DebugX.Draw(Color.yellow).Text(center, text, DebugXTextSettings.Default.SetBackgroundColor(Color.black));

如果预定义的图元不够用，可以使用以下方法绘制自定义网格和材质：

// 使用 lit 材质绘制任何网格。不使用 GPU 实例化。
DebugX.Draw(...).Mesh(mesh, pos, rot, sc);
// UnlitMesh - 使用 unlit 材质的网格
// WireMesh - 使用线框材质的网格

// 使用 lit 材质绘制静态网格。使用 GPU 实例化。
DebugX.Draw(...).Mesh<IStaticMesh>(pos, rot, sc);
// UnlitMesh<IStaticMesh> - 使用 unlit 材质的网格
// WireMesh<IStaticMesh> - 使用线框材质的网格

// 使用静态材质绘制静态网格。使用 GPU 实例化。
DebugX.Draw(...).Mesh<IStaticMesh, IStaticMat>(pos, rot, sc);

为了优化绘制，使用静态数据：

// 静态网格。使用 GPU 实例化绘制时必须。
public struct SomeMesh : IStaticMesh
{
    public Mesh GetMesh() => StaticStorage.SomeMesh;
}

// 静态材质。
public struct SomeMesh : IStaticMesh
{
    // 控制渲染顺序。
    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.

设置

设置窗口位于 "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.