singleton-patterns-config-and-access

Singleton Patterns — Senior Patterns

A singleton in DOTS is just an entity with a component that exists exactly once in the world. SystemAPI.GetSingleton<T>() is the O(1) accessor. state.RequireForUpdate<T>() is the gate that keeps the system from firing before the singleton is baked. Together they are the senior idiom for config, registries, frame-scoped input snapshots, and any data that should not be modeled per-entity.

Intent

Model world-unique data as a single entity + component, accessed in O(1) from any system that depends on it, with a hard prerequisite contract that prevents first-frame races against scene baking.

Use when

• A component is conceptually unique per world: game config, controls registry, frame input snapshot, prefab collection, world bounds, debug settings.
• A system needs guaranteed access to that data and must not run until it exists.
• You'd otherwise write GetEntityQuery(...) and .GetSingleEntity() to fetch it — the Singleton API is faster (no query iteration) and clearer.
• One system writes the value (e.g. an input system snapshots controller state into InputState) and many systems read it; you want a read-only contract on the consumers.

Avoid when

• The data is per-entity (per-character config, per-faction tuning, per-region settings). Model as regular components on the relevant entities — a "singleton" of per-entity data is a misuse.
• Multiple instances are legitimately possible (e.g. multiple PlayerInput for split-screen). The singleton API throws on more than one — model it as a regular component and query for the matching entity explicitly.
• The "singleton" is a thin wrapper for true global mutable state that would be clearer as a static field. Rare — usually the singleton entity is still right because it survives world disposal and is visible to ECS systems; but be honest if the answer is actually a static.

Senior pattern — read-only consumer

using Unity.Burst;
using Unity.Entities;

public struct GameConfig : IComponentData
{
    public float Gravity;
    public Entity ProjectilePrefab;
}

[BurstCompile]
public partial struct ConfigConsumerSystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        // The prerequisite contract — see entity-query-patterns-requireforupdate-gating.
        state.RequireForUpdate<GameConfig>();
    }

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