Repository navigation
ecs: despawn only what existed before the sync point, or at the end of the run #244
Description
Summary
commands.despawnWhere (#236) also despawns the matching entities that the same sync point spawns. And a command's effect at an earlier sync point (#232) can despawn data a later system still expects to read. Between the two, an app can't say "clear what existed before, keep what this frame made".
Case (mecs, @adobe/ecs 0.2.4)
One-frame events (a key going down, a request) are spawned during a frame and cleared at the start of the next, so each lives exactly one frame:
export const endFrame = System.create({ components: { with: [frameTransient] } }, (row, { commands }) => {
commands.despawn(row.entity);
});Changing the body to commands.despawnWhere({ with: [frameTransient] }) made 5 tests fail: the events spawned in the same sync point are removed before the consumers (selectFace, startStrokes, extrudeSelection) ever see them. A clear-then-respawn (previewBrush: despawn the old preview, spawn the new one) has the same problem. Both stay as per-row despawns.
With #232's earlier sync points the per-row version has a related hazard: endFrame's despawns now apply before later tiers, so it had to be after: [input], and a consumer of an event spawned in the same frame has to be ordered after its producer or the event is gone before the consumer runs. Before, "everything a frame made is read next frame" held without ordering; it is now something to write down.
Requested
despawnWherethat touches only what exists before the sync point (an option, e.g.{ existing: true }, or the default with the other documented), or documented as it is.- A despawn "at the end of the run": the command applies at the last sync point, after every system has read, so an event lives until the end of its frame regardless of the schedule.
Activity
krisnye commentedon Nov 1, 2026
Addressed in #250 (Adobe-Firefly/ecs#9). Request 1 is now the meaning, with no option:
despawnWheredespawns only what was alive before its sync point, as the commands issued before it leave it, which is what a row system callingdespawn(row.entity)over the same query would do. What that sync point spawns lives. This is why@adobe/ecsgoes to 0.3.0.Request 2, a despawn at the end of the run, is declined. It would add a command lane that waits past later sync points, which breaks "commands apply at the next sync point, in issue order" and makes an entity's lifetime depend on timing nothing declares. The guide's chapter 06 shows one-frame events instead:
previewBrushtoo);endFramerunsaftera composite of everything else, which places it last.