Merge pull request #3 from JasonXuDeveloper/claude/ecs-framework-multicore-011CUoqcaWaToLFchjwugUUG

Build ECS framework for multi-core servers

Author: JasonXuDeveloper

EasyEcs.Core/Archetype.cs

@@ -0,0 +1,121 @@
+using System;
+using System.Runtime.CompilerServices;
+using EasyEcs.Core.Components;
+
+namespace EasyEcs.Core;
+
+/// <summary>
+/// Archetype stores entities with the same component configuration.
+/// Uses tombstone pattern (-1) for safe iteration during modifications.
+/// </summary>
+internal class Archetype
+{
+    public Tag ComponentMask;
+    public int[] EntityIds;
+    public int Count;          // Total slots (including tombstones)
+    public int AliveCount;     // Living entities only
+
+    private const int Tombstone = -1;
+
+    public Archetype(in Tag componentMask, int initialCapacity = 1024)
+    {
+        ComponentMask = componentMask;
+        EntityIds = new int[initialCapacity];
+        Count = 0;
+        AliveCount = 0;
+    }
+
+    /// <summary>
+    /// Add an entity to this archetype.
+    /// Reuses tombstone slots first, then appends.
+    /// </summary>
+    [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
+    public void Add(int entityId)
+    {
+        // Try to find a tombstone slot for reuse
+        var span = EntityIds.AsSpan(0, Count);
+        int emptySlot = span.IndexOf(Tombstone);
+
+        if (emptySlot >= 0)
+        {
+            // Reuse tombstone slot
+            EntityIds[emptySlot] = entityId;
+            AliveCount++;
+        }
+        else
+        {
+            // No tombstones available, append to end
+            if (Count >= EntityIds.Length)
+            {
+                // Grow array (doubling strategy)
+                Array.Resize(ref EntityIds, EntityIds.Length * 2);
+            }
+
+            EntityIds[Count++] = entityId;
+            AliveCount++;
+        }
+    }
+
+    /// <summary>
+    /// Remove an entity from this archetype.
+    /// Marks the slot as tombstone (-1) for safe iteration.
+    /// </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);
+
+        if (idx >= 0)
+        {
+            EntityIds[idx] = Tombstone;
+            AliveCount--;
+
+            // Optional: Compact if heavily fragmented (>50% tombstones)
+            // This prevents memory waste while keeping iteration safe
+            if (AliveCount > 0 && AliveCount < Count / 2)
+            {
+                Compact();
+            }
+        }
+    }
+
+    /// <summary>
+    /// Compact the array by removing all tombstones.
+    /// Only called when heavily fragmented (>50% dead slots).
+    /// </summary>
+    [MethodImpl(MethodImplOptions.AggressiveOptimization)]
+    public void Compact()
+    {
+        int writeIdx = 0;
+        var span = EntityIds.AsSpan(0, Count);
+
+        for (int readIdx = 0; readIdx < Count; readIdx++)
+        {
+            if (span[readIdx] != Tombstone)
+            {
+                EntityIds[writeIdx++] = EntityIds[readIdx];
+            }
+        }
+
+        Count = writeIdx;
+        // AliveCount should already match Count after compaction
+    }
+
+    /// <summary>
+    /// Get a read-only span of entity IDs for iteration.
+    /// Includes tombstones - iterator must skip -1 values.
+    /// </summary>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ReadOnlySpan<int> GetEntitySpan() => new ReadOnlySpan<int>(EntityIds, 0, Count);
+
+    /// <summary>
+    /// Get fragmentation ratio (percentage of tombstones).
+    /// </summary>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public float GetFragmentation()
+    {
+        return Count > 0 ? 1.0f - (float)AliveCount / Count : 0f;
+    }
+}

EasyEcs.Core/Commands/AddComponentCommand.cs

@@ -1,19 +1,83 @@
+using System;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
 namespace EasyEcs.Core.Components;
 
+/// <summary>
+/// Optimized component reference with packed ID+version and Unsafe access.
+/// 24 bytes total (down from 32+).
+/// </summary>
 public readonly struct ComponentRef<T> where T : struct, IComponent
 {
-    private readonly int _index;
-    private readonly byte _bitIndex;
+    // Pack entity ID (lower 32 bits) + version (upper 32 bits)
+    private readonly long _packed;
+    private readonly ushort _componentIndex;  // Supports up to 65536 component types
     private readonly Context _context;
 
-    public ComponentRef(int index, byte bitIndex, Context context)
+    public ComponentRef(int entityId, int version, ushort componentIndex, Context context)
     {
-        _index = index;
-        _bitIndex = bitIndex;
+        _packed = ((long)version << 32) | (uint)entityId;
+        _componentIndex = componentIndex;
         _context = context;
     }
 
-    public ref T Value => ref ((T[])_context.Components[_bitIndex])[_index];
+    private int EntityId
+    {
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        get => (int)_packed;
+    }
+
+    private int Version
+    {
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        get => (int)(_packed >> 32);
+    }
+
+    public ref T Value
+    {
+        [MethodImpl(MethodImplOptions.AggressiveOptimization)]
+        get
+        {
+            int id = EntityId;
+            int version = Version;
+
+            // Validate version using Unsafe (zero bounds checks)
+            ref int actualVersion = ref Unsafe.Add(
+                ref MemoryMarshal.GetArrayDataReference(_context.EntityVersions),
+                id);
+
+            if (actualVersion != version)
+                ThrowEntityDestroyed();
+
+            // Lazy initialization: ensure component array exists
+            // This handles cases where TagRegistry static indices are shared across contexts
+            T[] componentArray = EnsureComponentArray();
+
+            return ref Unsafe.Add(
+                ref MemoryMarshal.GetArrayDataReference(componentArray),
+                id);
+        }
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private T[] EnsureComponentArray()
+    {
+        // Fast path: component array already initialized
+        if (_context.Components != null &&
+            _componentIndex < _context.Components.Length &&
+            _context.Components[_componentIndex] != null)
+        {
+            return Unsafe.As<T[]>(_context.Components[_componentIndex]);
+        }
+
+        // Slow path: need to initialize (happens when static TypeBitIndex is shared across contexts)
+        return _context.EnsureComponentArrayInitialized<T>(_componentIndex);
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static void ThrowEntityDestroyed() =>
+        throw new InvalidOperationException("Entity has been destroyed");
 
     public static implicit operator T(ComponentRef<T> componentRef)
     {