Merge pull request #10 from Juiix/feature/static-component-registry

feat(core): added static component registry, performance improvements…

Author: Juiix

DOCS.md

@@ -22,25 +22,11 @@
 
 EntitiesDb is built around a classic data-oriented ECS design:
 
-### **Entities**
-
-Lightweight integer IDs. They have no data themselves — components define the data.
-
-### **Components**
-
-Plain C# types (`struct`, `class`, `record`, etc). Stored densely in chunked arrays.
-
-### **Archetypes**
-
-Unique sets of components. Entities with the same component signature are grouped into the same chunk layout.
-
-### **Queries**
-
-Pull in chunks of entities matching component filters — the basis for all system updates.
-
-### **Source-Generated Iterators**
-
-`ForEach` methods generate strongly-typed, allocation-free iteration code.
+* **Entities**: Lightweight integer IDs. They have no data themselves — components define the data.
+* **Components**: Plain C# types (`struct`, `class`, `record`, etc). Stored densely in chunked arrays.
+* **Archetypes**: Unique sets of components. Entities with the same component signature are grouped into the same chunk layout.
+* **Queries**: Pull in chunks of entities matching component filters — the basis for all system updates.
+* **Source-Generated Iterators**: `ForEach` methods generate strongly-typed, allocation-free iteration code.
 
 ---
 
@@ -58,17 +44,17 @@ var options = new EntityDatabaseOptions(
 var db = new EntityDatabase(options);
 ```
 
-Each database is completely isolated, allowing multiple worlds.
-
 ---
 
 # Entities
 
 ```csharp
+// create entity
 var entity = db.Create(new Position(10, 10), new Health(100, 100));
-
 db.Exists(entity);      // true
-db.Destroy(entity.Id);  // destroy
+
+// destroy entity
+db.Destroy(entity);     // destroy
 db.Exists(entity);      // false
 ```
 
@@ -79,26 +65,27 @@ db.Exists(entity);      // false
 
 # Components
 
-Components are simple data types:
+Components are simple data types that can be `struct` or `class`:
 
 ```csharp
 public record struct Position(float X, float Y);
 public record struct Velocity(float Dx, float Dy);
 ```
+> *`class` components should be avoided when fast enumeration is a priority of the component*
 
 ### Add / Read / Write / Remove
 
 ```csharp
-db.Add(entity.Id, new Velocity(10, 10));
+db.Add(entity, new Velocity(10, 10));
 
-db.Has<Velocity>(entity.Id);                // true
+db.Has<Velocity>(entity);                // true
 
-db.Set(entity.Id, new Velocity(200, 200));  // overwrite component
+db.Set(entity, new Velocity(200, 200));  // overwrite component
 
-db.Remove<Velocity>(entity.Id);
+db.Remove<Velocity>(entity);
 
 // Read-only
-readonly ref var position = ref db.Read<Position>(entity.Id);
+ref readonly var position = ref db.Read<Position>(entity);
 
 // Write
 ref var pos = ref db.Write<Position>(entity.Id);
@@ -113,7 +100,7 @@ Buffers act like **inline component lists**, stored directly in the chunk.
 Only `unmanaged` types can be buffered.
 
 ```csharp
-[Buffer(8)]
+[Buffer(8)] // use the buffer attribute to mark a component as buffered and passing the inline buffer size
 public record struct InventoryItem(int Id, int Count);
 ```
 
@@ -126,7 +113,7 @@ var entity = db.Create(
     new[] {
         new InventoryItem(1, 1),
         new InventoryItem(2, 10)
-    } // Buffer must be the last argument
+    } // Buffers must be the last component arguments
 );
 ```
 
@@ -149,7 +136,7 @@ write.Add(new InventoryItem(3, 5));
 
 ## Tags
 
-Tags are **zero-data components** used for classification:
+Tags are **zero-data components** used for classification and filtering:
 
 ```csharp
 [Tag] public struct PlayerTag { }
@@ -241,12 +228,18 @@ query.ForEachChunk((int len,
 
 # Change Filter
 
+Enable change filtering with the `TrackChanges` attribute:
+```csharp
+[TrackChanges]
+public record struct Position(float X, float Y);
+```
+
 Only enumerate chunks whose components were written recently.
 
 ```csharp
 var query = db.QueryBuilder
     .WithAll<Position, SentPosition, PositionDelta>()
-    .WithChangeFilter<Position>()
+    .WithChangeFilter<Position>()                         // add change filter
     .Build();
 
 query.ForEach((in Position pos, ref SentPosition sent, ref PositionDelta delta) =>

README.md

@@ -10,13 +10,26 @@ EntitiesDb focuses on **raw performance**, **simple APIs**, and **zero external
 
 * **🚀 Fast** — Chunk-based, archetype-organized storage with SIMD-friendly handles
 * **🧩 Simple** — Define any type as a component and query with expressive filters
-* **📦 Self-Contained** — Multiple isolated databases/worlds
 * **🧵 Parallel-Ready** — Built-in multithreaded query execution and reduction
 * **0️⃣ GC-Friendly** — Minimal allocations, predictable memory layout
 * **📚 Documentation** — API reference and guides in [DOCS.md](./DOCS.md)
 
 ---
 
+# Features
+* Archetypes with cache-efficient chunking
+* Any type as a component
+* Component buffers for unmanaged types
+* High-performance component queries
+* Command buffers
+* Multithreaded queries
+* Manual archetype/chunk enumeration
+* Source generated delegate queries
+* Chunk change filters
+* SIMD-friendly
+
+---
+
 # Quick Start
 
 ```csharp

src/EntitiesDb.Benchmark/CreateWithOneComponent/EntitiesDb.cs

@@ -29,10 +29,9 @@ public void EntitiesDb_Bulk()
 		var entities = _entitiesDb.Entities;
 		entities.Reserve<Component1>(EntityCount);
 
-		var bulk = entities.GetBulkCreate<Component1>();
 		for (int i = 0; i < EntityCount; ++i)
 		{
-			entities.Create(in bulk, new Component1());
+			entities.Create(new Component1());
 		}
 	}
 }

src/EntitiesDb.Benchmark/SystemWithOneComponent/EntitiesDb.cs

@@ -10,7 +10,6 @@ public partial class SystemWithOneComponent
 	private class EntitiesDbContext : EntitiesDbBaseContext
 	{
 		public Query Query;
-		public Id<Component1> Id;
 
 		public EntitiesDbContext(int entityCount)
 		{
@@ -22,7 +21,6 @@ public EntitiesDbContext(int entityCount)
 			Query = Entities.QueryBuilder
 				.WithAll<Component1>()
 				.Build();
-			Id = Entities.ComponentRegistry.GetId<Component1>();
 		}
 	}
 

src/EntitiesDb.Benchmark/SystemWithTwoComponents/EntitiesDb.cs

@@ -10,7 +10,6 @@ public partial class SystemWithTwoComponents
 	private class EntitiesDbContext : EntitiesDbBaseContext
 	{
 		public Query Query;
-		public Ids<Component1, Component2> Ids;
 
 		public EntitiesDbContext(int entityCount) : base(6)
 		{
@@ -22,7 +21,6 @@ public EntitiesDbContext(int entityCount) : base(6)
 			Query = Entities.QueryBuilder
 				.WithAll<Component1, Component2>()
 				.Build();
-			Ids = Entities.ComponentRegistry.GetIds<Component1, Component2>();
 		}
 	}
 

src/EntitiesDb.Benchmark/SystemWithTwoComponentsVariedComposition/EntitiesDb.cs

@@ -10,7 +10,6 @@ public partial class SystemWithTwoComponentsVariedComposition
 	private class EntitiesDbContext : EntitiesDbBaseContext
 	{
 		public Query Query;
-		public Ids<Component1, Component2> Ids;
 
 		public EntitiesDbContext(int entityCount)
 		{
@@ -28,7 +27,6 @@ public EntitiesDbContext(int entityCount)
 			Query = Entities.QueryBuilder
 				.WithAll<Component1>()
 				.Build();
-			Ids = Entities.ComponentRegistry.GetIds<Component1, Component2>();
 		}
 	}
 

src/EntitiesDb.SourceGenerators/Model.cs

@@ -132,28 +132,27 @@ private static ForEachRenderModel BuildModel(InvocationCapture cap)
 			callArgs.Add(chunks ? "entityHandle" : "entityHandle[index]");
 		}
 
-		var offsetsName = parallel ? "_offsets" : "offsets";
 		for (int i = 0; i < comps.Count; i++)
 		{
 			var c = comps[i];
-			var ofs = "T" + i.ToString();
 			var baseVar = Utilities.Sanitize(c.Name) + "Handle";
+			var displayType = Utilities.ToDisplay(c.ComponentType);
 
 			string h;
 			switch (c.Kind)
 			{
 				case ParamKind.ComponentRef:
 				case ParamKind.ComponentWriteHandle:
-					h = "var " + baseVar + " = chunk.WriteHandle(" + offsetsName + "." + ofs + ");"; break;
+					h = "var " + baseVar + " = chunk.WriteHandle<" + displayType + ">();"; break;
 				case ParamKind.ComponentIn:
 				case ParamKind.ComponentReadHandle:
-					h = "var " + baseVar + " = chunk.ReadHandle(" + offsetsName + "." + ofs + ");"; break;
+					h = "var " + baseVar + " = chunk.ReadHandle<" + displayType + ">();"; break;
 				case ParamKind.WriteBuffer:
 				case ParamKind.WriteBufferHandle:
-					h = "var " + baseVar + " = chunk.WriteBufferHandle(" + offsetsName + "." + ofs + ");"; break;
+					h = "var " + baseVar + " = chunk.WriteBufferHandle<" + displayType + ">();"; break;
 				case ParamKind.ReadBuffer:
 				case ParamKind.ReadBufferHandle:
-					h = "var " + baseVar + " = chunk.ReadBufferHandle(" + offsetsName + "." + ofs + ");"; break;
+					h = "var " + baseVar + " = chunk.ReadBufferHandle<" + displayType + ">();"; break;
 				default:
 					h = ""; break;
 			}
@@ -176,9 +175,9 @@ private static ForEachRenderModel BuildModel(InvocationCapture cap)
 			}
 
 			if (c.Kind is ParamKind.WriteBuffer or ParamKind.ReadBuffer or ParamKind.WriteBufferHandle or ParamKind.ReadBufferHandle)
-				bufferedTypes.Add(Utilities.ToDisplay(c.ComponentType));
+				bufferedTypes.Add(displayType);
 			else
-				notBufferedTypes.Add(Utilities.ToDisplay(c.ComponentType));
+				notBufferedTypes.Add(displayType);
 		}
 
 		if (cap.HasState)

src/EntitiesDb.SourceGenerators/Rendering.ForEach.cs

@@ -51,35 +51,22 @@ public static string RenderForEach(ForEachRenderModel m)
 		// ComponentMeta assertions
 		if (m.BufferedTypes.Count > 0)
 		{
-			w.Append("global::EntitiesDb.ComponentMeta.AssertBuffered<")
+			w.Append("_ = global::EntitiesDb.ComponentBufferWritable<")
 			 .Append(string.Join(", ", m.BufferedTypes.ToArray()))
-			 .AppendLine(">();");
+			 .AppendLine(">.Check;");
 		}
 		if (m.NotBufferedTypes.Count > 0)
 		{
-			w.Append("global::EntitiesDb.ComponentMeta.AssertNotBuffered<")
+			w.Append("_ = global::EntitiesDb.ComponentSingleWritable<")
 			 .Append(string.Join(", ", m.NotBufferedTypes.ToArray()))
-			 .AppendLine(">();");
-		}
-
-		// ids
-		if (hasComponents)
-		{
-			w.Append("var ids = self.GetIds").Append(m.IdTypesJoined).AppendLine("();");
-			w.AppendLine("var all = Signature.FromIds(in ids);");
+			 .AppendLine(">.Check;");
 		}
 
 		// main loops
 		w.AppendLine("foreach (var archetype in self.EnumerateArchetypes())");
 		w.AppendLine("{");
 		w.Indent();
 
-		if (hasComponents)
-		{
-			w.AppendLine("if (!archetype.Signature.HasAll(in all)) continue;");
-			w.AppendLine("var offsets = archetype.GetOffsets(in ids);");
-		}
-
 		w.AppendLine("foreach (ref readonly var chunk in archetype)");
 		w.AppendLine("{");
 		w.Indent();

src/EntitiesDb.SourceGenerators/Rendering.ForEachChunk.cs

@@ -50,35 +50,22 @@ private static string RenderForEachChunk(ForEachRenderModel m)
 		// ComponentMeta assertions
 		if (m.BufferedTypes.Count > 0)
 		{
-			w.Append("global::EntitiesDb.ComponentMeta.AssertBuffered<")
+			w.Append("_ = global::EntitiesDb.ComponentBufferWritable<")
 			 .Append(string.Join(", ", m.BufferedTypes.ToArray()))
-			 .AppendLine(">();");
+			 .AppendLine(">.Check;");
 		}
 		if (m.NotBufferedTypes.Count > 0)
 		{
-			w.Append("global::EntitiesDb.ComponentMeta.AssertNotBuffered<")
+			w.Append("_ = global::EntitiesDb.ComponentSingleWritable<")
 			 .Append(string.Join(", ", m.NotBufferedTypes.ToArray()))
-			 .AppendLine(">();");
-		}
-
-		// ids
-		if (hasComponents)
-		{
-			w.Append("var ids = self.GetIds").Append(m.IdTypesJoined).AppendLine("();");
-			w.AppendLine("var all = Signature.FromIds(in ids);");
+			 .AppendLine(">.Check;");
 		}
 
 		// main loops
 		w.AppendLine("foreach (var archetype in self.EnumerateArchetypes())");
 		w.AppendLine("{");
 		w.Indent();
 
-		if (hasComponents)
-		{
-			w.AppendLine("if (!archetype.Signature.HasAll(in all)) continue;");
-			w.AppendLine("var offsets = archetype.GetOffsets(in ids);");
-		}
-
 		w.AppendLine("foreach (ref readonly var chunk in archetype)");
 		w.AppendLine("{");
 		w.Indent();