skip to content

In an ECS, why is adding or removing a component while a system iterates its query dangerous, and how does a command buffer fix it?

level: middleimportance: should knowfreq 55%

answer

  1. presence decides where data lives
  2. swap-and-pop moves the last row
  3. entity changes table mid-loop
  4. record now, apply at a sync point

basics

~20 s

Adding or removing a component moves an entity's data to other storage, which can skip or revisit entities and invalidate pointers mid-iteration. A command buffer records such changes and applies them later at a safe sync point.

solid answer

~50 s

In most ECS storage a component's presence decides where data lives. In archetype storage, adding `Burning` moves the entity's whole row to another table; the old table usually fills the hole by swapping its last row in, so the loop skips that swapped-in entity, and if the destination table also matches the query the moved entity can be visited twice. A pointer the system holds into a column can dangle if a table grows and reallocates. Sparse-set storage has the same swap-and-pop hazard. A **command buffer** fixes it: during iteration the system records `add`, `remove`, `create` and `destroy` commands, and the engine plays them back at a defined sync point, typically after the system or phase finishes. The costs: changes become visible only after playback, created entities need placeholder ids, and conflicting commands such as an add after a destroy need a rule.

code

pseudocode · 11 lines
pseudocode
// inside the fire system: record, never mutate storage
for each (entity, temperature) in query(Temperature, Health):
    if temperature.value > IGNITION_POINT and not has(entity, Burning):
        commands.add(entity, Burning { seconds_left = 5 })

// at the sync point after the system finishes
for each command in commands, in recorded order:
    if not is_alive(command.entity):
        continue                 // destroyed by an earlier command
    apply(command)               // an add on an existing component overwrites it
commands.clear()

go deeper

for a junior

Recall that adding or removing a component is different from writing a value, and that a command buffer delays the change until it is safe.

for a middle

Walk through swap-and-pop and a move between tables and show exactly which entity is skipped, which is visited twice and which pointer dangles.

for a senior

Reason about sync-point placement, delayed visibility, conflicting commands and the playback spike, and know when a flag beats a component.

for a principal

Set the team rule: structural changes only through buffers, documented sync points, and a stated policy for conflicts, so every system can rely on stable storage.

## What counts as a structural change In an ECS, writing a new value into a component an entity already has is an ordinary write. A **structural change** is anything that changes which components an entity has, or whether it exists: - adding a component, such as a `Burning` status when a unit catches fire; - removing a component, such as `Burning` when the fire goes out; - creating or destroying an entity. Structural changes matter because in most ECS designs the set of components decides **where an entity's data lives**. In archetype storage, entities with the same component set share a table, so adding `Burning` moves the entity's whole row to a different table. In sparse-set storage, each component type has a dense array of values, and removal keeps it dense by moving the last element into the hole. ## How an in-place change breaks iteration Picture fifty thousand swarm units and a fire system iterating every entity with `Temperature` and `Health` in archetype storage, adding `Burning` as each one crosses its ignition point. If it does that immediately: 1. The entity's components are copied into the table for its new component set. 2. The old table removes the row by **swap-and-pop**: the last row is copied into the vacated slot and the table shrinks by one. 3. The loop advances to the next index, so the entity that was just swapped into the current slot is **never visited** this pass. 4. The destination table also matches the query, because it also has `Temperature` and `Health`. If the loop reaches that table later, the moved entity is **visited a second time**. 5. If the destination table had to grow, its arrays may have been reallocated, and any pointer or reference the system held into them now **dangles**. Sparse sets suffer the same skip, because removal swaps the last element into the hole. Destroying an entity mid-loop adds another problem: other code may still hold its identifier. Generation counts on entity ids catch that case; they belong to handle design rather than to storage. ## Deferring through a command buffer The standard fix is to never change structure during iteration. A system records its intent into a **command buffer** instead: - `add(entity, value)`, `remove(entity, type)`, `create()` and `destroy(entity)` are appended as commands, usually with their data copied into the buffer; - the engine **plays back** the buffer at a **sync point**, a defined moment when no system is iterating the affected storage, commonly after the system, after a group of systems, or at the end of a frame phase; - an entity created through the buffer gets a **placeholder id**, later commands in the same buffer refer to it, and playback creates the real entity and rewrites those references; - playback can **batch**: many entities moving from the same table to the same destination can be moved together, which is cheaper than one move per command. Ordinary component writes, such as changing a unit's position or lowering its health, do not go through the buffer; they happen in place, because they move nothing. ## What deferral costs - **Delayed visibility.** Until playback, every system still sees the entity without `Burning`. A damage-over-time system that runs before the sync point will not damage the unit this frame. - **Ordering rules.** Commands can conflict: an add recorded after a destroy, or two systems adding the same component. The engine needs a rule (skip commands on dead entities, let a later add overwrite an earlier one) and the team needs to know it. - **Placeholder discipline.** Code outside the buffer cannot use a placeholder id until playback has run. - **Memory and playback time.** The buffer stores every command and value, and a burst of thousands of changes costs real time at the sync point, which shows up in the frame. ## Avoiding the structural change altogether Not every state needs to be a component. Compare the choices for a status like burning: | Representation | Change cost | Iteration cost | |---|---|---| | Component added and removed | Structural change, deferred | A system visits only burning units | | Flag inside an existing component | Plain write, no deferral | A system visits every unit and tests the flag | | Per-component enabled bit, where the design has one | Plain write | Iteration skips disabled entries | When most units are visited anyway and the status flips often, a flag avoids the churn. When the status is rare and a system should touch only the units that have it, a component deferred through a buffer keeps that system's query small.

  • Why not iterate the table backwards so swap-and-pop removal is safe?
    Reverse iteration only fixes removing the current element from the array being walked, because the swapped-in element has already been visited. It does nothing for an entity moved into another table the same query also matches, for a table that reallocates while you hold pointers into it, or for changes to entities other than the current one. A command buffer covers all of these with one rule.
  • How can one command refer to an entity that an earlier command in the same buffer creates?
    The buffer hands out a placeholder id when the create is recorded, and later commands use it. At playback the engine creates the real entity, maps the placeholder to its id, and rewrites the remaining commands. Code outside the buffer cannot use the placeholder until playback has finished.
  • When should a frequently toggled state be a flag rather than a component?
    When it flips often and the systems that care visit most of the candidate entities anyway. A boolean or bit in a component every unit already has costs no structural change and is tested inline. A separate component pays off when the state is rare and a system should visit only the entities that have it, because its query then skips everyone else.

  • Adding a component only writes the new value; no other data moves.
  • Iterating backwards makes every structural change during a loop safe.
  • A command buffer applies each change immediately, just more safely.
  • A recorded change is visible to the rest of the same system at once.
  • Value writes such as new positions must also go through the command buffer.