⚙️ Lesson 4.3: Systems & Queries — ISystem & SystemAPI

ISystem vs SystemBase

ECS offers two ways to write a system. ISystem is an unmanaged struct system: it can be Burst-compiled end to end and is the default you should reach for. SystemBase is a managed class system — slower, not Burst-compiled itself, but able to touch managed objects and the classic Unity API when you genuinely need to. The guidance is simple: write ISystem unless you must use managed data, in which case use SystemBase.

Systems are discovered and instantiated automatically — you don't new them or attach them to GameObjects. Define one and Unity creates it in the default world and ticks it every frame in the right group.

Anatomy of a System

Here is a complete movement system — the runtime cousin of the taste you saw in Lesson 4.1. Note the partial struct (source generators complete it), the [BurstCompile] on both the struct and its methods, and the ref SystemState that gives access to the world:

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

[BurstCompile]
public partial struct MovementSystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        // Don't run this system until at least one Velocity entity exists.
        state.RequireForUpdate<Velocity>();
    }

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

        foreach (var (transform, velocity) in
                 SystemAPI.Query<RefRW<LocalTransform>, RefRO<Velocity>>())
        {
            transform.ValueRW.Position += velocity.ValueRO.Value * dt;
        }
    }

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

• OnCreate runs once — set up queries and requirements here.
• OnUpdate runs every frame the system is active.
• RequireForUpdate<T>() skips OnUpdate entirely when no matching entity exists — cheap and tidy.

Querying with SystemAPI

The heart of a system is the query. SystemAPI.Query<…>() returns exactly the entities that have all the listed components, and you iterate them with a normal foreach. The wrappers declare your access:

• RefRW<T> — read/write access (use .ValueRW).
• RefRO<T> — read-only access (use .ValueRO); lets the system parallelise reads.
• EnabledRefRW<T>, RefRW with tags, Entity itself — you can also pull the entity handle into the loop.

SystemAPI is the entry point for more than queries: SystemAPI.Time.DeltaTime, SystemAPI.GetSingleton<T>(), SystemAPI.GetComponent<T>(entity), and component lookups all hang off it. Behind the scenes the source generator turns your Query call into real chunk iteration — the packed-array walk from Lesson 4.1's diagram. You write a foreach; you get cache-friendly bulk processing.

💡 Filter with tags. Add a tag to the query type list to narrow it: SystemAPI.Query<RefRW<LocalTransform>>().WithAll<Enemy>() processes only entities also carrying the Enemy tag. WithNone<T>() and WithDisabled<T>() refine it further.

System Groups & Order

Systems don't run in a random order — they're organised into system groups that update in a fixed sequence each frame. The three top-level groups are:

Figure 1: The three top-level system groups, in the order they update each frame.

By default a system lands in the SimulationSystemGroup. You place it explicitly and order it relative to siblings with attributes:

using Unity.Entities;

[UpdateInGroup(typeof(SimulationSystemGroup))]
[UpdateAfter(typeof(SpawnSystem))]       // run after spawning...
[UpdateBefore(typeof(MovementSystem))]   // ...but before movement
public partial struct SteeringSystem : ISystem { /* ... */ }

This is how you guarantee that, say, forces are computed before velocities are integrated before positions are moved — the ECS equivalent of the job dependencies you built by hand in Lesson 3.2, but declared once and managed by the framework. The Systems window (Window ▸ Entities ▸ Systems) shows the full ordered tree at runtime.

Going Parallel with IJobEntity

The foreach in OnUpdate runs on the main thread. For heavy work over many entities, promote it to a Burst-compiled parallel job with IJobEntity — the ECS-native cousin of IJobParallelFor. You write one Execute describing what happens to a single entity's components, and schedule it across every core:

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

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

    // The parameters ARE the query: every entity with LocalTransform + Velocity.
    void Execute(ref LocalTransform transform, in Velocity velocity)
    {
        transform.Position += velocity.Value * DeltaTime;
    }
}

[BurstCompile]
public partial struct MovementSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var job = new MoveJob { DeltaTime = SystemAPI.Time.DeltaTime };
        // Schedule across all cores; carry the system's job dependency chain.
        state.Dependency = job.ScheduleParallel(state.Dependency);
    }
}

Two things to notice. First, IJobEntity infers the query from the Execute parameters — ref/in mirror RefRW/RefRO. Second, you don't call Complete() here: you assign the handle to state.Dependency, and ECS completes it for you at the right moment (before any system that needs the result). This is the same "schedule early, complete late" discipline, now automated by the framework. This is exactly how the 25,600-entity scene in Lesson 4.1 moves at full frame rate.

Structural Changes: EntityCommandBuffer

Remember from Lesson 4.2 that structural changes — creating, destroying, adding/removing components — can't happen safely mid-job, because they'd move entities between chunks while other threads read them. The solution is the EntityCommandBuffer (ECB): you record the changes during the frame and play them back at a safe point.

[BurstCompile]
public void OnUpdate(ref SystemState state)
{
    // A command buffer that plays back at the start of the next simulation step.
    var ecb = SystemAPI.GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>()
                       .CreateCommandBuffer(state.WorldUnmanaged);

    foreach (var (health, entity) in
             SystemAPI.Query<RefRO<Health>>().WithEntityAccess())
    {
        if (health.ValueRO.Current <= 0)
            ecb.DestroyEntity(entity);   // recorded now, executed at a safe point
    }
}

The ECB queues DestroyEntity, AddComponent, Instantiate, and friends; a dedicated ECB system plays them back between system updates when no job is touching the data. For one-off editing from a MonoBehaviour you can also create a standalone new EntityCommandBuffer(Allocator.TempJob), record, then Playback(entityManager) and Dispose(). Either way: never do structural changes directly inside a parallel job — record them into an ECB.

Hands-on Challenge

Summary

🚀 What's Next?

You've been creating entities in code. Real projects author them visually and convert them at build time. In Lesson 4.4: Baking — From GameObjects to Entities you'll use SubScenes and Bakers to turn designer-friendly GameObjects into runtime entities.