ecs-fundamentals-isystem-default

ISystem vs SystemBase — Senior Patterns

Entities 1.x gives two system base types: ISystem (unmanaged value-type system, Burst-compatible) and SystemBase (managed class). They look interchangeable in a tutorial, but at scale the choice decides whether a system is on the hot path or a frame-time anchor. Default to ISystem. Pick SystemBase deliberately and document why.

Intent

Treat ISystem as the default execution model for runtime systems so Burst, zero-GC operation, and predictable scheduling are the default — not an opt-in that gets forgotten.

Use when

• Authoring any new runtime system in Entities 1.x. There is no scenario where "I'll write a SystemBase because it feels like normal C#" is the right answer in production code.
• The system body can be expressed without managed references (no Animator, Toggle, AudioSource, GameObject, string interpolation, List<T>, Dictionary<,>).
• You want [BurstCompile] on OnCreate / OnUpdate — i.e. the typical case.
• Entity counts at runtime are anything above "a handful" — per-system managed allocation in SystemBase compounds across systems and shows up as steady GC pressure.

Avoid when

• The system genuinely must hold managed references as fields (a live Animator, a Unity Toggle, an AudioSource, a MonoBehaviour it talks to). ISystem structs cannot hold managed fields safely.
• The system needs coroutines, async/await on the system class itself, or other managed orchestration that ISystem's value-type lifetime can't carry.
• You're writing throwaway editor scaffolding where Burst friction outweighs the win — but flag it as scaffolding and delete it before shipping.

In all three cases the right move is a small SystemBase with a one-line comment explaining why ISystem doesn't fit, sitting adjacent to ISystem peers in the same system group.

Senior pattern

using Unity.Burst;
using Unity.Entities;

[BurstCompile]
public partial struct FooSystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        // The prerequisite contract for this system. See entity-query-patterns-requireforupdate-gating.
        state.RequireForUpdate<FooConfig>();
    }

    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var config = SystemAPI.GetSingleton<FooConfig>();
        // ... unmanaged work, jobs, ECB usage, etc.
    }
}