unity-ecs-dots

Unity ECS / DOTS (Data-Oriented Technology Stack)

Based on Unity 6.3 LTS (6000.3) -- Entities 1.3, Burst 1.8, Jobs package

Core Concepts

ECS (Entity Component System) is Unity's data-oriented framework. It replaces the GameObject/MonoBehaviour model with a cache-friendly, high-performance architecture.

ECS vs MonoBehaviour

Aspect	MonoBehaviour	ECS
Identity	GameObject (heavy, managed)	Entity (lightweight int ID)
Data	Class fields on components	Unmanaged structs (IComponentData)
Logic	Methods on MonoBehaviour	Systems (ISystem / SystemBase)
Memory layout	Scattered across heap	Contiguous chunks by archetype
Threading	Main thread only	Jobs + Burst for parallel work

Entities

Entities are lightweight identifiers (an index + version integer). They have no behavior and no data -- they are handles used to associate components.

Components (IComponentData)

Components are unmanaged structs with no methods. They hold only data.

using Unity.Entities;

public struct Speed : IComponentData
{
    public float Value;
}

public struct Health : IComponentData
{
    public float Current;
    public float Max;
}

Archetypes and Chunks

An archetype is a unique combination of component types. All entities with the same set of components share an archetype. Entities are stored in chunks (16 KB blocks) grouped by archetype, enabling cache-efficient iteration.

World and EntityManager

A World contains an EntityManager and a set of systems. The default world is created automatically. EntityManager is the primary API for creating/destroying entities and adding/removing components.

Baking and SubScene Workflow

Baking converts authoring GameObjects into runtime entities. This is a one-way conversion that happens at build time or when a SubScene is loaded in the Editor.

Baker

using Unity.Entities;

// Authoring component (MonoBehaviour on GameObject)
public class SpeedAuthoring : MonoBehaviour
{
    public float speed;
}

// Baker converts authoring data to ECS components
public class SpeedBaker : Baker<SpeedAuthoring>
{
    public override void Bake(SpeedAuthoring authoring)
    {
        var entity = GetEntity(TransformUsageFlags.Dynamic);
        AddComponent(entity, new Speed { Value = authoring.speed });
    }
}

SubScene

• SubScenes contain GameObjects that are baked into entities at build time
• At runtime, entity data streams in efficiently (no GameObject overhead)
• In the Editor, SubScenes can be opened for editing (shows GameObjects) or closed (shows baked entities)
• Always place ECS-managed objects inside a SubScene

TransformUsageFlags

Flag	Use
Dynamic	Entity moves at runtime (gets LocalTransform, LocalToWorld)
Renderable	Entity is rendered but not moved by code
WorldSpace	Entity uses world-space transform only
None	No transform components added

Systems

Systems contain all logic. They iterate over entities that match a component query.

ISystem (Recommended)

ISystem is the modern, unmanaged system type. It is Burst-compatible and should be preferred over SystemBase.

using Unity.Burst;
using Unity.Entities;
using Unity.Mathematics;
using Unity.Transforms;

[BurstCompile]
public partial struct MovementSystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        state.RequireForUpdate<Speed>();
    }

    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        float deltaTime = SystemAPI.Time.DeltaTime;

        foreach (var (transform, speed) in
            SystemAPI.Query<RefRW<LocalTransform>, RefRO<Speed>>())
        {
            transform.ValueRW.Position +=
                new float3(0, 0, speed.ValueRO.Value * deltaTime);
        }
    }

    [BurstCompile]
    public void OnDestroy(ref SystemState state) { }
}

Key points:

• Must be a partial struct
• Use [BurstCompile] on the struct and each method
• OnCreate, OnUpdate, OnDestroy receive ref SystemState
• state.RequireForUpdate<T>() -- system only runs when T exists
• SystemAPI.Query<T>() -- type-safe foreach iteration

SystemBase (Managed, Legacy)

SystemBase is a managed class-based system. It supports managed code but cannot be Burst-compiled at the system level. Use ISystem for all new code. SystemBase uses Entities.ForEach() lambda syntax instead of SystemAPI.Query.

SystemGroup and Update Ordering

Systems are organized into groups that update in a defined order:

InitializationSystemGroup
  -> BeginInitializationEntityCommandBufferSystem
SimulationSystemGroup (default group)
  -> BeginSimulationEntityCommandBufferSystem
  -> [Your systems go here by default]
  -> EndSimulationEntityCommandBufferSystem
PresentationSystemGroup
  -> BeginPresentationEntityCommandBufferSystem

Control ordering with attributes:

[UpdateInGroup(typeof(SimulationSystemGroup))]
[UpdateBefore(typeof(OtherSystem))]
[UpdateAfter(typeof(AnotherSystem))]
public partial struct MySystem : ISystem { }

SystemAPI

SystemAPI provides static methods for safe, Burst-compatible access:

Method	Purpose
SystemAPI.Query<T1, T2>()	Iterate matching entities
SystemAPI.Time	Access TimeData (DeltaTime, ElapsedTime)
SystemAPI.GetSingleton<T>()	Get singleton component value
SystemAPI.SetSingleton<T>(value)	Set singleton component value
SystemAPI.GetComponent<T>(entity)	Read component from entity
SystemAPI.SetComponent<T>(entity, value)	Write component on entity
SystemAPI.HasComponent<T>(entity)	Check if entity has component
SystemAPI.GetComponentLookup<T>()	Get random-access lookup
SystemAPI.GetBuffer<T>(entity)	Get DynamicBuffer
SystemAPI.GetAspect<T>(entity)	Get aspect for entity

Components Deep Dive

IComponentData (Unmanaged Struct)

The fundamental component type. Must be an unmanaged struct (no reference types, no managed arrays).

ISharedComponentData

Shared across entities -- entities with the same shared component value are grouped into the same chunk. Changing a shared component value is a structural change.

public struct TeamId : ISharedComponentData
{
    public int Value;
}

IBufferElementData (DynamicBuffer)

Variable-length arrays attached to entities.

[InternalBufferCapacity(8)]
public struct DamageEvent : IBufferElementData
{
    public float Value;
    public Entity Source;
}

// Usage in a system
foreach (var (buffer, entity) in SystemAPI.Query<DynamicBuffer<DamageEvent>>()
    .WithEntityAccess())
{
    for (int i = 0; i < buffer.Length; i++)
        totalDamage += buffer[i].Value;
    buffer.Clear();
}

ICleanupComponentData

Persists after entity destruction. Used for cleanup logic (e.g., releasing native resources). The entity is not fully destroyed until all cleanup components are removed.

IEnableableComponent

Components that can be toggled on/off without structural changes (no chunk moves).

public struct Stunned : IComponentData, IEnableableComponent { }

// Toggle in system
SystemAPI.SetComponentEnabled<Stunned>(entity, true);
bool isStunned = SystemAPI.IsComponentEnabled<Stunned>(entity);

Tag Components

Zero-size structs used purely for filtering queries. No fields -- zero memory cost per entity.

public struct IsPlayer : IComponentData { }

Common Patterns

Creating and Destroying Entities

// Direct creation (structural change -- main thread only)
Entity e = entityManager.CreateEntity(typeof(Speed), typeof(Health));

// Preferred: use EntityCommandBuffer for deferred structural changes
var ecb = new EntityCommandBuffer(Allocator.TempJob);
Entity e2 = ecb.CreateEntity();
ecb.AddComponent(e2, new Speed { Value = 5f });
ecb.Playback(entityManager);
ecb.Dispose();

EntityCommandBuffer (ECB)

Structural changes (create/destroy entity, add/remove component) cannot happen during iteration. Use ECB to defer them. See references/ecs-api.md for full ECB API.

System-Managed ECB (Preferred)

[BurstCompile]
public partial struct SpawnSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var ecbSingleton = SystemAPI.GetSingleton<
            EndSimulationEntityCommandBufferSystem.Singleton>();
        var ecb = ecbSingleton.CreateCommandBuffer(state.WorldUnmanaged);
        // ecb is played back automatically -- no Playback/Dispose needed
        foreach (var spawner in SystemAPI.Query<RefRW<Spawner>>())
        {
            if (spawner.ValueRO.Timer <= 0)
            {
                ecb.Instantiate(spawner.ValueRO.Prefab);
                spawner.ValueRW.Timer = spawner.ValueRO.Interval;
            }
        }
    }
}

Singleton Components

Use when exactly one entity has a given component. Access via SystemAPI.GetSingleton<T>() / SystemAPI.SetSingleton<T>(value) / SystemAPI.GetSingletonRW<T>(). Useful for global config, game state, and similar one-of-a-kind data.

Aspects (IAspect)

Aspects group related components into a single access wrapper with optional methods.

public readonly partial struct CharacterAspect : IAspect
{
    public readonly RefRW<LocalTransform> Transform;
    public readonly RefRO<Speed> Speed;
    public readonly RefRW<Health> Health;

    public void Move(float3 direction, float deltaTime)
    {
        Transform.ValueRW.Position +=
            direction * Speed.ValueRO.Value * deltaTime;
    }
}

// Use in system
foreach (var character in SystemAPI.Query<CharacterAspect>())
{
    character.Move(new float3(1, 0, 0), deltaTime);
}

Jobs System

IJobEntity (Recommended)

Automatically generates an EntityQuery from the Execute parameter types.

[BurstCompile]
public partial struct MoveJob : IJobEntity
{
    public float DeltaTime;

    void Execute(ref LocalTransform transform, in Speed speed)
    {
        transform.Position += new float3(0, 0, speed.Value * DeltaTime);
    }
}

// Schedule from system
[BurstCompile]
public partial struct MoveSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        new MoveJob
        {
            DeltaTime = SystemAPI.Time.DeltaTime
        }.ScheduleParallel();
    }
}

IJobChunk (Low-Level)

Manual chunk iteration for maximum control. See references/jobs-burst.md for full examples.

Job Scheduling

Method	Behavior
Run()	Execute on main thread (no job scheduling)
Schedule()	Single-threaded job on worker thread
ScheduleParallel()	Multi-threaded across chunks

ECB in Parallel Jobs

[BurstCompile]
public partial struct DestroyDeadJob : IJobEntity
{
    public EntityCommandBuffer.ParallelWriter ECB;

    void Execute([ChunkIndexInQuery] int sortKey, in Health health, Entity entity)
    {
        if (health.Current <= 0)
            ECB.DestroyEntity(sortKey, entity);
    }
}

Burst Compiler

The Burst compiler translates IL/.NET bytecode into highly optimized native code using LLVM.

Usage

Add [BurstCompile] to ISystem structs (and each method) and IJobEntity structs. Burst compiles them to optimized native code via LLVM.

Restrictions

• No managed types (no class, string, List<T>, managed arrays)
• No allocations (no new for reference types)
• No try/catch/finally
• No virtual methods or interfaces (except job interfaces)
• No static mutable fields (use SharedStatic<T> instead)
• Must use NativeContainer types for collections

Unity.Mathematics

Burst-optimized math library replacing UnityEngine.Mathf and Vector3:

using Unity.Mathematics;

float3 position = new float3(1, 2, 3);
quaternion rot = quaternion.Euler(0, math.PI, 0);
float dist = math.distance(a, b);
float3 dir = math.normalize(b - a);
float val = math.lerp(0f, 1f, 0.5f);

UnityEngine	Unity.Mathematics
Vector3	float3
Vector2	float2
Quaternion	quaternion
Mathf.Lerp	math.lerp
Mathf.Sin	math.sin
Matrix4x4	float4x4

Anti-Patterns

What	Why It's Wrong	Fix
Using SystemBase when ISystem works	Cannot Burst-compile system, heap allocations	Use ISystem (partial struct) with [BurstCompile]
Structural changes during iteration	Invalidates iterators, causes exceptions	Use EntityCommandBuffer for deferred changes
Structural changes in parallel jobs without ECB	Race conditions, crashes	Use EntityCommandBuffer.ParallelWriter with sort key
Managed types in Burst-compiled code	Burst cannot compile managed types	Use unmanaged structs, FixedString, NativeContainer
Missing [BurstCompile] on ISystem	System runs as managed code, loses performance	Add [BurstCompile] to struct and all methods
Allocating NativeArray every frame without disposing	Memory leak	Allocate with Allocator.Temp or dispose in OnDestroy
Using UnityEngine.Mathf in Burst code	Not Burst-optimized	Use Unity.Mathematics.math
Forgetting state.RequireForUpdate<T>()	System runs even when no matching entities exist	Call in OnCreate to skip updates when unnecessary
Modifying SharedComponentData frequently	Each change is a structural change (chunk move)	Use regular IComponentData for frequently changing data
Using GetComponent in inner loops	Random access breaks cache coherency	Use SystemAPI.Query for linear iteration

Key API Quick Reference

Class / Struct	Key Members	Notes
EntityManager	CreateEntity, DestroyEntity, AddComponent<T>, RemoveComponent<T>, GetComponentData<T>, SetComponentData<T>	Main-thread only; structural changes
EntityCommandBuffer	CreateEntity, DestroyEntity, AddComponent, RemoveComponent, Instantiate, Playback	Deferred structural changes
ECB.ParallelWriter	Same as ECB but with sortKey parameter	Thread-safe for parallel jobs
SystemAPI	Query<T>, Time, GetSingleton<T>, GetComponent<T>, GetComponentLookup<T>	Static access from systems
EntityQuery	ToEntityArray, ToComponentDataArray<T>, CalculateEntityCount	Bulk operations
IComponentData	(marker interface)	Unmanaged struct components
IBufferElementData	(marker interface)	Dynamic buffer elements
DynamicBuffer<T>	Add, RemoveAt, Length, Clear, AsNativeArray	Variable-length per-entity arrays
IJobEntity	Execute(ref T1, in T2, ...)	Auto-generated query from params
IJobChunk	Execute(in ArchetypeChunk, ...)	Manual chunk iteration
World	DefaultGameObjectInjectionWorld, EntityManager	Container for systems + entities
RefRW<T> / RefRO<T>	ValueRW / ValueRO	Read-write / read-only component refs

Related Skills

• unity-scripting -- MonoBehaviour scripting, coroutines, async/await
• unity-physics -- Physics engine, Rigidbody, colliders (for Unity Physics ECS package)
• unity-foundations -- GameObjects, Transforms, Scenes, Prefabs

Additional Resources

• See references/ecs-api.md for detailed Entity/Component API
• See references/jobs-burst.md for Jobs and Burst deep dive
• Unity Entities Manual
• Unity Burst Manual
• Unity Jobs Manual
• Unity Entities API Reference