singleton-access

What problem does it solve?

Prevents slow, error-prone ECS lookups by providing a direct way to access a guaranteed single entity or component value in O(1) time.

Core Features & Use Cases

• Read-only singleton access: Use SystemAPI.GetSingleton<T>() to fetch a copy of the singleton value for safe, non-mutating logic (e.g., reading global game config).
• Write access when needed: Use SystemAPI.GetSingletonRW<T>() for controlled mutation that correctly marks components dirty for change filtering (e.g., updating a global score or settings state).
• Entity handle access: Use SystemAPI.GetSingletonEntity<T>() when you need the entity reference itself (e.g., for destroying or adding components elsewhere).
• Correctness gate: Pair singleton access with state.RequireForUpdate<T>() to avoid runtime exceptions when the singleton entity might not exist yet.

Quick Start

Use a singleton component type with state.RequireForUpdate<YourSingletonComponent>() in OnCreate, then read it in OnUpdate via var value = SystemAPI.GetSingleton<YourSingletonComponent>(); to obtain the global configuration without query overhead.