mirror of
https://github.com/DCFApixels/Unity-DebugX.git
synced 2025-09-18 01:54:37 +08:00
Compare commits
3 Commits
eb1c4ebf91
...
9864d41dee
| Author | SHA1 | Date | |
|---|---|---|---|
|
9864d41dee | ||
|
|
f03bd355f6 | ||
|
|
2e565c9012 |
256
README-RU.md
Normal file
256
README-RU.md
Normal file
@ -0,0 +1,256 @@
|
||||
|
||||
|
||||
|
||||
<p align="center">
|
||||
<img alt="Version" src="https://img.shields.io/github/package-json/v/DCFApixels/Unity-DebugX?style=for-the-badge&color=ff3530">
|
||||
<img alt="License" src="https://img.shields.io/github/license/DCFApixels/Unity-DebugX?color=ff3530&style=for-the-badge">
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
# Unity-DebugX
|
||||
|
||||
<table>
|
||||
<tr></tr>
|
||||
<tr>
|
||||
<td colspan="3">Readme Languages:</td>
|
||||
</tr>
|
||||
<tr></tr>
|
||||
<tr>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX/blob/main/README-RU.md">
|
||||
<img src="https://github.com/user-attachments/assets/3c699094-f8e6-471d-a7c1-6d2e9530e721"></br>
|
||||
<span>Русский</span>
|
||||
</a>
|
||||
</td>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX">
|
||||
<img src="https://github.com/user-attachments/assets/30528cb5-f38e-49f0-b23e-d001844ae930"></br>
|
||||
<span>English</span>
|
||||
</a>
|
||||
</td>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX/blob/main/README-ZH.md">
|
||||
<img src="https://github.com/user-attachments/assets/8e598a9a-826c-4a1f-b842-0c56301d2927"></br>
|
||||
<span>中文</span>
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</br>
|
||||
|
||||
Многофункциональная, расширяемая и производительная утилита рисования Gizmos для Unity. Работает как в редакторе так и в сборке, а рисовать можно как в `OnDrawGizmos` так и в `Update`. Поддерживается HDRP, URP и BRP, но в BRP не поддерживается отрисовка в `OnDrawGizmos`.
|
||||
|
||||
Синтаксис:
|
||||
```c#
|
||||
DebugX.Draw(duration, color).*Gizmo Function*(...);
|
||||
```
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
## Оглавление
|
||||
- [Установка](#установка)
|
||||
- [Базовый API](#api)
|
||||
- [Настройки](#настройки)
|
||||
- [Расширение API](#кастомный-gizmo)
|
||||
- [Загрузка статических ассетов](#загрузка-статических-ассетов)
|
||||
- [Define Symbols](#define-symbols)
|
||||
|
||||
<br>
|
||||
|
||||
# Установка
|
||||
Семантика версионирования - [Открыть](https://gist.github.com/DCFApixels/e53281d4628b19fe5278f3e77a7da9e8#file-dcfapixels_versioning_ru-md)
|
||||
### Unity-Package
|
||||
Поддерживается установка в виде Unity-модуля, достаточно скопировать Git-URL [в PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html) или в `Packages/manifest.json`. Скопируйте этот Git-URL для установки актуальной рабочей версии:
|
||||
```
|
||||
https://github.com/DCFApixels/Unity-DebugX
|
||||
```
|
||||
### 作为源代码
|
||||
Пакет так же может быть напрямую скопирован в папку проекта.
|
||||
|
||||
</br>
|
||||
|
||||
# Базовый API
|
||||
|
||||
Общий синтаксис рисования заготовленных Gizmo:
|
||||
```c#
|
||||
DebugX.Draw(duration, color).*Gizmo Function*(...);
|
||||
```
|
||||
</br>
|
||||
|
||||
Среди заготовленных Gizmo есть разные вариации примитивов, линий, точек и текст. Пример некоторых Gizmo:
|
||||
```c#
|
||||
// Рисует обычную линию аналогично Debug.DrawLine(...).
|
||||
// Показываться линия будет в течении секунды и красного цвета.
|
||||
DebugX.Draw(1, Color.red).Line(startPoint, endPoint);
|
||||
```
|
||||
```c#
|
||||
// Рисует куб, но всего один кадр и желтого цвета.
|
||||
DebugX.Draw(Color.yellow).Cube(center, rotation, size);
|
||||
```
|
||||
```c#
|
||||
// Рисует сферу.
|
||||
DebugX.Draw(Color.yellow).Cube(center, radius);
|
||||
```
|
||||
```c#
|
||||
// Рисует точку, точка имеет screen space размер.
|
||||
DebugX.Draw(Color.yellow).Dot(startPoint, endPoint);
|
||||
```
|
||||
```c#
|
||||
// Рисует текст. Текст так же может показываться в течении заданного времени.
|
||||
DebugX.Draw(1, Color.red).Text(center, text);
|
||||
// Для расширенной настройки отображения используется DebugXTextSettings.
|
||||
DebugX.Draw(Color.yellow).Text(center, text, DebugXTextSettings.Default.SetBackgroundColor(Color.black));
|
||||
```
|
||||
</br>
|
||||
|
||||
|
||||
На случай если не хватает заготовленных примитивов есть методы для рисования кастомных меша и материала:
|
||||
```c#
|
||||
//Рисования любого меша lit материалом. Без GPU instancing.
|
||||
DebugX.Draw(...).Mesh(mesh, pos, rot, sc);
|
||||
//UnlitMesh - меш с unlit материалом
|
||||
//WireMesh - меш с wireframe материалом
|
||||
```
|
||||
```c#
|
||||
//Рисования статического меша lit материалом. В режиме GPU instancing.
|
||||
DebugX.Draw(...).Mesh<IStaticMesh>(pos, rot, sc);
|
||||
//UnlitMesh<IStaticMesh> - меш с unlit материалом
|
||||
//WireMesh<IStaticMesh> - меш с wireframe материалом
|
||||
```
|
||||
```c#
|
||||
//Рисования статического меша статическим материалом. В режиме GPU instancing.
|
||||
DebugX.Draw(...).Mesh<IStaticMesh, IStaticMat>(pos, rot, sc);
|
||||
```
|
||||
</br>
|
||||
|
||||
Для оптимизации отрисовки используются статические данные:
|
||||
```c#
|
||||
// Статический меш. Обязателен для отрисовки с GPU instancing.
|
||||
public struct SomeMesh : IStaticMesh
|
||||
{
|
||||
public Mesh GetMesh() => StaticStorage.SomeMesh;
|
||||
}
|
||||
```
|
||||
```c#
|
||||
// Статический материал.
|
||||
public struct SomeMesh : IStaticMesh
|
||||
{
|
||||
// Контроль порядка выполнения отрисовки.
|
||||
public int GetExecuteOrder() => 100;
|
||||
public Mesh GetMaterial() => StaticStorage.SomeMaterial;
|
||||
}
|
||||
```
|
||||
> В примере StaticStorage это условная реализация статического хранилища ассетов. Так как в Unity статические данные нельзя заполнять через инспектор, решение этой проблемы описано в главе [Загрузка статических ассетов](#загрузка-статических-ассетов).
|
||||
|
||||
<br>
|
||||
|
||||
# Настройки
|
||||
Окно настроек "Tools -> DebugX -> Settings":
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
# Расширение API
|
||||
Самый простой вариант это создание метода расширения который комбинирует заготовленные гизмо, например:
|
||||
```c#
|
||||
public static class SomeGizmoExtensions
|
||||
{
|
||||
public static DebugX.DrawHandler Distance(this DebugX.DrawHandler self, Vector3 start, Vector3 end)
|
||||
{
|
||||
// Рисуем линию.
|
||||
self.Line(start, end);
|
||||
// Рисуем текст посреди линии который показывает длину линии.
|
||||
self.Text(Vector3.Lerp(start, end, 0.5f), Vector3.Distance(start, end), DebugXTextSettings.Default.SetAnchor(TextAnchor.UpperCenter));
|
||||
// для поддержки Method Chaining синтаксиса.
|
||||
return self;
|
||||
}
|
||||
}
|
||||
```
|
||||
> Так же можно использовать методы `Mesh` для создания методов рисования других примитивов.
|
||||
|
||||
Расширенная реализация Gizmo, на случай нехватки встроенных методов отрисовки:
|
||||
```c#
|
||||
public readonly struct SomeGizmo : IGizmo<SomeGizmo>
|
||||
{
|
||||
// Данные.
|
||||
|
||||
public SomeGizmo(/*...*/)
|
||||
{
|
||||
// Заполнение данных.
|
||||
}
|
||||
|
||||
public IGizmoRenderer<SomeGizmo> RegisterNewRenderer() => new Renderer();
|
||||
private class Renderer : IGizmoRenderer<SomeGizmo>
|
||||
{
|
||||
// Контроль порядка выполнения рендереров.
|
||||
public int ExecuteOrder => 0; //можно использовать default(SomeMat).GetExecutuonOrder();
|
||||
// Флаг системе о способе оптимизации.
|
||||
// Если метод рисовки или подготовки зависят от текущей камеры, то false，иначе true.
|
||||
// Если не уверены то выбирайте false.
|
||||
public bool IsStaticRender => false;
|
||||
|
||||
// Подготовка данных перед рендером, тут можно выполнить дополнительные расчеты или запланировать Job.
|
||||
public void Prepare(Camera camera, GizmosList<SomeGizmo> list)
|
||||
{
|
||||
foreach (var item in list)
|
||||
{
|
||||
//...
|
||||
}
|
||||
}
|
||||
|
||||
// Рендер, тут можно напрямую воспользоваться графическим API или добавить команду в CommandBuffer.
|
||||
public void Render(Camera camera, GizmosList<SomeGizmo> list, CommandBuffer cb)
|
||||
{
|
||||
foreach (var item in list)
|
||||
{
|
||||
//...
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
```c#
|
||||
// Создание метода расширения.
|
||||
public static class SomeGizmoExtensions
|
||||
{
|
||||
public static DebugX.DrawHandler SomeGizmo(this DebugX.DrawHandler self, /*...*/)
|
||||
{
|
||||
self.Gizmo(new SomeGizmo(/*...*/);
|
||||
return self;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
# Загрузка статических ассетов
|
||||
Для загрузки имеется утилита `DebugXUtility.LoadStaticData(...);`.
|
||||
|
||||
1) Сначала создаем хранилище для ассетов.
|
||||
```c#
|
||||
public readonly struct SomeAssets
|
||||
{
|
||||
public readonly Mesh SomeMesh;
|
||||
public readonly Material SomeMaterial;
|
||||
}
|
||||
```
|
||||
2) Далее необходимо создать префаб со списком ассетов. Каждый дочерний GameObject префаба рассматривается как один ассет, а его имя должно совпадать с полем в которое будет загружаться ассет. Для загрузки мешей в GameObject необходимо добавить компонент MeshFilter с ссылкой на нужный меш. Для загрузки материала нужен любой компонент унаследованный от Renderer с заданным материалом. Сам префаб должен быть расположен в папке Resources.
|
||||
|
||||
|
||||
|
||||
3) После подготовки хранилища и префаба-списка можно загружать
|
||||
```c#
|
||||
SomeAssets assets = DebugXUtility.LoadStaticData(new SomeAssets(), "SomeAssets");
|
||||
// Готово.
|
||||
```
|
||||
> Пример как с этой утилитой работать можно посмотреть в исходниках в файле `DebugXAssets.cs`.
|
||||
|
||||
<br>
|
||||
|
||||
# Define Symbols
|
||||
+ `DISABLE_DEBUGX_INBUILD` - по умолчанию Gizmo будут рисовать в сборке проекта, этот дефайн отключает рисование. Включить или выключить можно так же в окне настроек DebugX.
|
||||
7
README-RU.md.meta
Normal file
7
README-RU.md.meta
Normal file
@ -0,0 +1,7 @@
|
||||
fileFormatVersion: 2
|
||||
guid: a2f5be859c68e624c80b0c0346b7a097
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
259
README-ZH.md
Normal file
259
README-ZH.md
Normal file
@ -0,0 +1,259 @@
|
||||
|
||||
|
||||
|
||||
<p align="center">
|
||||
<img alt="Version" src="https://img.shields.io/github/package-json/v/DCFApixels/Unity-DebugX?style=for-the-badge&color=ff3530">
|
||||
<img alt="License" src="https://img.shields.io/github/license/DCFApixels/Unity-DebugX?color=ff3530&style=for-the-badge">
|
||||
</p>
|
||||
|
||||
|
||||
# Unity-DebugX
|
||||
|
||||
> [!WARNING]
|
||||
> The translation of the Readme is not completely finished
|
||||
|
||||
|
||||
<table>
|
||||
<tr></tr>
|
||||
<tr>
|
||||
<td colspan="3">Readme Languages:</td>
|
||||
</tr>
|
||||
<tr></tr>
|
||||
<tr>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX/blob/main/README-RU.md">
|
||||
<img src="https://github.com/user-attachments/assets/7bc29394-46d6-44a3-bace-0a3bae65d755"></br>
|
||||
<span>Русский</span>
|
||||
</a>
|
||||
</td>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX">
|
||||
<img src="https://github.com/user-attachments/assets/30528cb5-f38e-49f0-b23e-d001844ae930"></br>
|
||||
<span>English</span>
|
||||
</a>
|
||||
</td>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX/blob/main/README-ZH.md">
|
||||
<img src="https://github.com/user-attachments/assets/3c699094-f8e6-471d-a7c1-6d2e9530e721"></br>
|
||||
<span>中文</span>
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</br>
|
||||
|
||||
一个多功能、可扩展且高性能的 Unity Gizmos 绘图工具。 它既可以在编辑器中运行，也可以在 Build 中运行，绘制可以在 `OnDrawGizmos` 和 `Update` 中进行. 支持 HDRP、URP 和 BRP，但在 BRP 中不支持在 `OnDrawGizmos` 回调中进行绘制。
|
||||
|
||||
语法：
|
||||
```c#
|
||||
DebugX.Draw(duration, color).*Gizmo Function*(...);
|
||||
```
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
## 目录
|
||||
- [安装](#安装)
|
||||
- [基础API](#基础-api)
|
||||
- [设置](#设置)
|
||||
- [API Extension](#API-Extension)
|
||||
- [Loading Static Assets](#Loading-Static-Assets)
|
||||
- [Define Symbols](#define-symbols)
|
||||
|
||||
<br>
|
||||
|
||||
# Installation
|
||||
版本的语义 - [Открыть](https://gist.github.com/DCFApixels/e53281d4628b19fe5278f3e77a7da9e8#file-dcfapixels_versioning_ru-md)
|
||||
### Unity-软件包
|
||||
支持以 Unity 模块的形式安装，只需将 Git-URL 复制到 [PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html) 或 `Packages/manifest.json`中. 复制此 Git-URL 以安装最新的工作版本:
|
||||
```
|
||||
https://github.com/DCFApixels/Unity-DebugX
|
||||
```
|
||||
### 作为源代码
|
||||
该包也可以直接复制到项目文件夹中。
|
||||
|
||||
</br>
|
||||
|
||||
# 基础 API
|
||||
|
||||
绘制预定义 Gizmo 的通用语法：
|
||||
```c#
|
||||
DebugX.Draw(duration, color).*Gizmo Function*(...);
|
||||
```
|
||||
</br>
|
||||
|
||||
预定义的 Gizmo 包括各种图元、线条、点和文本。以下是一些 Gizmo 的示例：
|
||||
```c#
|
||||
// 绘制一条普通线条，类似于 Debug.DrawLine(...)。
|
||||
// 线条将显示一秒钟，并且为红色。
|
||||
DebugX.Draw(1, Color.red).Line(startPoint, endPoint);
|
||||
```
|
||||
```c#
|
||||
// 绘制一个立方体，但仅显示一帧，并且为黄色。
|
||||
DebugX.Draw(Color.yellow).Cube(center, rotation, size);
|
||||
```
|
||||
```c#
|
||||
// 绘制一个球体。
|
||||
DebugX.Draw(Color.yellow).Cube(center, radius);
|
||||
```
|
||||
```c#
|
||||
// 绘制一个点，点的大小为屏幕空间大小。
|
||||
DebugX.Draw(Color.yellow).Dot(startPoint, endPoint);
|
||||
```
|
||||
```c#
|
||||
// 绘制文本。文本也可以显示指定的时间。
|
||||
DebugX.Draw(1, Color.red).Text(center, text);
|
||||
// 使用 DebugXTextSettings 进行高级显示设置。
|
||||
DebugX.Draw(Color.yellow).Text(center, text, DebugXTextSettings.Default.SetBackgroundColor(Color.black));
|
||||
```
|
||||
</br>
|
||||
|
||||
|
||||
如果预定义的图元不够用，可以使用以下方法绘制自定义网格和材质：
|
||||
```c#
|
||||
// 使用 lit 材质绘制任何网格。不使用 GPU 实例化。
|
||||
DebugX.Draw(...).Mesh(mesh, pos, rot, sc);
|
||||
// UnlitMesh - 使用 unlit 材质的网格
|
||||
// WireMesh - 使用线框材质的网格
|
||||
```
|
||||
```c#
|
||||
// 使用 lit 材质绘制静态网格。使用 GPU 实例化。
|
||||
DebugX.Draw(...).Mesh<IStaticMesh>(pos, rot, sc);
|
||||
// UnlitMesh<IStaticMesh> - 使用 unlit 材质的网格
|
||||
// WireMesh<IStaticMesh> - 使用线框材质的网格
|
||||
```
|
||||
```c#
|
||||
// 使用静态材质绘制静态网格。使用 GPU 实例化。
|
||||
DebugX.Draw(...).Mesh<IStaticMesh, IStaticMat>(pos, rot, sc);
|
||||
```
|
||||
</br>
|
||||
|
||||
为了优化绘制，使用静态数据：
|
||||
```c#
|
||||
// 静态网格。使用 GPU 实例化绘制时必须。
|
||||
public struct SomeMesh : IStaticMesh
|
||||
{
|
||||
public Mesh GetMesh() => StaticStorage.SomeMesh;
|
||||
}
|
||||
```
|
||||
```c#
|
||||
// 静态材质。
|
||||
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](#Loading-Static-Assets).
|
||||
|
||||
<br>
|
||||
|
||||
# 设置
|
||||
设置窗口位于 "Tools -> DebugX -> Settings"：
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
# API Extension
|
||||
The simplest option is to create an extension method that combines predefined gizmos, for example:
|
||||
```c#
|
||||
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:
|
||||
```c#
|
||||
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)
|
||||
{
|
||||
//...
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
```c#
|
||||
// Create an extension method.
|
||||
public static class SomeGizmoExtensions
|
||||
{
|
||||
public static DebugX.DrawHandler SomeGizmo(this DebugX.DrawHandler self, /*...*/)
|
||||
{
|
||||
self.Gizmo(new SomeGizmo(/*...*/);
|
||||
return self;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
# Loading Static Assets
|
||||
Для загрузки имеется утилита `DebugXUtility.LoadStaticData(...);`.
|
||||
|
||||
1) First, create a storage for the assets.
|
||||
```c#
|
||||
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.
|
||||
```c#
|
||||
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`.
|
||||
|
||||
<br>
|
||||
|
||||
# Define Symbols
|
||||
+ `DISABLE_DEBUGX_INBUILD` - By default, Gizmos will be drawn in the project build. This define disables drawing. It can also be enabled or disabled in the DebugX settings window.
|
||||
7
README-ZH.md.meta
Normal file
7
README-ZH.md.meta
Normal file
@ -0,0 +1,7 @@
|
||||
fileFormatVersion: 2
|
||||
guid: d7f72ea7f76e11b49986de514fc5d029
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
214
README.md
214
README.md
@ -1,50 +1,113 @@
|
||||
# Unity-DebugX
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p align="center">
|
||||
<img alt="Version" src="https://img.shields.io/github/package-json/v/DCFApixels/Unity-DebugX?style=for-the-badge&color=1e90ff">
|
||||
<img alt="License" src="https://img.shields.io/github/license/DCFApixels/Unity-DebugX?color=1e90ff&style=for-the-badge">
|
||||
<img alt="Version" src="https://img.shields.io/github/package-json/v/DCFApixels/Unity-DebugX?style=for-the-badge&color=ff3530">
|
||||
<img alt="License" src="https://img.shields.io/github/license/DCFApixels/Unity-DebugX?color=ff3530&style=for-the-badge">
|
||||
</p>
|
||||
|
||||
Многофункциональная, расширяемая и производительная утилита рисования Gizmos для Unity. Работает как в редакторе так и в билде, а рисовать можно и в Update. Поддерживается HDRP, URP и BRP, но в BRP не поддерживается отрисовка в коллбеках OnDrawGizmos.
|
||||
|
||||
Синтаксис:
|
||||
# Unity-DebugX
|
||||
|
||||
<table>
|
||||
<tr></tr>
|
||||
<tr>
|
||||
<td colspan="3">Readme Languages:</td>
|
||||
</tr>
|
||||
<tr></tr>
|
||||
<tr>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX/blob/main/README-RU.md">
|
||||
<img src="https://github.com/user-attachments/assets/7bc29394-46d6-44a3-bace-0a3bae65d755"></br>
|
||||
<span>Русский</span>
|
||||
</a>
|
||||
</td>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX">
|
||||
<img src="https://github.com/user-attachments/assets/3c699094-f8e6-471d-a7c1-6d2e9530e721"></br>
|
||||
<span>English</span>
|
||||
</a>
|
||||
</td>
|
||||
<td nowrap width="100">
|
||||
<a href="https://github.com/DCFApixels/Unity-DebugX/blob/main/README-ZH.md">
|
||||
<img src="https://github.com/user-attachments/assets/8e598a9a-826c-4a1f-b842-0c56301d2927"></br>
|
||||
<span>中文</span>
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</br>
|
||||
|
||||
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:
|
||||
```c#
|
||||
DebugX.Draw(duration, color).*Gizmo Function*(...);
|
||||
```
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
## Оглавление
|
||||
- [Установка](#установка)
|
||||
- [API](#api)
|
||||
- [Загрузка статических ассетов](#загрузка-статических-ассетов)
|
||||
- [Настройки](#настройки)
|
||||
- [Кастомный Gizmo](#кастомный-gizmo)
|
||||
## Table of Contents
|
||||
- [Installation](#Installation)
|
||||
- [Basic API](#Basic-api)
|
||||
- [Settings](#Settings)
|
||||
- [API Extension](#API-Extension)
|
||||
- [Loading Static Assets](#Loading-Static-Assets)
|
||||
- [Define Symbols](#define-symbols)
|
||||
|
||||
# Установка
|
||||
Семантика версионирования - [Открыть](https://gist.github.com/DCFApixels/e53281d4628b19fe5278f3e77a7da9e8#file-dcfapixels_versioning_ru-md)
|
||||
### Unity-пакет
|
||||
Поддерживается установка в виде Unity-пакета через добавление [в PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html) или ручного добавления в `Packages/manifest.json` этого git-URL:
|
||||
<br>
|
||||
|
||||
# Installation
|
||||
Versioning semantics - [Открыть](https://gist.github.com/DCFApixels/e53281d4628b19fe5278f3e77a7da9e8#file-dcfapixels_versioning_ru-md)
|
||||
### Unity-Package
|
||||
Supports installation as a Unity module. Copy the Git-URL [into PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html) or into `Packages/manifest.json`. Copy this Git-URL to install the latest working version:
|
||||
```
|
||||
https://github.com/DCFApixels/Unity-DebugX
|
||||
```
|
||||
### В виде исходников
|
||||
Пакет так же может быть добавлен в проект в виде исходников.
|
||||
### Source Code
|
||||
The Package can also be directly copied into the project folder.
|
||||
|
||||
</br>
|
||||
|
||||
# Basic API
|
||||
|
||||
# API
|
||||
|
||||
Синтаксис рисования заготовленных Gizmo:
|
||||
The general syntax for drawing predefined Gizmos:
|
||||
```c#
|
||||
DebugX.Draw(duration, color).*Gizmo Function*(...);
|
||||
```
|
||||
</br>
|
||||
|
||||
Рисование кастомных меша и материала:
|
||||
Among the predefined Gizmos, there are various primitives, lines, points, and text. Examples of some Gizmos:
|
||||
```c#
|
||||
// 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);
|
||||
```
|
||||
```c#
|
||||
// Draws a cube, but for just one frame and in yellow.
|
||||
DebugX.Draw(Color.yellow).Cube(center, rotation, size);
|
||||
```
|
||||
```c#
|
||||
// Draws a sphere.
|
||||
DebugX.Draw(Color.yellow).Cube(center, radius);
|
||||
```
|
||||
```c#
|
||||
// Draws a point. The point has a screen space size.
|
||||
DebugX.Draw(Color.yellow).Dot(startPoint, endPoint);
|
||||
```
|
||||
```c#
|
||||
// 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));
|
||||
```
|
||||
</br>
|
||||
|
||||
|
||||
In case the predefined primitives are not enough, there are methods for drawing custom meshes and materials:
|
||||
```c#
|
||||
//Рисования любого меша lit материалом. Без GPU instancing.
|
||||
DebugX.Draw(...).Mesh(mesh, pos, rot, sc);
|
||||
@ -61,76 +124,76 @@ DebugX.Draw(...).Mesh<IStaticMesh>(pos, rot, sc);
|
||||
//Рисования статического меша статическим материалом. В режиме GPU instancing.
|
||||
DebugX.Draw(...).Mesh<IStaticMesh, IStaticMat>(pos, rot, sc);
|
||||
```
|
||||
</br>
|
||||
|
||||
Для оптимизации отрисовки используются статические данные:
|
||||
Static data is used to optimize the rendering:
|
||||
```c#
|
||||
// Статический меш. Обязателен для отрисовки с GPU instancing.
|
||||
// Static mesh. Required for drawing with GPU instancing.
|
||||
public struct SomeMesh : IStaticMesh
|
||||
{
|
||||
public Mesh GetMesh() => StaticStorage.SomeMesh;
|
||||
}
|
||||
```
|
||||
```c#
|
||||
// Статический материал.
|
||||
// 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](#Loading-Static-Assets).
|
||||
|
||||
# Загрузка статических ассетов
|
||||
Для загрузки имеется утилита `DebugXUtility.LoadStaticData(...);`.
|
||||
<br>
|
||||
|
||||
1) Сначала создаем хранилище для ассетов.
|
||||
```c#
|
||||
public readonly struct SomeAssets
|
||||
{
|
||||
public readonly Mesh SomeMesh;
|
||||
public readonly Material SomeMaterial;
|
||||
}
|
||||
```
|
||||
2) Далее необходимо создать префаб со списком ассетов. Каждый дочерний GameObject префаба рассматривается как один ассет, а его имя должно совпадать с полем в которое будет загружаться ассет. Для загрузки мешей в GameObject необходимо добавить компонент MeshFilter с ссылкой на нужный меш. Для загрузки материала нужен любой компонент унаследованный от Renderer с заданным материалом. Сам префаб должен быть расположен в папке Resources.
|
||||
|
||||
|
||||
|
||||
3) После подготовки хранилища и префаба-списка можно загружать
|
||||
```c#
|
||||
SomeAssets assets = DebugXUtility.LoadStaticData(new SomeAssets(), "SomeAssets");
|
||||
// Готово.
|
||||
```
|
||||
> Пример как с этой утилитой работать можно посмотреть в исходинках в файле `DebugXAssets.cs`.
|
||||
|
||||
# Настройки
|
||||
Окно настроек "Tools -> DebugX -> Settings":
|
||||
# Settings
|
||||
Settings window "Tools -> DebugX -> Settings":
|
||||
|
||||
|
||||
|
||||
# Кастомный Gizmo
|
||||
<br>
|
||||
|
||||
Кастомная реализация Gizmo:
|
||||
# API Extension
|
||||
The simplest option is to create an extension method that combines predefined gizmos, for example:
|
||||
```c#
|
||||
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:
|
||||
```c#
|
||||
public readonly struct SomeGizmo : IGizmo<SomeGizmo>
|
||||
{
|
||||
// Данные.
|
||||
// Gizmo Data.
|
||||
|
||||
public SomeGizmo(/*...*/)
|
||||
{
|
||||
// Заполнение данных.
|
||||
// Fill the data.
|
||||
}
|
||||
|
||||
public IGizmoRenderer<SomeGizmo> RegisterNewRenderer() => new Renderer();
|
||||
private class Renderer : IGizmoRenderer<SomeGizmo>
|
||||
{
|
||||
// Контроль порядка выполнения рендереров.
|
||||
public int ExecuteOrder => 0; //можно использовать default(SomeMat).GetExecutuonOrder();
|
||||
// Флаг системе о способе оптимизации.
|
||||
// Если метод рисовки или подготовки зависят от текущей камеры, то false，иначе true.
|
||||
// Если не уверены то выбирайте false.
|
||||
// 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;
|
||||
|
||||
// Подготовка данных перед рендером, тут можно выполнить дополнительные расчеты или запланировать Job.
|
||||
// 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)
|
||||
@ -139,7 +202,7 @@ public readonly struct SomeGizmo : IGizmo<SomeGizmo>
|
||||
}
|
||||
}
|
||||
|
||||
// Рендер, тут можно напрямую воспользоваться графическим API или добавить команду в CommandBuffer.
|
||||
// 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)
|
||||
@ -151,7 +214,7 @@ public readonly struct SomeGizmo : IGizmo<SomeGizmo>
|
||||
}
|
||||
```
|
||||
```c#
|
||||
// Создание метода расширения.
|
||||
// Create an extension method.
|
||||
public static class SomeGizmoExtensions
|
||||
{
|
||||
public static DebugX.DrawHandler SomeGizmo(this DebugX.DrawHandler self, /*...*/)
|
||||
@ -162,6 +225,31 @@ public static class SomeGizmoExtensions
|
||||
}
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
# Loading Static Assets
|
||||
Для загрузки имеется утилита `DebugXUtility.LoadStaticData(...);`.
|
||||
|
||||
1) First, create a storage for the assets.
|
||||
```c#
|
||||
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.
|
||||
```c#
|
||||
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`.
|
||||
|
||||
<br>
|
||||
|
||||
# Define Symbols
|
||||
+ `DISABLE_DEBUGX_INBUILD` - по умолчанию Gizmo будут рисовать в сборке проекта, этот дефайн отключает рисование. Включить или выключить можно так же в окне настроек DebugX.
|
||||
+ `DISABLE_DEBUGX_INBUILD` - By default, Gizmos will be drawn in the project build. This define disables drawing. It can also be enabled or disabled in the DebugX settings window.
|
||||
Loading…
Reference in New Issue
Block a user