entity-query-patterns-systemapi-query

Your Unity DOTS system runs but nothing changes likely because SystemAPI.Query lacks correct RefRO/RefRW access intent. Using RefRW for read-only components or RefRO for writes causes silent scheduling conflicts, preventing the main-thread foreach loop from properly executing archetype-chunk iteration.

To use SystemAPI.Query correctly in ISystem.OnUpdate, apply RefRO strictly for read-only components and RefRW only for values you genuinely write. This access intent discipline ensures proper type-level read/write safety and avoids parallelism issues during main-thread archetype-chunk iteration.

You cannot safely make structural changes inside a SystemAPI.Query foreach loop. Using EntityManager mutators directly causes invalid iterators and skipped or duplicated entities. Use an EntityCommandBuffer (ECB) based approach instead to safely defer structural changes during archetype-chunk iteration.

You filter archetypes in SystemAPI.Query by applying composable filters like WithAll, WithNone, and WithAny. These refinements precisely target intended archetypes during entity iteration, ensuring your ISystem.OnUpdate loop processes only the specific components matching your query criteria.

You should move from SystemAPI.Query to IJobEntity when scale or per-entity workload increases significantly. If your main-thread archetype-chunk iteration handles large entity counts or heavier computations, promoting the loop to IJobEntity satisfies performance requirements and enables parallel scheduling.

RefRW intent discipline in Unity DOTS ECS iteration means using RefRW exclusively for component values you genuinely write inside the SystemAPI.Query loop. This strict type-level read/write discipline prevents scheduling conflicts and ensures your main-thread system correctly expresses its access intent.