Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(query): forEach opened an iteration it could not promise to close

esengineafcf66edc457
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 170f91666..c2b955762 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,21 @@ published separately; it ships inside the editor.
### Fixed
+- **A system that threw inside `forEach` left the world iterating.** The world
+ refuses `spawn`/`despawn`/`remove` while a query is being walked — those would
+ resize the arrays under it — so `beginIteration` and `endIteration` have to
+ balance no matter how the walk ends. `forEach` called them around a bare loop
+ with no `try`/`finally`, so a callback that threw skipped the decrement and the
+ world believed it was iterating from then on. The failure does not appear where
+ it happened: the callback's error gets logged somewhere, and the next unrelated
+ `world.spawn()` fails with "Cannot spawn entity during query iteration". The
+ system runner resets the depth at each system boundary, which limits this to the
+ rest of that system and does nothing for a `forEach` outside one (an editor
+ tool, a script holding the World). The iterator had the same hole in `next()`:
+ `for..of` closes an iterator whose BODY throws, but not one whose `next()` does.
+ Both close now, and a write-back that fails while an error is already on its way
+ out no longer replaces it — the callback's error is the one worth reading.
+
- **Asking a query a question gave a different answer than iterating it.**
`Added()`/`Changed()` are per-entity tick checks applied while iterating, not
part of the entity set the query cache returns — and `count()` read that set
diff --git a/sdk/src/ecs/query.ts b/sdk/src/ecs/query.ts
index e69e7c3ee..5ce9dcc6c 100644
--- a/sdk/src/ecs/query.ts
+++ b/sdk/src/ecs/query.ts
@@ -436,13 +436,17 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
const writeMut = () => { self.writeMutBack_(prevEntity!); };
- const finalize = () => {
+ // endIteration first, so the depth balances even if the write-back throws.
+ const finalize = (errorInFlight = false) => {
if (done) return;
done = true;
world.endIteration();
- if (prevEntity !== null && hasMut) {
+ if (prevEntity === null || !hasMut) return;
+ if (!errorInFlight) {
writeMut();
+ return;
}
+ try { writeMut(); } catch { /* the original error wins */ }
};
const iterResult: IteratorResult<QueryResult<C>> = { value: result as QueryResult<C>, done: false };
@@ -455,31 +459,39 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
world.beginIteration();
}
- while (idx < entities.length) {
- const entity = entities[idx++];
+ // for..of closes the iterator when its BODY throws, but nothing
+ // closes it when next() itself does — a getter over broken storage
+ // would leave the world iterating for good.
+ try {
+ while (idx < entities.length) {
+ const entity = entities[idx++];
- if (hasChangeFilters && !self.passesChangeFilters_(entity)) {
- continue;
- }
+ if (hasChangeFilters && !self.passesChangeFilters_(entity)) {
+ continue;
+ }
- if (prevEntity !== null && hasMut) {
- writeMut();
- }
+ if (prevEntity !== null && hasMut) {
+ writeMut();
+ }
- result[0] = entity;
- for (let i = 0; i < compCount; i++) {
- const getter = getters[i];
- result[i + 1] = getter ? getter(entity) : world.get(entity, actualComponents[i]);
- }
+ result[0] = entity;
+ for (let i = 0; i < compCount; i++) {
+ const getter = getters[i];
+ result[i + 1] = getter ? getter(entity) : world.get(entity, actualComponents[i]);
+ }
- if (hasMut) {
- for (let i = 0; i < mutCount; i++) {
- mutData[i].data = result[_mutIndices[i] + 1] as Record<string, unknown>;
+ if (hasMut) {
+ for (let i = 0; i < mutCount; i++) {
+ mutData[i].data = result[_mutIndices[i] + 1] as Record<string, unknown>;
+ }
+ prevEntity = entity;
}
- prevEntity = entity;
- }
- return iterResult;
+ return iterResult;
+ }
+ } catch (e) {
+ finalize(true);
+ throw e;
}
finalize();
@@ -507,43 +519,54 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
world.beginIteration();
let prevEntity: Entity | null = null;
- for (let idx = 0; idx < entities.length; idx++) {
- const entity = entities[idx];
- if (hasChangeFilters && !this.passesChangeFilters_(entity)) continue;
+ let completed = false;
+ try {
+ for (let idx = 0; idx < entities.length; idx++) {
+ const entity = entities[idx];
+ if (hasChangeFilters && !this.passesChangeFilters_(entity)) continue;
+
+ if (prevEntity !== null && hasMut) {
+ this.writeMutBack_(prevEntity);
+ }
- if (prevEntity !== null && hasMut) {
- this.writeMutBack_(prevEntity);
- }
+ result[0] = entity;
+ for (let i = 0; i < compCount; i++) {
+ const getter = getters[i];
+ result[i + 1] = getter ? getter(entity) : world.get(entity, actualComponents[i]);
+ }
- result[0] = entity;
- for (let i = 0; i < compCount; i++) {
- const getter = getters[i];
- result[i + 1] = getter ? getter(entity) : world.get(entity, actualComponents[i]);
- }
+ if (hasMut) {
+ for (let i = 0; i < mutCount; i++) {
+ mutData[i].data = result[_mutIndices[i] + 1] as Record<string, unknown>;
+ }
+ prevEntity = entity;
+ }
- if (hasMut) {
- for (let i = 0; i < mutCount; i++) {
- mutData[i].data = result[_mutIndices[i] + 1] as Record<string, unknown>;
+ // Fast path for 1–6 components (covers the vast majority of queries); 7+ falls back to .apply.
+ switch (compCount) {
+ case 1: (callback as any)(entity, result[1]); break;
+ case 2: (callback as any)(entity, result[1], result[2]); break;
+ case 3: (callback as any)(entity, result[1], result[2], result[3]); break;
+ case 4: (callback as any)(entity, result[1], result[2], result[3], result[4]); break;
+ case 5: (callback as any)(entity, result[1], result[2], result[3], result[4], result[5]); break;
+ case 6: (callback as any)(entity, result[1], result[2], result[3], result[4], result[5], result[6]); break;
+ default: (callback as Function).apply(null, result); break;
}
- prevEntity = entity;
}
- // Fast path for 1–6 components (covers the vast majority of queries); 7+ falls back to .apply.
- switch (compCount) {
- case 1: (callback as any)(entity, result[1]); break;
- case 2: (callback as any)(entity, result[1], result[2]); break;
- case 3: (callback as any)(entity, result[1], result[2], result[3]); break;
- case 4: (callback as any)(entity, result[1], result[2], result[3], result[4]); break;
- case 5: (callback as any)(entity, result[1], result[2], result[3], result[4], result[5]); break;
- case 6: (callback as any)(entity, result[1], result[2], result[3], result[4], result[5], result[6]); break;
- default: (callback as Function).apply(null, result); break;
+ if (prevEntity !== null && hasMut) {
+ this.writeMutBack_(prevEntity);
}
+ completed = true;
+ } finally {
+ if (!completed && prevEntity !== null && hasMut) {
+ // The callback threw partway. Edits it already finished still go
+ // back, but a failure writing them must not replace the error on
+ // its way out — that error is the one worth reading.
+ try { this.writeMutBack_(prevEntity); } catch { /* the original error wins */ }
+ }
+ world.endIteration();
}
-
- if (prevEntity !== null && hasMut) {
- this.writeMutBack_(prevEntity);
- }
- world.endIteration();
}
/**
diff --git a/sdk/tests/query-iteration-balance.test.ts b/sdk/tests/query-iteration-balance.test.ts
new file mode 100644
index 000000000..5ec41cc3f
--- /dev/null
+++ b/sdk/tests/query-iteration-balance.test.ts
@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file query-iteration-balance.test.ts
+ * @brief beginIteration/endIteration must balance however iteration ends.
+ *
+ * While the world is iterating it REFUSES spawn/despawn/remove — the
+ * whole point, since those would resize the arrays being walked. So a
+ * leaked depth does not fail where it happened: forEach's callback
+ * throws, the count is never decremented, and the error surfaces later
+ * as "Cannot spawn entity during query iteration" somewhere entirely
+ * unrelated. SystemRunner resets the depth at each system boundary,
+ * which narrows the blast radius to the rest of that system and does
+ * nothing at all for a forEach called outside one.
+ */
+import { describe, it, expect } from 'vitest';
+import { World } from '../src/ecs/world';
+import { Query, QueryInstance, Mut } from '../src/ecs/query';
+import { defineComponent } from '../src/ecs/component';
+
+const P = defineComponent('IBPosition', { x: 0 });
+
+function worldWithEntities(n: number): World {
+ const world = new World();
+ for (let i = 0; i < n; i++) {
+ const e = world.spawn();
+ world.insert(e, P, { x: i });
+ }
+ return world;
+}
+
+describe('iteration depth balances however iteration ends', () => {
+ it('forEach: callback throws', () => {
+ const world = worldWithEntities(3);
+ expect(() => {
+ new QueryInstance(world, Query(P), -1).forEach(() => { throw new Error('boom'); });
+ }).toThrow('boom');
+ expect(world.isIterating()).toBe(false);
+ });
+
+ it('forEach: callback throws on a Mut query', () => {
+ const world = worldWithEntities(3);
+ expect(() => {
+ new QueryInstance(world, Query(Mut(P)), -1).forEach((_e, p) => {
+ (p as { x: number }).x = 99;
+ throw new Error('boom');
+ });
+ }).toThrow('boom');
+ expect(world.isIterating()).toBe(false);
+ });
+
+ it('forEach: the error is the callback\'s, and the world is usable after it', () => {
+ const world = worldWithEntities(3);
+ try {
+ new QueryInstance(world, Query(P), -1).forEach(() => { throw new Error('boom'); });
+ } catch { /* a system that logs and carries on */ }
+ expect(() => world.spawn()).not.toThrow();
+ });
+
+ it('forEach: nesting stays balanced when the inner one throws', () => {
+ const world = worldWithEntities(2);
+ const outer = new QueryInstance(world, Query(P), -1);
+ const inner = new QueryInstance(world, Query(P), -1);
+ outer.forEach(() => {
+ try {
+ inner.forEach(() => { throw new Error('inner'); });
+ } catch { /* handled */ }
+ });
+ expect(world.isIterating()).toBe(false);
+ });
+
+ it('for..of: loop body throws', () => {
+ const world = worldWithEntities(3);
+ expect(() => {
+ for (const _row of new QueryInstance(world, Query(P), -1)) {
+ throw new Error('boom');
+ }
+ }).toThrow('boom');
+ expect(world.isIterating()).toBe(false);
+ });
+
+ it('for..of: break leaves nothing open', () => {
+ const world = worldWithEntities(3);
+ for (const _row of new QueryInstance(world, Query(P), -1)) break;
+ expect(world.isIterating()).toBe(false);
+ });
+
+ it('for..of: next() itself throws', () => {
+ const world = worldWithEntities(3);
+ const q = new QueryInstance(world, Query(P), -1);
+ // A getter that fails is the engine's own storage breaking underfoot; the
+ // iterator still has to close, or nothing can spawn for the rest of the run.
+ (q as unknown as { getters_: unknown[] }).getters_ = [() => { throw new Error('storage'); }];
+ expect(() => {
+ for (const _row of q) { /* never reached */ }
+ }).toThrow('storage');
+ expect(world.isIterating()).toBe(false);
+ });
+
+ it('a write-back failure does not replace the callback\'s error', () => {
+ const world = worldWithEntities(2);
+ const q = new QueryInstance(world, Query(Mut(P)), -1);
+ (q as unknown as { writeMutBack_: (e: number) => void }).writeMutBack_ = () => {
+ throw new Error('write-back');
+ };
+ expect(() => {
+ q.forEach(() => { throw new Error('callback'); });
+ }).toThrow('callback');
+ expect(world.isIterating()).toBe(false);
+ });
+
+ it('a write-back failure on a clean run is not swallowed', () => {
+ const world = worldWithEntities(2);
+ const q = new QueryInstance(world, Query(Mut(P)), -1);
+ (q as unknown as { writeMutBack_: (e: number) => void }).writeMutBack_ = () => {
+ throw new Error('write-back');
+ };
+ expect(() => q.forEach(() => { /* no error of its own */ })).toThrow('write-back');
+ expect(world.isIterating()).toBe(false);
+ });
+});