update readme

2026-04-21 17:35:56 +08:00 · 2026-03-13 20:44:02 +08:00 · 2026-03-13 20:44:02 +08:00 · 2c11eaa463
commit 2c11eaa463
parent 8901c4fc83
3 changed files with 140 additions and 63 deletions
--- a/README-RU.md
+++ b/README-RU.md
@ -19,7 +19,7 @@
  <tr></tr>
  <tr>
    <td nowrap width="100">
-      <a href="https://github.com/DCFApixels/DragonECS/blob/main/README-RU.md">
+      <a href="README-RU.md">
        <img src="https://github.com/user-attachments/assets/3c699094-f8e6-471d-a7c1-6d2e9530e721"></br>
        <span>Русский</span>
      </a>  
@ -31,7 +31,7 @@
      </a>  
    </td>
    <td nowrap width="100">
-      <a href="https://github.com/DCFApixels/DragonECS/blob/main/README-ZH.md">
+      <a href="README-ZH.md">
        <img src="https://github.com/user-attachments/assets/8e598a9a-826c-4a1f-b842-0c56301d2927"></br>
        <span>中文</span>
      </a>  
@ -50,6 +50,7 @@ DragonECS - это [ECS](https://en.wikipedia.org/wiki/Entity_component_system)

 ## Оглавление
 - [Установка](#установка)
+- [Расширения](#расширения)
 - [Основные концепции](#основные-концепции)
  - [Entity](#entity)
  - [Component](#component)
@ -77,7 +78,6 @@ DragonECS - это [ECS](https://en.wikipedia.org/wiki/Entity_component_system)
  - [Компоненты мира](#компоненты-мира)
  - [Конфиги](#конфиги)
 - [Проекты на DragonECS](#Проекты-на-DragonECS)
- [Расширения](#расширения)
 - [FAQ](#faq)
 - [Обратная связь](#обратная-связь)

@ -94,24 +94,49 @@ DragonECS - это [ECS](https://en.wikipedia.org/wiki/Entity_component_system)
 + Игровые движки с C#: Unity, Godot, MonoGame и т.д.

 Протестировано:
-+ **Unity:** Минимальная версия 2020.1.0;
+ **Unity:** Минимальная версия 2020.3.0;

 ## Установка для Unity
 > Рекомендуется так же установить расширение [Интеграция с движком Unity](https://github.com/DCFApixels/DragonECS-Unity)
 * ### Unity-модуль
-Поддерживается установка в виде Unity-модуля в  при помощи добавления git-URL [в PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html) или ручного добавления в `Packages/manifest.json`: 
+Поддерживается установка в виде Unity-модуля при помощи добавления git-URL [в PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html): 
 ```
 https://github.com/DCFApixels/DragonECS.git
 ```
+Или ручного добавления этой строчки в `Packages/manifest.json`:
+```
+"com.dcfa_pixels.dragonecs": "https://github.com/DCFApixels/DragonECS.git",
+```
+
 * ### В виде исходников
-Фреймворк так же может быть добавлен в проект в виде исходников.
+Можно так же напрямую скопировать в проект исходники фреймворка.
+
+</br>
+
+# Расширения
+* Интеграции:
+    * [Unity](https://github.com/DCFApixels/DragonECS-Unity)
+    * [Godot](https://gitlab.com/InauniusOwn/Libraries/DraGodot)
+* Пакеты:
+    * [Автоматическое внедрение зависимостей](https://github.com/DCFApixels/DragonECS-AutoInjections)
+    * [Классическая C# многопоточность](https://github.com/DCFApixels/DragonECS-ClassicThreads)
+    * [Recursivity](https://github.com/DCFApixels/DragonECS-Recursivity)
+    * [Hybrid](https://github.com/DCFApixels/DragonECS-Hybrid)
+    * [Графы](https://github.com/DCFApixels/DragonECS-Graphs)
+* Утилиты:
+    * [Упрощенный синтаксис](https://gist.github.com/DCFApixels/d7bfbfb8cb70d141deff00be24f28ff0)
+    * [Таймеры](https://gist.github.com/DCFApixels/71a416275660c465ece76242290400df)
+    * [Однокадровые компоненты](https://gist.github.com/DCFApixels/46d512dbcf96c115b94c3af502461f60)
+    * [Шаблоны кода IDE](https://gist.github.com/ctzcs/0ba948b0e53aa41fe1c87796a401660b) и [для Unity](https://gist.github.com/ctzcs/d4c7730cf6cd984fe6f9e0e3f108a0f1)
+> *Твое расширение? Если разрабатываешь расширение для DragonECS, пиши [сюда](#обратная-связь).
+
 </br>

 # Основные концепции
 ## Entity
-**Сущности** - это то к чему крепятся данные. Реализованы в виде идентификаторов, которых есть 2 вида:
-* `int` - однократный идентификатор, применяется в пределах одного тика. Не рекомендуется хранить `int` идентификаторы, в место этого используйте `entlong`;
-* `entlong` - долговременный идентификатор, содержит в себе полный набор информации для однозначной идентификации;
+**Сущности** - это то к чему крепятся данные. Для доступа к сущности используются идентификаторы двух типов:
+* `int` - однократный идентификатор, применяется в пределах одного тика. Не рекомендуется использовать для хранения;
+* `entlong` - долговременный идентификатор, содержит метку поколения, что делает его уникальным навсегда. Подходит для хранения.
 ``` c#
 // Создание новой сущности в мире.
 int entityID = _world.NewEntity();
@ -129,10 +154,11 @@ int newEntityID = _world.CloneEntity(entityID);
 <details>
 <summary>Работа с entlong</summary>
 
+
 ``` c#
 // Конвертация int в entlong.
 entlong entity = _world.GetEntityLong(entityID);
-// или
+// упрощенная версия
 entlong entity = (_world, entityID);

 // Проверка что сущность еще жива.
@ -148,6 +174,8 @@ if (entity.TryGetID(out int entityID)) { }
 ```
 
 </details>
+
+> 
 
 > Сущности не могут существовать без компонентов, пустые сущности будут автоматически удаляться сразу после удаления последнего компонента либо в конце тика.
 ## Component
@ -183,6 +211,48 @@ class SomeSystem : IEcsPreInit, IEcsInit, IEcsRun, IEcsDestroy
 ```
 > Для реализации дополнительных процессов перейдите к разделу [Процессы](#Процессы).

+<details>
+<summary>Пример системы</summary>
+ 
+
+``` c#
+// Система
+class DamageSystem : IEcsRun, IEcsInject<EcsDefaultWorld>
+{
+    // Аспекты описаны в соответствующей главе
+    class Aspect : EcsAspect
+    {
+        public EcsPool<DamageRequest> DamageRequests = Inc;
+        public EcsPool<Health> Healths = Inc;
+    }
+    // Мир - хранилище сущностей, так же описан в соответствующей главе
+    EcsDefaultWorld world;
+    // Процесс Run
+    public void Run()
+    {
+        // Итерируемся по сущностям, в рамках Run можно использовать int идентификаторы сущностей
+        foreach (int e in world.Where(out Aspect a))
+        {
+            // Логика нанесения урона
+            a.Healths[e].Points -= a.DamageRequests[e].Points;
+        }
+    }
+    // Процесс Inject. Получение инстанса EcsDefaultWorld
+    void IEcsInject<EcsDefaultWorld>.Inject(EcsDefaultWorld obj) => world = obj;
+}
+// Компоненты
+public struct DamageRequest : IEcsComponent
+{
+    public float Points;
+}
+public struct Health : IEcsComponent
+{
+    public float Points;
+}
+```
+ 
+ </details>
+
 </br>

 # Концепции фреймворка
@ -466,10 +536,13 @@ poses.Del(entityID);
 </details>

 ## Маска
-Применяется для фильтрации сущностей по наличию или отсутствию компонентов.  
+Набор требований к компонентам сущности: какие компоненты должны присутствовать, а какие отсутствовать. Маска — это просто данные, она не выполняет поиск, а используется запросами для фильтрации сущностей.
+
+Обычно маски не используются в чистом виде, а являются частью [Аспекта](#Аспект).
+
 ``` c#
-// Создание маски которая проверяет что у сущностей есть компоненты 
-// SomeCmp1 и SomeCmp2, но нет компонента SomeCmp3.
+// Создание маски с улосвием наличия компонентов SomeCmp1 и SomeCmp2, 
+// и с улосвием отсутсвия компонента SomeCmp3.
 EcsMask mask = EcsMask.New(_world)
    // Inc - Условие наличия компонента.
    .Inc<SomeCmp1>()
@ -501,42 +574,47 @@ EcsMask mask = _staticMask.ToMask(_world);
 </details>

 ## Аспект
-Пользовательские классы наследуемые от `EcsAspect` и используемые для взаимодействия с сущностями. Аспекты одновременно являются кешем пулов и содержат маску. Можно рассматривать аспекты как описание того с какими сущностями работает система.

-Упрощенный синтаксис:
+Пользовательские классы наследуемые от `EcsAspect`, описывающие наборы компонентов, с которыми работает система. Аспект одновременно выполняет две функции:
+ Маска — инициализирует и хранит [маску](#Маска), за счет чего может использоваться в запросах.
+ Кэш пулов — предоставляет быстрый доступ к пулам компонентов.
+
+
+Проще говоря, аспект — это удобный способ описать "с какими сущностями я работаю и как получать их компоненты".
+
+
+Пример:
 ``` c#
-using DCFApixels.DragonECS;
-// ...
 class Aspect : EcsAspect
 {
-    // Кешируется пул и Pose добавляется во включающее ограничение.
+    // Кешируется пул и тип Pose добавляется во включающее условие.
    public EcsPool<Pose> poses = Inc;
-    // Кешируется пул и Velocity добавляется во включающее ограничение.
+    // Кешируется пул и тип Velocity добавляется во включающее условие.
    public EcsPool<Velocity> velocities = Inc;
-    // Кешируется пул и FreezedTag добавляется в исключающее ограничение.
+    // Кешируется пул и тип FreezedTag добавляется в исключающее условие.
    public EcsTagPool<FreezedTag> freezedTags = Exc;
-
-    // При запросах будет проверяться наличие компонентов
-    // из включающего ограничения маски и отсутствие из исключающего.
-    // Так же есть Opt - только кеширует пул, не влияя на маску. 
 }
 ```

+Назначение статических свойств:
+ Inc — компонент должен быть у сущности (включающее условие) + кеширует пул
+ Exc — компонента не должно быть у сущности (исключающее условие) + кеширует пул
+ Opt — компонент может быть, но не влияет на фильтрацию (только кеширует пул для доступа)
+ Any — хотя бы один из компонентов с Any должен присутствовать + кеширует пул
+
 <details>
-<summary>Явный синтаксис (результат идентичен примеру выше):</summary>
+<summary>Инициализация через метод (результат идентичен примеру выше):</summary>

 ``` c#
-using DCFApixels.DragonECS;
-// ...
 class Aspect : EcsAspect
 {
    public EcsPool<Pose> poses;
    public EcsPool<Velocity> velocities;
    protected override void Init(Builder b)
    {
-        poses = b.Include<Pose>();
-        velocities = b.Include<Velocity>();
-        b.Exclude<FreezedTag>();
+        poses = b.IncludePool<Pose>();
+        velocities = b.IncludePool<Velocity>();
+        b.ExcludePool<FreezedTag>();
    }
 }
 ```
@ -546,10 +624,8 @@ class Aspect : EcsAspect
 <details>
 <summary>Комбинирование аспектов</summary>

-В аспекты можно добавлять другие аспекты, тем самым комбинируя их. Ограничения так же будут скомбинированы.
+В аспекты можно добавлять другие аспекты, тем самым комбинируя их. Маски так же будут скомбинированы.
 ``` c#
-using DCFApixels.DragonECS;
-// ...
 class Aspect : EcsAspect
 {
    public OtherAspect1 otherAspect1;
@ -562,7 +638,7 @@ class Aspect : EcsAspect
        otherAspect1 = b.Combine<OtherAspect1>(1);
        // Хотя для OtherAspect1 метод Combine был вызван раньше, сначала будет скомбинирован с OtherAspect2, так как по умолчанию order = 0.
        otherAspect2 = b.Combine<OtherAspect2>();
-        // Если в OtherAspect1 или в OtherAspect2 было ограничение b.Exclude<Pose>() тут оно будет заменено на b.Include<Pose>().
+        // Если в OtherAspect1 или в OtherAspect2 было условие b.Exclude<Pose>() тут оно будет заменено на b.Include<Pose>().
        poses = b.Include<Pose>();
    }
 }
@ -578,11 +654,11 @@ class Aspect : EcsAspect
 </details>

 ## Запросы
-Фильтруют сущности и выдают коллекции сущностей удовлетворяющие определенным условиям. Встроенный запрос `Where` фильтрует на соответствие условиям маски компонентов и имеет несколько перегрузок:
+Запросы позволяют отфильтровать и получать коллекции сущностей, удовлетворяющих заданным условиям. Основной метод — `Where`, который фильтрует по маске компонентов и имеет несколько перегрузок:
+ `EcsWorld.Where<TAspect>(out TAspect aspect)` - Фильтрация по маске, определённой в аспекте, плюс получение самого аспекта с закешированными пулами.
 + `EcsWorld.Where(EcsMask mask)` - Обычная фильтрация по маске;
-+ `EcsWorld.Where<TAspect>(out TAspect aspect)` - Сочетает в себе фильтрацию по маске из аспекта и получение аспекта;

-Запрос `Where` применим как к `EcsWorld` так и коллекциям фреймворка (в этом плане Where чем-то похож на аналогичный из Linq). Так же имеются перегрузки для сортировки сущностей по `Comparison<int>`. 
+`Where` можно вызывать не только у мира, но и у любых коллекций фреймворка (в этом плане Where чем-то похож на аналогичный из Linq). Также доступны перегрузки для сортировки сущностей с помощью `Comparison<int>`. 

 Пример системы:
 ``` c#
@ -597,10 +673,9 @@ public class SomeDamageSystem : IEcsRun, IEcsInject<EcsDefaultWorld>
        public EcsTagPool<IsDiedSignal> isDiedSignals = Opt;
    }
    EcsDefaultWorld _world;
-    public void Inject(EcsDefaultWorld world) => _world = world;
-
    public void Run()
    {
+        // Запрашиваем сущности удовлетворяющее маске из Aspect
        foreach (var e in _world.Where(out Aspect a))
        {
            // Сюда попадают сущности с компонентами Health, DamageSignal и без IsInvulnerable.
@ -615,6 +690,7 @@ public class SomeDamageSystem : IEcsRun, IEcsInject<EcsDefaultWorld>
            }
        }
    }
+    public void Inject(EcsDefaultWorld world) => _world = world;
 }
 ```

@ -623,7 +699,7 @@ public class SomeDamageSystem : IEcsRun, IEcsInject<EcsDefaultWorld>
 ## Коллекции

 ### EcsSpan
-Коллекция сущностей, доступная только для чтения и выделяемая только в стеке. Состоит из ссылки на массив, длинны и идентификатора мира. Аналог `ReadOnlySpan<int>`.
+`ref struct` коллекция сущностей, доступная только для чтения. Состоит из ссылки на массив, длинны и идентификатора мира. Аналог `ReadOnlySpan<int>`.
 ``` c#
 // Запрос Where возвращает сущности в виде EcsSpan.
 EcsSpan es = _world.Where(out Aspect a);
@ -641,7 +717,7 @@ for (int i = 0; i < es.Count; i++)
 > Хотя `EcsSpan` является просто массивом, в нем не допускается дублирование сущностей. 

 ### EcsGroup
-Вспомогательная коллекция основанная на Sparse Set для хранения множества сущностей с O(1) операциями добавления/удаления/проверки и т.д.
+Вспомогательная коллекция основанная на Sparse Set для хранения множества сущностей с `O(1)` операциями добавления/удаления/проверки и т.д.
 ``` c#
 // Получаем новую группу. EcsWorld содержит в себе пул групп,
 // поэтому будет переиспользована свободная или создана новая.
@ -1011,6 +1087,23 @@ public struct WorldComponent : IEcsWorldComponent<WorldComponent>
 ## Опубликованные проекты:

 <table>
+  <tr>
+    <td align="center">
+      <a href="https://dcfapixels.github.io/Project8.html">
+        Crystal Siege
+        <img src="https://github.com/user-attachments/assets/1aa60a50-2668-4919-aca9-d6d2b980c3dd">
+      </a> 
+    </td>
+    <td align="center">
+      <a href="https://play.google.com/store/apps/details?id=com.ZlodeyStudios.OrdersMatter">
+        Order matters
+        <img src="https://github.com/user-attachments/assets/c55b2647-9b6e-4145-98ff-c3d094600fa1">
+      </a> 
+    </td>
+  </tr>
+
+  <tr></tr>
+
  <tr>
    <td align="center">
      <a href="https://yandex.ru/games/app/206024?utm_source=game_popup_menu">
@ -1019,33 +1112,17 @@ public struct WorldComponent : IEcsWorldComponent<WorldComponent>
      </a> 
    </td>
    <td align="center">
-      <span>
-        ㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤ
+        _____________
        <img tabindex="-1" src="https://github.com/user-attachments/assets/3fa1ca6d-29f6-43e6-aafe-cc9648d20490" alt="screenshot">
-      </span> 
    </td>
  </tr>
 </table>

 </br>

-# Расширения
-* Пакеты:
-    * [Интеграция с движком Unity](https://github.com/DCFApixels/DragonECS-Unity)
-    * [Автоматическое внедрение зависимостей](https://github.com/DCFApixels/DragonECS-AutoInjections)
-    * [Классическая C# многопоточность](https://github.com/DCFApixels/DragonECS-ClassicThreads)
-    * [Recursivity](https://github.com/DCFApixels/DragonECS-Recursivity)
-    * [Hybrid](https://github.com/DCFApixels/DragonECS-Hybrid)
-    * [Графы](https://github.com/DCFApixels/DragonECS-Graphs)
-* Утилиты:
-    * [Упрощенный синтаксис](https://gist.github.com/DCFApixels/d7bfbfb8cb70d141deff00be24f28ff0)
-    * [Однокадровые компоненты](https://gist.github.com/DCFApixels/46d512dbcf96c115b94c3af502461f60)
-    * [Шаблоны кода IDE](https://gist.github.com/ctzcs/0ba948b0e53aa41fe1c87796a401660b) и [для Unity](https://gist.github.com/ctzcs/d4c7730cf6cd984fe6f9e0e3f108a0f1)
-> *Твое расширение? Если разрабатываешь расширение для DragonECS, пиши [сюда](#обратная-связь).
-
-</br>
 
 # FAQ
+
 ## 'ReadOnlySpan<>' could not be found
 В версии Unity 2020.1.х в консоли может выпадать ошибка:
 ```
--- a/README-ZH.md
+++ b/README-ZH.md
@ -19,7 +19,7 @@
  <tr></tr>
  <tr>
    <td nowrap width="100">
-      <a href="https://github.com/DCFApixels/DragonECS/blob/main/README-RU.md">
+      <a href="README-RU.md">
        <img src="https://github.com/user-attachments/assets/7bc29394-46d6-44a3-bace-0a3bae65d755"></br>
        <span>Русский</span>
      </a>  
@ -31,7 +31,7 @@
      </a>  
    </td>
    <td nowrap width="100">
-      <a href="https://github.com/DCFApixels/DragonECS/blob/main/README-ZH.md">
+      <a href="README-ZH.md">
        <img src="https://github.com/user-attachments/assets/3c699094-f8e6-471d-a7c1-6d2e9530e721"></br>
        <span>中文</span>
      </a>  
--- a/README.md
+++ b/README.md
@ -21,7 +21,7 @@
  <tr></tr>
  <tr>
    <td nowrap width="100">
-      <a href="https://github.com/DCFApixels/DragonECS/blob/main/README-RU.md">
+      <a href="README-RU.md">
        <img src="https://github.com/user-attachments/assets/7bc29394-46d6-44a3-bace-0a3bae65d755"></br>
        <span>Русский</span>
      </a>  
@ -33,7 +33,7 @@
      </a>  
    </td>
    <td nowrap width="100">
-      <a href="https://github.com/DCFApixels/DragonECS/blob/main/README-ZH.md">
+      <a href="README-ZH.md">
        <img src="https://github.com/user-attachments/assets/8e598a9a-826c-4a1f-b842-0c56301d2927"></br>
        <span>中文</span>
      </a>