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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(query): forEach opened an iteration it could not promise to close
esengineafcf66edc457
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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, notpart of the entity set the query cache returns — and `count()` read that setdiff --git a/sdk/src/ecs/query.ts b/sdk/src/ecs/query.tsindex 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<Quconst 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<Quworld.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<Quworld.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.tsnew file mode 100644index 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);+ });+});