From 4728be1722cd66612948fb40ae805d35e581213d Mon Sep 17 00:00:00 2001
From: Lars <behethangames@gmail.com>
Date: Mon, 21 Oct 2024 23:15:49 +0200
Subject: [PATCH] Added docs and fixed test.

---
 src/Arch.Tests/WorldTest.cs |  9 +++++++--
 src/Arch/Core/Archetype.cs  | 10 ++++++----
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/src/Arch.Tests/WorldTest.cs b/src/Arch.Tests/WorldTest.cs
index 7138b26..130c7b9 100644
--- a/src/Arch.Tests/WorldTest.cs
+++ b/src/Arch.Tests/WorldTest.cs
@@ -240,9 +240,14 @@ public void CapacityTest()
     public void EnsureCapacity()
     {
         using var world = World.Create();
-        var archetype = world.EnsureCapacity(_entityGroup, 11000);
+        var amount = 11_000;
+        var archetype = world.EnsureCapacity(_entityGroup, amount);
+
+        // Calculation for capacity
+        var calculatedChunkSize = Archetype.GetChunkSizeInBytesFor(archetype.MinimumAmountOfEntitiesPerChunk, _entityGroup);
+        var entityCapacityPerChunk = Archetype.GetEntityCountFor(calculatedChunkSize, _entityGroup);
+        var requiredEntityCapacity = Math.Ceiling((float)amount / entityCapacityPerChunk) * entityCapacityPerChunk;
 
-        var requiredEntityCapacity = Archetype.GetEntityCountFor(Archetype.GetByteCountFor(archetype.MinimumAmountOfEntitiesPerChunk, _entityGroup), _entityGroup);
         That(world.Size, Is.EqualTo(0));
         That(world.Capacity, Is.EqualTo(archetype.EntityCapacity));
         That(archetype.EntityCount, Is.EqualTo(0));
diff --git a/src/Arch/Core/Archetype.cs b/src/Arch/Core/Archetype.cs
index 599fe86..a9f0306 100644
--- a/src/Arch/Core/Archetype.cs
+++ b/src/Arch/Core/Archetype.cs
@@ -283,7 +283,7 @@ internal Archetype(Signature signature)
         Types = signature;
 
         // Calculations
-        ChunkSizeInBytes = GetByteCountFor(MinimumAmountOfEntitiesPerChunk, signature);
+        ChunkSizeInBytes = GetChunkSizeInBytesFor(MinimumAmountOfEntitiesPerChunk, signature);
         EntitiesPerChunk = GetEntityCountFor(ChunkSizeInBytes, signature);
 
         // The bitmask/set
@@ -757,15 +757,17 @@ public sealed partial class Archetype
 {
 
     /// <summary>
-    ///     Calculates how many bytes are needed to store the <see cref="entityAmount"/>.
+    ///     Calculates the size of the memory in bytes required to store the number of <see cref="entityAmount"/>.
+    ///     The <see cref="BaseSize"/> (L1 cache size) is taken into account and, if necessary, rounded up to a multiple of this to ensure maximum cache performance.
+    ///     So if the number of <see cref="entityAmount"/> exceeds the <see cref="BaseSize"/> value, a multiple of this is used.
     /// </summary>
     /// <param name="entityAmount">The amount of entities.</param>
     /// <param name="types">The component structure of the <see cref="Arch.Core.Entity"/>'s.</param>
     /// <returns>The amount of bytes required to store the <see cref="Entity"/>s.</returns>
-    public unsafe static int GetByteCountFor(int entityAmount, Span<ComponentType> types)
+    public unsafe static int GetChunkSizeInBytesFor(int entityAmount, Span<ComponentType> types)
     {
         var entityBytes = (sizeof(Entity) + types.ToByteSize()) * entityAmount;
-        return (int)Math.Ceiling((float)entityBytes / BaseSize) * BaseSize;
+        return (int)Math.Ceiling((float)entityBytes / BaseSize) * BaseSize;  // Calculates and rounds to a multiple of BaseSize to store the number of entities
     }
 
     /// <summary>