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(ecs): a query row outlives the row after it
esengine9e953377a4c9
diff --git a/docs/MUTATION_CONTRACT.md b/docs/MUTATION_CONTRACT.mdindex d5ab3731c..907066d7e 100644--- a/docs/MUTATION_CONTRACT.md+++ b/docs/MUTATION_CONTRACT.md@@ -64,6 +64,11 @@ shadow scan 看得见,ChangeTracker 看不见。** 只要还有一条这样的写它既不改 World 也不报告——不是「安全」,是**静默丢弃**。裸 `Query(C)` 对 builtin 更糟:`resolvePtrGetter` 返回的是一个**跨行复用的 scratch 对象**,写入会被下一行的 fill 覆盖。于是同一行代码 `row.field = v` 在脚本组件上悄悄改了世界,在 builtin 上悄悄什么都没做。++ > **PR6c.2 已修这一格的读侧。** 那不只是写侧的陷阱:`toArray()` 曾把三行返回成同一个+ > 对象、值全等于最后一行,纯读也是错的。现在 `forEach` 是明确的 borrowed 快路,+ > iterator / `single` / `toArray` 交出可保留的行;代价是每行一次分配+ > (脚本组件 1.2x,引擎组件 1.7x)。判据见 `sdk/tests/query-row-lifetime.test.ts`。3. **`Query` 的文档承诺没有被执行层兑现。** 文档写的是「除非包在 `Mut` 里否则只读」,但裸 `Query(C)` 的 getter 对脚本组件就是 `storage.get(e)`。承诺只存在于类型注释里。diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 7115d8323..4d2ff4e0f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -9521,7 +9521,7 @@ tabIndex: number | undefined@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@internal resetQueryPool: () => void-@internal resolveGetter: (component: AnyComponentDef) => ((entity: Entity) => unknown) | null+@internal resolveGetter: (component: AnyComponentDef, mode?: "borrowed" | "retained") => ((entity: Entity) => unknown) | null@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null@internal resumeIteration: (depth: number) => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex f00436f7a..36b0803ca 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -9714,7 +9714,7 @@ tabIndex: number | undefined@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@internal resetQueryPool: () => void-@internal resolveGetter: (component: AnyComponentDef) => ((entity: Entity) => unknown) | null+@internal resolveGetter: (component: AnyComponentDef, mode?: "borrowed" | "retained") => ((entity: Entity) => unknown) | null@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null@internal resumeIteration: (depth: number) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex f2356bc08..5c16bdee3 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -9516,7 +9516,7 @@ tabIndex: number | undefined@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@internal resetQueryPool: () => void-@internal resolveGetter: (component: AnyComponentDef) => ((entity: Entity) => unknown) | null+@internal resolveGetter: (component: AnyComponentDef, mode?: "borrowed" | "retained") => ((entity: Entity) => unknown) | null@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null@internal resumeIteration: (depth: number) => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 14a927ac3..45e615048 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -9768,7 +9768,7 @@ tabIndex: number | undefined@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@internal resetQueryPool: () => void-@internal resolveGetter: (component: AnyComponentDef) => ((entity: Entity) => unknown) | null+@internal resolveGetter: (component: AnyComponentDef, mode?: "borrowed" | "retained") => ((entity: Entity) => unknown) | null@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null@internal resumeIteration: (depth: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 3ef7785d5..5d8037b00 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -9544,7 +9544,7 @@ tabIndex: number | undefined@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@internal resetQueryPool: () => void-@internal resolveGetter: (component: AnyComponentDef) => ((entity: Entity) => unknown) | null+@internal resolveGetter: (component: AnyComponentDef, mode?: "borrowed" | "retained") => ((entity: Entity) => unknown) | null@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null@internal resumeIteration: (depth: number) => voiddiff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.tsindex 3a4af7103..433b9c2f5 100644--- a/sdk/src/ecs/bridge/BuiltinBridge.ts+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts@@ -726,15 +726,26 @@ export class BuiltinBridge {}/**- * Returns a getter that reads C++ component data into a shared preallocated object.- * WARNING: The returned object is reused across calls — copy it if you need to retain the values.+ * A getter reading C++ component data out of the wasm heap. `borrowed` (the+ * default) refills ONE object per call, so the value dies at the next call;+ * `retained` fills a fresh one, which is what a caller keeping the value past+ * its own step needs — a query row outliving the row after it, above all.*/- resolvePtrGetter(cppName: string): ((entity: Entity) => unknown) | null {+ resolvePtrGetter(cppName: string, mode: 'borrowed' | 'retained' = 'borrowed'):+ ((entity: Entity) => unknown) | null {const accessor = PTR_ACCESSORS[cppName];if (!accessor) return null;const resolveHeap = this.memory_?.resolveComponentHeap(cppName);if (!resolveHeap) return null;const heap: ComponentHeap = SCRATCH_HEAP();+ if (mode === 'retained') {+ return (e: Entity) => {+ if (!resolveHeap(e, heap)) return null;+ const out = accessor.create();+ accessor.fill(heap.f32, heap.u32, heap.u8, heap.ptr, out);+ return out;+ };+ }const cached = accessor.create();return (e: Entity) => {if (!resolveHeap(e, heap)) return null;diff --git a/sdk/src/ecs/query.ts b/sdk/src/ecs/query.tsindex c893b52c7..0d76c362e 100644--- a/sdk/src/ecs/query.ts+++ b/sdk/src/ecs/query.ts@@ -408,6 +408,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Quprivate scanned_ = 0;private filtered_ = 0;private readonly getters_: Array<((entity: Entity) => unknown) | null>;+ private readonly gettersRetained_: Array<((entity: Entity) => unknown) | null>;private readonly mutSetters_: Array<((entity: Entity, data: unknown) => void) | null>;private readonly mutIsBuiltin_: boolean[];private readonly compiledFilter_: QueryFilter | null;@@ -445,7 +446,8 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu...descriptor._without.map(c => c._id),...(this.compiledFilter_?.deps.map(c => c._id) ?? []),];- this.getters_ = this.actualComponents_.map(comp => world.resolveGetter(comp));+ this.getters_ = this.actualComponents_.map(comp => world.resolveGetter(comp, 'borrowed'));+ this.gettersRetained_ = this.actualComponents_.map(comp => world.resolveGetter(comp, 'retained'));this.mutSetters_ = descriptor._mutIndices.map(idx =>world.resolveSetter(this.actualComponents_[idx]));@@ -556,6 +558,12 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu}}+ /**+ * Rows the caller may keep: a fresh array per entity, and for an+ * engine-backed component a fresh value rather than the shared fill target.+ * {@link forEach} lends its row instead and is cheaper for a body that only+ * reads it once.+ */[Symbol.iterator](): Iterator<QueryResult<C>> {const { _mutIndices } = this.descriptor_;const actualComponents = this.actualComponents_;@@ -563,11 +571,10 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Quconst compCount = actualComponents.length;const hasMut = _mutIndices.length > 0;const hasChangeFilters = this.hasChangeFilters_();- const result = this.result_;const mutData = this.mutData_;const mutCount = mutData.length;const world = this.world_;- const getters = this.getters_;+ const getters = this.gettersRetained_;const self = this;let idx = 0;@@ -597,7 +604,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qutry { writeMut(); } catch { /* the original error wins */ }};- const iterResult: IteratorResult<QueryResult<C>> = { value: result as QueryResult<C>, done: false };+ const iterResult: IteratorResult<QueryResult<C>> = { value: undefined as unknown as QueryResult<C>, done: false };const doneResult: IteratorResult<QueryResult<C>> = { value: undefined as unknown as QueryResult<C>, done: true };return {@@ -622,19 +629,21 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<QuwriteMut();}- result[0] = entity;+ const row: unknown[] = new Array(compCount + 1);+ row[0] = entity;for (let i = 0; i < compCount; i++) {const getter = getters[i];- result[i + 1] = getter ? getter(entity) : world.get(entity, actualComponents[i]);+ row[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>;+ mutData[i].data = row[_mutIndices[i] + 1] as Record<string, unknown>;}prevEntity = entity;}+ iterResult.value = row as QueryResult<C>;return iterResult;}} catch (e) {@@ -652,6 +661,12 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu};}+ /**+ * Run `callback` per matching entity, LENDING it the row: the values are+ * refilled for the next entity, so anything kept past the callback must be+ * copied. The fast path — iterating instead costs an allocation per row+ * (1.2x for script components, 1.7x for engine-backed ones).+ */forEach(callback: (entity: Entity, ...components: ComponentsData<C>) => void): void {const { _mutIndices } = this.descriptor_;const entities = this.candidates_();@@ -724,10 +739,9 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu* the next iteration overwrites — a caller that holds this would otherwise* watch it change under them.*/+ /** The one row, or null. The iterator's rows are already the caller's to keep. */single(): QueryResult<C> | null {- for (const result of this) {- return [...result] as QueryResult<C>;- }+ for (const result of this) return result;return null;}@@ -764,9 +778,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<QutoArray(): QueryResult<C>[] {const arr: QueryResult<C>[] = [];- for (const row of this) {- arr.push([...row] as QueryResult<C>);- }+ for (const row of this) arr.push(row);return arr;}}diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex 6341787de..3946409e1 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -839,12 +839,13 @@ export class World {}/** @internal Pre-resolve a component to its direct storage/getter for fast iteration. */- resolveGetter(component: AnyComponentDef): ((entity: Entity) => unknown) | null {+ resolveGetter(component: AnyComponentDef, mode: 'borrowed' | 'retained' = 'borrowed'):+ ((entity: Entity) => unknown) | null {if (isBuiltinComponent(component)) {if (!this.builtin_.hasCpp) return null;if (this.builtin_.getWasmModule()) {- const ptrGetter = this.builtin_.resolvePtrGetter(component._cppName);+ const ptrGetter = this.builtin_.resolvePtrGetter(component._cppName, mode);if (ptrGetter) return ptrGetter;}diff --git a/sdk/tests/query-iteration-balance.test.ts b/sdk/tests/query-iteration-balance.test.tsindex d177689e4..195884b88 100644--- a/sdk/tests/query-iteration-balance.test.ts+++ b/sdk/tests/query-iteration-balance.test.ts@@ -90,7 +90,12 @@ describe('iteration depth balances however iteration ends', () => {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'); }];+ // Both tables: the iterator reads the retained one and forEach the+ // borrowed one, and this test is about closing the iteration either way.+ const broken = [() => { throw new Error('storage'); }];+ const inner = q as unknown as { getters_: unknown[]; gettersRetained_: unknown[] };+ inner.getters_ = broken;+ inner.gettersRetained_ = broken;expect(() => {for (const _row of q) { /* never reached */ }}).toThrow('storage');diff --git a/sdk/tests/query-row-lifetime.test.ts b/sdk/tests/query-row-lifetime.test.tsnew file mode 100644index 000000000..b0b66544c--- /dev/null+++ b/sdk/tests/query-row-lifetime.test.ts@@ -0,0 +1,87 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file How long a value read out of a query stays valid.+ *+ * Engine-backed components are read through a pointer accessor that fills a+ * preallocated object, so the row a query yields can be a BORROWED view of the+ * next row's memory. That is a read-correctness question and has nothing to do+ * with whether writing to a row is allowed: `toArray()` returning three rows+ * that are one object is wrong even for a reader that never writes.+ */+import { describe, it, expect, beforeAll } from 'vitest';+import { App } from '../src/app/app';+import { Query, QueryInstance } from '../src/ecs/query';+import { Transform } from '../src/ecs/component';+import type { World } from '../src/ecs/world';+import type { ESEngineModule, CppRegistry } from '../src/wasm';+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';++const X = [100, 200, 300];++describe.skipIf(!HAS_WASM)('query row lifetime', () => {+ let module: ESEngineModule;+ beforeAll(async () => { module = await loadWasmModule(); });++ /** A world holding three entities whose Transforms differ in x. */+ function worldOfThree(): { app: App; world: World } {+ const app = App.new();+ app.connectCpp(new module.Registry() as unknown as CppRegistry, module);+ const world = app.world;+ for (const x of X) world.insert(world.spawn(), Transform, { position: { x, y: 0, z: 0 } });+ return { app, world };+ }++ type Row = [number, { position: { x: number } }];+ type Rows = Iterable<Row> & {+ toArray(): Row[];+ single(): Row;+ forEach(cb: (e: number, t: { position: { x: number } }) => void): void;+ };++ const rowsOf = (world: World): Rows =>+ new QueryInstance(world, Query(Transform)) as unknown as Rows;++ /** Run one body against a query over Transform. */+ function inQuery(fn: (q: Rows) => void): void {+ const { app, world } = worldOfThree();+ fn(rowsOf(world));+ app.world.disconnectCpp();+ }++ it('toArray keeps every row distinct', () => {+ inQuery((q) => {+ const rows = q.toArray();+ expect(rows.map((r) => r[1].position.x)).toEqual(X);+ expect(new Set(rows.map((r) => r[1])).size).toBe(3);+ });+ });++ it('a row held across iteration still reads its own entity', () => {+ inQuery((q) => {+ let first: { position: { x: number } } | undefined;+ for (const [, t] of q) if (!first) first = t;+ expect(first?.position.x).toBe(X[0]);+ });+ });++ it('single returns a value that outlives the query', () => {+ const { app, world } = worldOfThree();+ // The SAME instance must walk again: each QueryInstance resolves its own+ // scratch, so a second instance would not overwrite the first one's row+ // and the assertion would pass without the defect being fixed.+ const q = rowsOf(world);+ const held = (q as unknown as { single(): Row }).single()[1];+ for (const _row of q) { /* walk every row */ }+ expect(held.position.x).toBe(X[0]);+ app.world.disconnectCpp();+ });++ it('forEach lends its row for the duration of the callback only', () => {+ inQuery((q) => {+ const seen: number[] = [];+ q.forEach((_e, t) => { seen.push(t.position.x); });+ expect(seen).toEqual(X);+ });+ });+});