Quick answer: Total component size per entity must fit in a 16KB chunk. Split rarely-co-accessed data into separate archetypes or use IComponentData for “cold” data.

A DOTS-based game adds 32 components to one mega-entity. EntityManager.CreateArchetype throws InvalidOperationException about chunk capacity. Each archetype has a strict per-chunk limit.

Chunk Memory Layout

ECS stores entities in 16KB chunks. Each chunk holds an integer number of entities whose total component size fits. Too-large entities = 1 entity per chunk = wasted memory and crash potential when component count overflows internal limits.

Audit Component Sizes

EntityManager em = ...;
ArchetypeChunk[] chunks = em.GetAllChunks(Allocator.Temp);
Debug.Log($"Chunks: {chunks.Length}, entities/chunk: {chunks[0].Count}");

If entities/chunk is 1, your archetype is too fat. Inspect each component’s size and prune.

Split Cold Data

// Hot data: queried every frame
public struct Position : IComponentData { public float3 Value; }
public struct Velocity : IComponentData { public float3 Value; }

// Cold data: rarely accessed, separate archetype
public struct DescriptionMetadata : IComponentData
{
    public FixedString128Bytes Name;
    public FixedString512Bytes Lore;
}

Pair only when accessed together. Cold metadata in a separate archetype that you query rarely.

Shared Components for Identity

For configuration-like data (faction, model index), use ISharedComponentData. Shared data isn’t stored per-entity in chunk; instead, archetypes split by shared value. Much smaller per-entity footprint.

Dynamic Buffers for Lists

Replace fixed arrays with IBufferElementData. Buffer storage is external, not in the chunk. Keeps the archetype small.

Verifying

Re-architect mega-entity. Chunks hold ~64 entities each. Memory profiler shows compact chunks. Job query times within budget.

“ECS chunks are a fixed cake size. Slice your data wisely.”

Use the Entity Hierarchy & Inspector windows in editor to view archetype size live — catches bloat as you add components.