entity-query-patterns-systemapi-query

What problem does it solve?

This guide helps developers avoid silent “system runs but nothing changes” bugs and performance bottlenecks by teaching the correct main-thread iteration pattern for Unity DOTS using SystemAPI.Query and strict RefRO/RefRW access intent.

Core Features & Use Cases

• RefRO/RefRW intent discipline: Use RefRO for read-only components and RefRW only for values you genuinely write, so the loop expresses correct access and avoids scheduling/parallelism issues.
• Refined query filtering: Apply composable filters like WithAll, WithNone, WithAny, WithEntityAccess, and enableable-component options to precisely target the intended archetypes.
• Safety against structural-change traps: Prevent invalid iterators and skipped/duplicated entities by avoiding EntityManager structural mutations inside the foreach and using an ECB-based approach instead.
• Promotion guidance: Know when to stay on SystemAPI.Query versus when to move to IJobEntity for large entity counts or heavier per-entity work.

Quick Start

Ask an AI to review your ISystem OnUpdate and explain whether your SystemAPI.Query tuple correctly uses RefRO vs RefRW and whether you’re risking structural changes inside the foreach.