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

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

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:

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

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);

Anti-Patterns

Key API Quick Reference

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