entity-query-patterns-systemapi-query

SystemAPI.Query Patterns — Senior Patterns

SystemAPI.Query<...>() with foreach is the senior default for main-thread iteration in ISystem. It's source-generated into a tight archetype-chunk loop, expresses read/write intent at the type level, and composes cleanly with .WithAll / .WithNone / .WithAny / .WithEntityAccess. It is not a substitute for IJobEntity at scale — but for the bulk of gameplay systems it's the right tool, and the discipline it enforces around access intent pays off across the rest of the codebase.

Intent

Iterate entities on the main thread with explicit read/write intent, archetype-chunk-aware iteration, and zero allocation — so the system is fast, readable, and gives the scheduler the information it needs to parallelize adjacent jobs.

Use when

• Main-thread per-entity work in OnUpdate that doesn't justify the cost of scheduling a job. Scheduling a job has overhead; for a few hundred entities with a simple body, SystemAPI.Query is faster end-to-end.
• The work touches managed objects (so a Burst job can't be used) but you still want chunk-iteration efficiency.
• The body is small and obvious — the kind of thing where reading the foreach is faster than reading an IJobEntity declaration.
• The system also does main-thread setup work (singleton read, ECB acquisition) — folding the iteration into the same method keeps the system file short.

Avoid when

• Entity counts are large (thousands+) and the body is non-trivial. Promote to IJobEntity.ScheduleParallel — the main-thread ceiling here is real and shows up as a frame-time anchor.
• The body needs to mutate archetypes (AddComponent, RemoveComponent, DestroyEntity, structural moves). You cannot call EntityManager mutators inside the foreach — the enumerator becomes invalid. Use an ECB (see dots-ecb-orchestration).
• You need chunk-level optimizations: DidChange on the chunk, raw pointer iteration, version-filtered chunks. Drop to IJobChunk for that.
• The body is so trivial that even main-thread iteration is wasted — consider whether a singleton or an enableable component flip would solve it without per-entity work at all.