release v3.0.1

- [opt] immediate entity creation/destruction and component addition/removal
- [opt] improve groupof performance
- [opt] improve tag performance
- [opt] improve spatial and temporal locality
- [feat] introduce archetype
- [feat] introduce batch add/remove components

see `migration_guide.md`

Author: JasonXuDeveloper

EasyEcs.Core/Archetype.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Runtime.CompilerServices;
 using EasyEcs.Core.Components;
 
@@ -8,6 +9,7 @@ namespace EasyEcs.Core;
 /// Archetype stores entities with the same component configuration.
 /// Uses tombstone pattern (-1) for safe iteration during modifications.
 /// Uses free list for O(1) tombstone slot reuse.
+/// Uses reverse lookup dictionary for O(1) removal.
 /// </summary>
 internal class Archetype
 {
@@ -20,13 +22,17 @@ internal class Archetype
     private int[] _freeSlots;
     private int _freeCount;
 
+    // Reverse lookup: entityId -> index in EntityIds array (O(1) removal)
+    private readonly Dictionary<int, int> _entityToIndex;
+
     private const int Tombstone = -1;
 
     public Archetype(in Tag componentMask, int initialCapacity = 1024)
     {
         ComponentMask = componentMask;
         EntityIds = new int[initialCapacity];
-        _freeSlots = new int[initialCapacity / 4]; // Start smaller, grow as needed
+        _freeSlots = new int[initialCapacity]; // Match capacity to avoid early resizing
+        _entityToIndex = new Dictionary<int, int>(initialCapacity);
         Count = 0;
         AliveCount = 0;
         _freeCount = 0;
@@ -39,10 +45,12 @@ public Archetype(in Tag componentMask, int initialCapacity = 1024)
     [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
     public void Add(int entityId)
     {
+        int slot;
+
         // Fast path: Reuse free slot from free list (O(1))
         if (_freeCount > 0)
         {
-            int slot = _freeSlots[--_freeCount];
+            slot = _freeSlots[--_freeCount];
             EntityIds[slot] = entityId;
             AliveCount++;
         }
@@ -55,55 +63,67 @@ public void Add(int entityId)
                 Array.Resize(ref EntityIds, EntityIds.Length * 2);
             }
 
-            EntityIds[Count++] = entityId;
+            slot = Count++;
+            EntityIds[slot] = entityId;
             AliveCount++;
         }
+
+        // Update reverse lookup for O(1) removal
+        _entityToIndex[entityId] = slot;
     }
 
     /// <summary>
     /// Remove an entity from this archetype.
+    /// O(1) removal using reverse lookup dictionary.
     /// Marks the slot as tombstone (-1) and adds to free list for O(1) reuse.
     /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
     public void Remove(int entityId)
     {
-        // Find and tombstone the entity
-        var span = EntityIds.AsSpan(0, Count);
-        int idx = span.IndexOf(entityId);
+        // O(1) lookup using reverse index
+        if (!_entityToIndex.TryGetValue(entityId, out int idx))
+            return;
 
-        if (idx >= 0)
-        {
-            EntityIds[idx] = Tombstone;
-            AliveCount--;
+        // Tombstone the slot
+        EntityIds[idx] = Tombstone;
+        AliveCount--;
 
-            // Add to free list for O(1) reuse
-            if (_freeCount >= _freeSlots.Length)
-            {
-                Array.Resize(ref _freeSlots, _freeSlots.Length * 2);
-            }
-            _freeSlots[_freeCount++] = idx;
+        // Remove from reverse lookup
+        _entityToIndex.Remove(entityId);
 
-            // Note: Auto-compaction is disabled to avoid unpredictable performance spikes mid-frame.
-            // Call Context.CompactArchetypes() manually during loading screens or maintenance windows
-            // to remove tombstones and reduce fragmentation.
+        // Add to free list for O(1) reuse
+        if (_freeCount >= _freeSlots.Length)
+        {
+            Array.Resize(ref _freeSlots, _freeSlots.Length * 2);
         }
+        _freeSlots[_freeCount++] = idx;
+
+        // Note: Auto-compaction is disabled to avoid unpredictable performance spikes mid-frame.
+        // Call Context.CompactArchetypes() manually during loading screens or maintenance windows
+        // to remove tombstones and reduce fragmentation.
     }
 
     /// <summary>
     /// Compact the array by removing all tombstones.
-    /// Clears the free list since all gaps are removed.
+    /// Clears the free list and rebuilds reverse lookup since all gaps are removed.
     /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveOptimization)]
     public void Compact()
     {
         int writeIdx = 0;
         var span = EntityIds.AsSpan(0, Count);
 
+        // Clear and rebuild reverse lookup
+        _entityToIndex.Clear();
+
         for (int readIdx = 0; readIdx < Count; readIdx++)
         {
-            if (span[readIdx] != Tombstone)
+            int entityId = span[readIdx];
+            if (entityId != Tombstone)
             {
-                EntityIds[writeIdx++] = EntityIds[readIdx];
+                EntityIds[writeIdx] = entityId;
+                _entityToIndex[entityId] = writeIdx;  // Rebuild reverse lookup
+                writeIdx++;
             }
         }
 

EasyEcs.Core/Components/TagRegistry.cs

@@ -4,7 +4,11 @@
 
 namespace EasyEcs.Core.Components;
 
-internal class TagRegistry
+/// <summary>
+/// Global component type registry. Thread-safe and shared across all Context instances.
+/// Component types are registered once globally and persist for the lifetime of the process.
+/// </summary>
+internal static class TagRegistry
 {
     private interface ITypeBitIndex
     {
@@ -14,10 +18,9 @@ private interface ITypeBitIndex
     private class TypeBitIndex<T> : ITypeBitIndex
     {
         // Volatile fields for cross-thread visibility
-        // Static instance shared across all Context instances by design
         internal volatile ushort BitIndex;  // Supports up to 65536 component types
         internal volatile bool IsRegistered;
-        public static TypeBitIndex<T> Instance = new();
+        public static readonly TypeBitIndex<T> Instance = new();
 
         public void Reset()
         {
@@ -26,31 +29,42 @@ public void Reset()
         }
     }
 
-    // Static lock for thread-safe registration across all Context instances
-    private static readonly object GlobalRegistrationLock = new();
+    // Global lock for thread-safe registration
+    private static readonly object GlobalLock = new();
 
-    public int TagCount;
-    private List<ITypeBitIndex> _tags = new();
+    // Global tag counter - thread-safe via lock
+    private static int _tagCount;
 
-    public void Clear()
+    // Track all registered tags for cleanup (primarily for testing scenarios)
+    private static readonly List<ITypeBitIndex> Tags = new();
+
+    /// <summary>
+    /// Clear all registered component types.
+    /// WARNING: Only use this in testing scenarios. This will invalidate all existing Tags and Archetypes.
+    /// </summary>
+    public static void Clear()
     {
-        // Zero-allocation iteration with direct method call
-        for (int i = 0; i < _tags.Count; i++)
+        lock (GlobalLock)
         {
-            _tags[i].Reset();
+            // Reset all registered types
+            for (int i = 0; i < Tags.Count; i++)
+            {
+                Tags[i].Reset();
+            }
+
+            Tags.Clear();
+            _tagCount = 0;
         }
-
-        _tags.Clear();
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public bool HasTag<T>() where T : struct
+    public static bool HasTag<T>() where T : struct
     {
         return TypeBitIndex<T>.Instance.IsRegistered;
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public ushort GetTagBitIndex<T>() where T : struct
+    public static ushort GetTagBitIndex<T>() where T : struct
     {
         var instance = TypeBitIndex<T>.Instance;
         if (!instance.IsRegistered)
@@ -62,7 +76,7 @@ public ushort GetTagBitIndex<T>() where T : struct
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public bool TryGetTagBitIndex<T>(out ushort bitIndex) where T : struct
+    public static bool TryGetTagBitIndex<T>(out ushort bitIndex) where T : struct
     {
         var instance = TypeBitIndex<T>.Instance;
         if (!instance.IsRegistered)
@@ -78,33 +92,33 @@ public bool TryGetTagBitIndex<T>(out ushort bitIndex) where T : struct
     /// <summary>
     /// Get existing tag index or register a new one if it doesn't exist.
     /// Supports up to 65536 component types (ushort max).
-    /// Thread-safe: uses static lock to protect shared TypeBitIndex across contexts.
+    /// Thread-safe: uses global lock for registration.
     /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public ushort GetOrRegisterTag<T>() where T : struct
+    public static ushort GetOrRegisterTag<T>() where T : struct
     {
         var instance = TypeBitIndex<T>.Instance;
 
         // Fast path: already registered (volatile read ensures visibility)
         if (instance.IsRegistered)
             return instance.BitIndex;
 
-        // Slow path: need to register (lock globally since TypeBitIndex is static)
-        lock (GlobalRegistrationLock)
+        // Slow path: need to register
+        lock (GlobalLock)
         {
             // Double-check after acquiring lock
             if (instance.IsRegistered)
                 return instance.BitIndex;
 
             // Register new tag - limited to 65536 component types (ushort max)
-            if (TagCount >= ushort.MaxValue)
+            if (_tagCount >= ushort.MaxValue)
                 throw new InvalidOperationException($"Maximum number of component types reached ({ushort.MaxValue})");
 
-            ushort bitIndex = (ushort)TagCount;
+            ushort bitIndex = (ushort)_tagCount;
             instance.BitIndex = bitIndex;
             instance.IsRegistered = true;  // Volatile write ensures visibility
-            TagCount++;
-            _tags.Add(instance);
+            _tagCount++;
+            Tags.Add(instance);
 
             return bitIndex;
         }

EasyEcs.Core/Context.Archetypes.cs

@@ -1,4 +1,3 @@
-using System;
 using System.Collections.Generic;
 using System.Runtime.CompilerServices;
 using EasyEcs.Core.Components;
@@ -30,8 +29,19 @@ internal Archetype GetOrCreateArchetype(in Tag componentMask)
                 archetype = new Archetype(in componentMask, initialCapacity: 1024);
                 Archetypes[componentMask] = archetype;
 
-                // Invalidate query cache (new archetype may match existing queries)
-                _queryCache.Clear();
+                // Incrementally update query cache: add new archetype to matching queries
+                // This is smarter than clearing the entire cache
+                foreach (var kvp in _queryCache)
+                {
+                    var queryTag = kvp.Key;
+                    var cachedList = kvp.Value;
+
+                    // Check if new archetype matches this cached query
+                    if ((componentMask & queryTag) == queryTag)
+                    {
+                        cachedList.Add(archetype);
+                    }
+                }
             }
 
             return archetype;

EasyEcs.Core/Context.cs

@@ -24,7 +24,6 @@ public partial class Context : IAsyncDisposable
 
     // Component storage
     internal Array[] Components;
-    internal readonly TagRegistry TagRegistry = new();
 
     // System storage (zero-allocation priority lists)
     private readonly PrioritySystemList<ExecuteSystemWrapper> _executeSystems = new();
@@ -466,7 +465,9 @@ public async ValueTask DisposeAsync()
         _initSystems.Clear();
         _endSystems.Clear();
 
-        TagRegistry.Clear();
+        // Note: TagRegistry is global and shared across all contexts.
+        // It is NOT cleared here to avoid breaking other Context instances.
+        // Only clear TagRegistry in isolated testing scenarios via TagRegistry.Clear().
 
         _activeEntityCount = 0;
         _disposed = true;

EasyEcs.Core/Entity.cs

@@ -321,7 +321,7 @@ public void RemoveComponents<T1, T2, T3, T4, T5, T6, T7, T8, T9>()
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public ComponentRef<T> GetComponent<T>() where T : struct, IComponent
     {
-        var idx = Context.TagRegistry.GetTagBitIndex<T>();
+        var idx = TagRegistry.GetTagBitIndex<T>();
         if (!Tag.HasBit(idx))
             throw new InvalidOperationException("Component not found");
 
@@ -338,7 +338,7 @@ public ComponentRef<T> GetComponent<T>() where T : struct, IComponent
     public bool TryGetComponent<T>(out ComponentRef<T> value) where T : struct, IComponent
     {
         value = default;
-        if (!Context.TagRegistry.TryGetTagBitIndex<T>(out var idx))
+        if (!TagRegistry.TryGetTagBitIndex<T>(out var idx))
             return false;
         if (!Tag.HasBit(idx))
             return false;
@@ -355,7 +355,7 @@ public bool TryGetComponent<T>(out ComponentRef<T> value) where T : struct, ICom
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public bool HasComponent<T>() where T : struct, IComponent
     {
-        if (Context.TagRegistry.TryGetTagBitIndex<T>(out var idx))
+        if (TagRegistry.TryGetTagBitIndex<T>(out var idx))
             return Tag.HasBit(idx);
         return false;
     }

EasyEcs.Core/Enumerators/GroupResultEnumerator.1.cs

@@ -33,7 +33,7 @@ public GroupResultEnumerator(Context context)
         _entityIndexInArchetype = 0;
         Current = default;
 
-        if (context.TagRegistry.TryGetTagBitIndex<T>(out var bitIdx))
+        if (TagRegistry.TryGetTagBitIndex<T>(out var bitIdx))
         {
             // Safely access Components array (may not be initialized yet)
             if (context.Components != null && bitIdx < context.Components.Length)
@@ -45,7 +45,7 @@ public GroupResultEnumerator(Context context)
                 queryTag.SetBit(bitIdx);
 
                 // Get matching archetypes from cache (O(1) after first access)
-                _matchingArchetypes = context.GetMatchingArchetypes(queryTag);
+                _matchingArchetypes = context.GetMatchingArchetypes(in queryTag);
             }
         }
     }

EasyEcs.Core/Enumerators/GroupResultEnumerator.2.cs

@@ -32,8 +32,8 @@ public GroupResultEnumerator(Context context)
         _entityIndexInArchetype = 0;
         Current = default;
 
-        if (context.TagRegistry.TryGetTagBitIndex<T1>(out var bitIdx1) &&
-            context.TagRegistry.TryGetTagBitIndex<T2>(out var bitIdx2))
+        if (TagRegistry.TryGetTagBitIndex<T1>(out var bitIdx1) &&
+            TagRegistry.TryGetTagBitIndex<T2>(out var bitIdx2))
         {
             if (context.Components != null &&
                 bitIdx1 < context.Components.Length &&
@@ -46,7 +46,7 @@ public GroupResultEnumerator(Context context)
                 queryTag.SetBit(bitIdx1);
                 queryTag.SetBit(bitIdx2);
 
-                _matchingArchetypes = context.GetMatchingArchetypes(queryTag);
+                _matchingArchetypes = context.GetMatchingArchetypes(in queryTag);
             }
         }
     }

EasyEcs.Core/Enumerators/GroupResultEnumerator.3.cs

@@ -35,9 +35,9 @@ public GroupResultEnumerator(Context context)
         _entityIndexInArchetype = 0;
         Current = default;
 
-        if (context.TagRegistry.TryGetTagBitIndex<T1>(out var bitIdx1) &&
-            context.TagRegistry.TryGetTagBitIndex<T2>(out var bitIdx2) &&
-            context.TagRegistry.TryGetTagBitIndex<T3>(out var bitIdx3))
+        if (TagRegistry.TryGetTagBitIndex<T1>(out var bitIdx1) &&
+            TagRegistry.TryGetTagBitIndex<T2>(out var bitIdx2) &&
+            TagRegistry.TryGetTagBitIndex<T3>(out var bitIdx3))
         {
             if (context.Components != null &&
                 bitIdx1 < context.Components.Length &&
@@ -53,7 +53,7 @@ public GroupResultEnumerator(Context context)
                 queryTag.SetBit(bitIdx2);
                 queryTag.SetBit(bitIdx3);
 
-                _matchingArchetypes = context.GetMatchingArchetypes(queryTag);
+                _matchingArchetypes = context.GetMatchingArchetypes(in queryTag);
             }
         }
     }