Merge branch 'main' into unsafe_pool

DragonECS.csproj

@@ -10,7 +10,7 @@
         <RootNamespace>DCFApixels.DragonECS</RootNamespace>
 
         <Title>DragonECS</Title>
-        <Version>0.9.20</Version>
+        <Version>0.9.21</Version>
         <Authors>DCFApixels</Authors>
         <Description>ECS Framework for Game Engines with C# and .Net Platform</Description>
         <Copyright>DCFApixels</Copyright>

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`;
+* `int` - однократный идентификатор, применяется в пределах одного тика. Не рекомендуется использовать для хранения;
-* `entlong` - долговременный идентификатор, содержит в себе полный набор информации для однозначной идентификации;
+* `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, 
-// SomeCmp1 и SomeCmp2, но нет компонента SomeCmp3.
+// и с улосвием отсутсвия компонента 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>();
+        poses = b.IncludePool<Pose>();
-        velocities = b.Include<Velocity>();
+        velocities = b.IncludePool<Velocity>();
-        b.Exclude<FreezedTag>();
+        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.х в консоли может выпадать ошибка:
 ```

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>  

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>  

package.json

@@ -8,7 +8,7 @@
     "displayName": "DragonECS",
     "description": "C# Entity Component System Framework",
     "unity": "2020.3",
-    "version": "0.9.20",
+    "version": "0.9.21",
     "repository": {
         "type": "git",
         "url": "https://github.com/DCFApixels/DragonECS.git"

src/DebugUtils/TypeMeta.cs

@@ -370,6 +370,14 @@ namespace DCFApixels.DragonECS
         #endregion
 
         #region Other
+        public static void ClearCache()
+        {
+            lock (_lock)
+            {
+                _metaCache.Clear();
+                _metaCache.Add(typeof(void), NullTypeMeta);
+            }
+        }
         ITypeMeta ITypeMeta.BaseMeta
         {
             get { return null; }

src/EcsAspect.cs

@@ -411,6 +411,10 @@ namespace DCFApixels.DragonECS
         #endregion
 
         #region Other
+        public static void ClearCache()
+        {
+            _staticMaskCache.Clear();
+        }
         EcsMask IComponentMask.ToMask(EcsWorld world) { return _mask; }
         #endregion
 

src/EcsWorld.cs

@@ -175,10 +175,6 @@ namespace DCFApixels.DragonECS
                 // тут сложно однозначно посчитать, так как нужно еще место под аспекты и запросы
                 int controllersCount = config.PoolsCapacity * 4;
                 _worldComponentPools = new StructList<WorldComponentPoolAbstract>(controllersCount);
-                if (controllersCount < _allWorldComponentPools.Capacity)
-                {
-                    _allWorldComponentPools.Capacity = controllersCount;
-                }
 
                 if (worldID < 0 || (worldID == NULL_WORLD_ID && nullWorld == false))
                 {
@@ -234,6 +230,13 @@ namespace DCFApixels.DragonECS
 #endif
                     return;
                 }
+
+                for (int i = Entities.Count - 1; i >= 0; i--)
+                {
+                    DelEntity(Entities[i]);
+                }
+                ReleaseDelEntityBufferAll();
+
                 _isDestroyed = true;
                 _listeners.InvokeOnWorldDestroy();
                 _entityDispenser = null;
@@ -253,7 +256,6 @@ namespace DCFApixels.DragonECS
                 //_entities - не обнуляется для работы entlong.IsAlive
             }
         }
-        //public void Clear() { }
         #endregion
 
         #region Getters

src/EcsWorld.static.cs

@@ -147,10 +147,7 @@ namespace DCFApixels.DragonECS
             private static short _recycledItemsCount;
             private static readonly IEcsWorldComponent<T> _interface = EcsWorldComponentHandler<T>.instance;
             private static readonly Abstract _controller = new Abstract();
-            static WorldComponentPool()
+
-            {
-                _allWorldComponentPools.Add(_controller);
-            }
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
             public static ref T GetItem(int itemIndex)
             {// ts

src/Injections/Injector.cs

@@ -357,6 +357,12 @@ namespace DCFApixels.DragonECS
                     instance.Inject(_injectedData);
                 }
             }
+            
+            internal static void Clear()
+            {
+                _Empty_Internal._injections.Clear();
+                _Empty_Internal._nodes.Clear();
+            }
         }
         #endregion
     }