entity-query-patterns-requireforupdate-gating

RequireForUpdate Gating — Senior Patterns

state.RequireForUpdate<T>() is the contract that says "this system has nothing to do until T exists in the world". When the contract isn't satisfied, the entire system is skipped — OnUpdate is not called, the scheduler doesn't even traverse it. This is strictly better than guarding inside OnUpdate, and it's the only correct guard against the first-frame race with subscene baking.

Intent

Make every system's prerequisites explicit, AND-combined at OnCreate, and free at runtime — so the system runs exactly when it has work to do, and never throws on a half-initialized world.

Use when

• Authoring any system. As a convention, every system declares at least one RequireForUpdate — the list is the system's prerequisite contract. A system with no gate is a system that "runs every frame regardless of state", which is almost never what you actually mean.
• A system depends on a singleton existing (config, registry, input, prefab table). Without the gate, the first frame can fire before subscene baking finishes and GetSingleton<T>() throws.
• A system should only run when a feature is enabled. Bake an empty tag from an authoring toggle; gate the system on it. Toggling the authoring bool disables the entire feature with zero runtime overhead.
• A system needs multiple prerequisites — RequireForUpdate calls compose with AND semantics.

Avoid when

• The system genuinely must run every frame regardless of world state. Rare in practice — usually the right gate is "until the world is loaded" via a WorldLoadedTag or similar.
• The prerequisite is "any entity matching a complex query" (e.g. "at least one entity with both Damaged and Enabled"). Use the state.RequireForUpdate(query) overload, not the generic — see below.

Senior pattern — generic gates

using Unity.Burst;
using Unity.Entities;

[BurstCompile]
public partial struct CombatSystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        // Multiple RequireForUpdate calls AND together — system runs only when ALL satisfied.
        state.RequireForUpdate<GameConfig>();         // singleton must exist
        state.RequireForUpdate<EnableCombatFeature>(); // feature flag tag must exist
    }

    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var config = SystemAPI.GetSingleton<GameConfig>();
        // ... combat logic
    }
}