From 77f9e1e844667f166951c087b7cd9d4982f56be5 Mon Sep 17 00:00:00 2001 From: Mikhail <99481254+DCFApixels@users.noreply.github.com> Date: Fri, 17 Apr 2026 16:28:48 +0800 Subject: [PATCH] update readme --- README-RU.md | 2 +- README.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 143 insertions(+), 11 deletions(-) diff --git a/README-RU.md b/README-RU.md index 0713592..88f28f8 100644 --- a/README-RU.md +++ b/README-RU.md @@ -156,6 +156,7 @@ _pipeline = EcsPipeline.New() * ### `WorldQueriesMonitor` Расположен вместе с `WorldMonitor`, показывает список всех Where запросов которые выполняли системы. Вверху есть поле для поиска запросов по именам компонентам. Поисковую строку можно разделять символом `/` для одновременного поиска нескольких компонентов. Рядом с каждым Where запросом есть кнопка `Snapshot`, по нажатию откроется окно со списоком всех сущностей которые на данный момент удовлетворяют маске запроса. +

@@ -467,7 +468,6 @@ public class EcsRoot : MonoBehaviour
- # Кастомизация инспектора ## Атрибуты инспектора diff --git a/README.md b/README.md index 511740a..a5632e0 100644 --- a/README.md +++ b/README.md @@ -49,15 +49,17 @@ This package integrates DragonECS with the Unity editor and runtime. It provides - [Debug](#debug) - [Debug service](#debug-service) - [Debug module](#debug-module) - - [Visual debugging](#Visual-debugging) -- [Templates](#Templates) -- [Binding to GameObjects](#Binding-to-GameObjects) + - [Visual debugging](#visual-debugging) +- [Templates](#templates) +- [Binding to GameObjects](#binding-to-gameobjects) - [World Provider](#world-provider) -- [Pipeline template](#Pipeline-template) -- [FixedUpdate LateUpdate](#fixedupdate-lateupdate) -- [Project documentation](#Project-documentation) -- [Settings window](#Settings-window) -- [Reference Repairer](#Reference-Repairer) +- [Pipeline template](#pipeline-template) +- [FixedUpdate and LateUpdate](#fixedupdate-and-lateupdate) +- [Inspector Customization](#inspector-customization) +- [Jobs Support](#jobs-support) +- [Project documentation](#project-documentation) +- [Settings window](#settings-window) +- [Reference Repairer](#reference-repairer) - [FAQ](#faq)
@@ -147,7 +149,16 @@ Displays processes and systems in a matrix layout. Systems are shown in executio Displays `EcsWorld` state. A separate monitor is created for each world passed to `AddUnityDebug(...)`.

- + +

+ +----- + +* ### `WorldQueriesMonitor` +Located together with `WorldMonitor`, shows a list of all Where queries that systems have executed. At the top there is a search field for filtering queries by component names. The search string can be split with a `/` character to search for multiple components at once. Next to each Where query there is a `Snapshot` button; clicking it opens a window showing a list of all entities that currently match the query mask. + +

+

----- @@ -244,6 +255,8 @@ public struct Health : IEcsComponent, ITemplateNode } ``` +> The section [Inspector Customization](#Inspector-Customization) describes customization of component display and usage outside of entity templates. + #### Custom template implementation If built-in `ComponentTemplate` or `TagComponentTemplate` do not fit the requirements, implement a custom template by implementing `IComponentTemplate`. This can be useful for custom pools. In most cases the built-in templates are sufficient. @@ -435,7 +448,7 @@ public class EcsMyWorldSingletonProvider : EcsWorldProvider
-# Pipeline templates +# Pipeline template Pipelines and entities can be assembled from templates. Pipeline templates are modules implementing the `IEcsModule` interface. The package provides two pipeline template types by default: `ScriptablePipelineTemplate` and `MonoPipelineTemplate`. @@ -496,6 +509,125 @@ public class EcsRoot : MonoBehaviour
+# Inspector Customization + +## Inspector Attributes ++ **[ReferenceDropDown]** - +Applied to a field with `[SerializeReference]`. Adds a type selection button from a list. The set of available types can be restricted by passing a list to the constructor. + ++ **[ReferenceDropDownWithout]** - +Used together with `[ReferenceDropDown]` to exclude the specified types (and their descendants) from the selection list. + ++ **[DragonMetaBlock]** - +Displays the value in the inspector similarly to how components are displayed in entity templates. Takes meta-attributes into account (`MetaGroup`, `MetaColor`, `MetaDescription`, `MetaID`, etc.). + +## Behavior of Meta‑Attributes ++ Hierarchical grouping of items in the `Add Component` menu or `[ReferenceDropDown]` is defined via `[MetaGroup]`. ++ The component color in the inspector is determined by the type name by default. The coloring mode can be changed in the settings window. An explicit color is set via `[MetaColor]`. ++ When the type name matches the file name (or when `[MetaID]` is present), a file icon appears next to the delete button: a single click selects the script in the project, a double click opens it. ++ If `[MetaDescription]` is specified, a tooltip icon with the description text is displayed next to it. ++ When restoring a Missing Reference using Reference Repairer, the tool searches for a match between the old and new type names by the `[MetaID(id)]` attribute. + + +## Examples: + +`DragonMetaBlock` attribute: +```c# +// Display of the field customizable via meta-attributes. +// Similar to components in MonoEntityTemplate or ScriptableEntityTemplate. +[DragonMetaBlock] +public SomeComponent Component; + +// Can be applied to any field of any type. +[DragonMetaBlock] +public Foo Foo; +``` + +`ReferenceDropDown` and `ReferenceDropDownWithout`: +```c# +// Adds a button to select an implementation of ITemplateNode from a drop-down list. +[SerializeReference] +[ReferenceDropDown] +public ITemplateNode Template; +``` + +```c# +// Also applicable to any field of any type. +// The list will contain only type Foo and its descendants, excluding FooExc and its descendants. +[SerializeReference] +[ReferenceDropDown(typeof(Foo))] +[ReferenceDropDownWithout(typeof(FooExc))] +public object Template; +``` + +Combination and other use cases: +```c# +// Attributes can be combined. +[DragonMetaBlock] +[ReferenceDropDown] +public ITemplateNode Template; + +// A wrapper over ITemplateNode, similar to the example above. +public ComponentTemplateProperty Template; + +// Attributes work correctly with arrays and lists. +[DragonMetaBlock] +[ReferenceDropDown] +public ITemplateNode[] Template; +``` + +
+ +# Jobs Support + +DragonECS is compatible with Unity's Job system by default. Example: +```c# +EcsWorld _world; +class Aspect : EcsAspect +{ + // Pool for unmanaged components. + public EcsValuePool Cmps = Inc; +} +public void Run() +{ + var job = new Job() + { + // Same as Where, but returns an unmanaged entity list. + Entities = _world.WhereUnsafe(out Aspect a), + // Convert the pool to its unmanaged version + Cmps = a.Cmps.AsNative(), + X = 10f, + }; + JobHandle jobHandle = job.Schedule(job.Entities.Count, 64); + jobHandle.Complete(); +} +``` +```c# +// Unmanaged component. +public struct Cmp : IEcsValueComponent +{ + public float A; +} +private struct Job : IJobParallelFor +{ + public EcsUnsafeSpan Entities; + public NativeEcsValuePool Cmps; + public float X; + public Job(EcsUnsafeSpan entities, float x) + { + Entities = entities; + X = x; + } + public void Execute(int index) + { + var e = Entities[index]; + Cmps[e].A += X; + } +} +``` + +
+ # Project documentation A documentation window based on meta-attributes is available via `Tools > DragonECS > Documentation`. Documentation is generated on first open and when the `Update` button is pressed.