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(ecs): a query row outlives the row after it

esengine9e953377a4c9
diff --git a/docs/MUTATION_CONTRACT.md b/docs/MUTATION_CONTRACT.md
index 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.md
index 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) => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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) => void
diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.ts
index 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.ts
index 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<Qu
private 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<Qu
const 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<Qu
try { 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<Qu
writeMut();
}
- 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<Qu
toArray(): 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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);
+ });
+ });
+});