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.

feat(aot): the native row table is kept while the world stands

yhh94e32f85d836
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2af5e193b..e2d63d528 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,41 @@ published separately; it ships inside the editor.
### Added
+- **The native row table is kept across frames, so both AOT roads now answer the
+ same two questions.** `AotDispatch.ts` states the model the web road has always
+ worked to: a row table is a function of two things — which entities match, and
+ where their components are — and each has an authority that answers cheaply.
+ The native road answered neither until this release; the narrowing above
+ settled the first, and this settles the second.
+
+ Each side supplies the half it owns. The engine's pool versions are read in the
+ host, per call, because a despawn applied by the system before this one moves
+ them; the script pools' epoch can only come from the language that owns them,
+ so `es_aot_run` takes it. A host that cannot be told repacks every frame, which
+ is the same rule the web road follows — trusting an address because nobody
+ could say it moved is how compiled code reads somebody else's bytes.
+
+ **Two conditions, not one, and the second is the one that is easy to miss.**
+ `Registry::layoutEpoch()` says whether ADDRESSES moved, and it is deliberately
+ not a membership signal: `SparseSet::emplace` bumps no version when the buffer
+ does not reallocate, so an entity can join a pool without moving the epoch. So
+ every column a query names is also watched by identity — not just the shortest
+ one, because a query matches on all of them and the one it narrowed on need not
+ be the one that changed. Both conditions are sabotage-verified: dropping either
+ turns a test red, and neither test was red before the corresponding check
+ existed.
+
+ Measured at 100,000 movers on this host, packing costs about 3.4 ns per entity
+ per frame: a thin system goes from 11.4 to 8.0 ns/entity and a heavy one from
+ 14.6 to 12.5. **That is not the web road's 27.5 to under 2**, and the reason is
+ worth keeping: packing there is JavaScript resolving an address per component
+ per entity, and here it is C++ doing the same work an order of magnitude
+ cheaper. A conclusion measured on one host does not carry to the other.
+
+ `aotPacked` is published beside `aotCandidates`, and `--gate` requires it to be
+ zero in a scene that does not move — repacking a standing world is the other
+ silent way to pay for the frame.
+
- **A compiled system is paid over what it matches, not over the world.** On the
native road every compiled system was handed EVERY LIVE ENTITY as a candidate
each frame and resolved every component of each one. The absence of a
diff --git a/bench/aot-native/frame-bench.mjs b/bench/aot-native/frame-bench.mjs
index 3c8e73ced..cec98655e 100644
--- a/bench/aot-native/frame-bench.mjs
+++ b/bench/aot-native/frame-bench.mjs
@@ -319,14 +319,15 @@ console.log(`\nno-JIT frame — QuickJS-ng in the native host, ${ENTITIES} entit
// `tick` is the microtask drain, not the `update` call: that one only schedules an
// async tick. `draws` is a column because a body can move the render's cost —
// `heavy` writes `position.z`, which breaks sprite batching into one draw each.
-// `walked` is the entities a compiled system was PAID OVER in one frame, summed
-// across its queries. A count and not a clock on purpose — see the ceiling below.
-console.log('body build tick p50 cpu p50 frame p50 draws walked compiled?');
+// `walked` is what a compiled system covered in one frame, `packed` what it had
+// to write — zero once the row table is being kept. Counts and not clocks on
+// purpose; see the ceiling below.
+console.log('body build tick p50 cpu p50 frame p50 draws walked packed compiled?');
for (const r of rows) {
console.log(`${r.body.padEnd(9)} ${r.key.padEnd(13)} ${`${r.pump.p50.toFixed(3)} ms`.padStart(10)}`
+ ` ${`${r.cpu.p50.toFixed(3)} ms`.padStart(10)} ${`${r.frame.p50.toFixed(3)} ms`.padStart(11)}`
+ ` ${String(r.draws ?? '?').padStart(7)} ${String(r.aotCandidates ?? '?').padStart(9)}`
- + ` ${r.running ?? '—'}`);
+ + ` ${String(r.aotPacked ?? '?').padStart(8)} ${r.running ?? '—'}`);
}
let bad = 0;
@@ -359,6 +360,14 @@ const WORLD = ENTITIES + BYSTANDERS;
console.log(`${line} — ${(WORLD / Math.max(r.aotCandidates, 1)).toFixed(1)}x fewer`
+ ' entities than the world has');
}
+ // Nothing in this scene moves after startup, so a row table packed once
+ // must still stand. Repacking it every frame is the other silent way to
+ // pay for the world: no error, no pixel, just time.
+ if (typeof r.aotPacked === 'number' && r.aotPacked > 0) {
+ console.error(`✗ ${r.body}: repacked ${r.aotPacked} rows in a world that did not`
+ + ' move — the row table is not being kept');
+ bad++;
+ }
}
}
// An idle run of the same scene, if one was asked for: the frame minus the system,
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index c9fa210da..528de6a3d 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -44,11 +44,14 @@ query 会收窄。20k 实体、一个匹配 200 的系统 → 96% 的工作是
slot→entity 的表天然就是它,代价是每次 put/delete 一次 O(1) 写。**这一半是必须的**:
bench 里的 `Mover` 是项目组件,只收窄引擎池什么也买不到。
-2. **组件在哪 —— 跨帧复用 row table。**〔待做〕web 那条路量到 27.5 → 不到 2 ns/entity。
- native 侧更值:已经量到「代价不是代码」(thin 20 ns、heavy 21 ns,四次 substep 和四次
- sqrt 与三次乘加同价),也就是说编译系统的代价**几乎全是打表**。
+2. **组件在哪 —— 跨帧复用 row table。**〔已落地 2026-08-27〕两条路现在回答同一组问题。
- **开工前必须知道的一件事,否则会写出一个静默错误的缓存。**
+ **实测(100,000 个 mover,同一构建开关缓存)**:打表的代价在这台宿主上约
+ **3.4 ns/entity** —— thin 从 11.4 降到 8.0 ns/entity,heavy 从 14.6 降到 12.5。
+ **不是 web 那条路的 27.5 → 不到 2**:那边打表是 JS 逐实体逐组件解析地址,这边是 C++,
+ 便宜一个数量级。**在一个宿主上量到的结论不能照搬到另一个。**
+
+ **下面这条是开工前必须知道的,也是这次真正的收获。**
`Registry::layoutEpoch()` 是「地址有没有动」的权威,**不是「谁匹配」的权威** ——
`SparseSet::emplace` 只在 `components_` 真的 realloc 时才 `++version_`(容量内追加不
动已发出的指针,所以不需要 bump)。也就是说**往池里加一个实体可以完全不动 epoch**。
@@ -63,7 +66,9 @@ query 会收窄。20k 实体、一个匹配 200 的系统 → 96% 的工作是
- 引擎侧的 epoch **不需要**过界:native 宿主就在同一个进程里,直接
`host().registry->layoutEpoch()`(web 那条路当年还得为此加 embind 绑定)。
- **先做 1 再量 2**,因为 1 做完之后 2 的分母变了。
+ **两个条件而不是一个**,落地时就是按这个写的:epoch 管「地址动没动」,而每个 query
+ 点名的**每一列**都按身份盯着 —— 不只是最短的那一列,因为 query 是在所有列上匹配的,
+ 而变的那一列未必就是它收窄用的那一列。两个条件都做过双向 sabotage。
**前半的结果(`8379ba9f3`,2026-08-27)。** 同机实测:20,000 个 mover 在
200,000 实体的世界里,系统自身代价 **0.43 ms**,与「世界里只有它自己」的 0.51 ms 无异;
diff --git a/native/host/Bench.cpp b/native/host/Bench.cpp
index f434815d4..ec6eda0ec 100644
--- a/native/host/Bench.cpp
+++ b/native/host/Bench.cpp
@@ -48,10 +48,11 @@ struct BenchState {
long seen = 0; // frames entered, warmup included
Span update, pump, cpu, frame;
unsigned draws = 0, sprites = 0;
- /** This frame's running total, and the last timed frame's — the same shape
+ /** This frame's running totals, and the last timed frame's — the same shape
* `draws` has, so the report reads one frame rather than an average that
* hides a system which stopped being dispatched to halfway through. */
unsigned aotCandidates = 0, aotCandidatesFrame = 0;
+ unsigned aotPacked = 0, aotPackedFrame = 0;
};
long envLong(const char* name, long fallback) {
@@ -117,7 +118,7 @@ void report() {
"\"pump\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},"
"\"cpu\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},"
"\"frame\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},"
- "\"draws\":%u,\"sprites\":%u,\"aotCandidates\":%u,"
+ "\"draws\":%u,\"sprites\":%u,\"aotCandidates\":%u,\"aotPacked\":%u,"
"\"tickShareOfCpu\":%.4f}",
// The FRAME span's count is the authority on how many frames were
// sampled: a frame can be abandoned after it began and reach no other span.
@@ -126,7 +127,7 @@ void report() {
at(s.pump.ms, 0.0), p50, at(s.pump.ms, 0.9),
at(s.cpu.ms, 0.0), c50, at(s.cpu.ms, 0.9),
at(s.frame.ms, 0.0), at(s.frame.ms, 0.5), at(s.frame.ms, 0.9),
- s.draws, s.sprites, s.aotCandidatesFrame, share);
+ s.draws, s.sprites, s.aotCandidatesFrame, s.aotPackedFrame, share);
}
} // namespace
@@ -143,9 +144,10 @@ double benchDelta(double wall) {
void benchFrameBegin() {
BenchState& s = state();
if (!s.asked || s.reported) return;
- // Reset before the frame, not after: several compiled systems each add to it
- // and the total is what one frame was paid over.
+ // Reset before the frame, not after: several compiled systems each add to
+ // these and the totals are what one frame did.
s.aotCandidates = 0;
+ s.aotPacked = 0;
++s.seen;
if (timing()) {
s.frame.begin();
@@ -165,13 +167,15 @@ void benchNoteDraws(unsigned draws, unsigned sprites) {
state().sprites = sprites;
}
-void benchNoteAotCandidates(unsigned candidates) {
+void benchNoteAotCandidates(unsigned candidates, unsigned packed) {
BenchState& s = state();
if (!s.asked || s.reported) return;
s.aotCandidates += candidates;
- // Kept even during warmup: cheap, and it means the report has a number even
+ s.aotPacked += packed;
+ // Kept even during warmup: cheap, and it means the report has numbers even
// if the last timed frame happened to dispatch to nothing.
s.aotCandidatesFrame = s.aotCandidates;
+ s.aotPackedFrame = s.aotPacked;
}
bool benchFrameEnd() {
diff --git a/native/host/Bench.hpp b/native/host/Bench.hpp
index 84de1d2f2..6467754d1 100644
--- a/native/host/Bench.hpp
+++ b/native/host/Bench.hpp
@@ -87,13 +87,15 @@ void benchBeforePresent();
void benchNoteDraws(unsigned draws, unsigned sprites);
/**
- * Entities a compiled system was paid over, added to this frame's total.
+ * What a compiled system covered, and what it had to write, added to this
+ * frame's totals.
*
- * A count beside the clocks: a dispatcher back to offering every entity alive
- * makes a frame dearer in proportion to the WORLD, which on a busy machine reads
- * as noise. This is exact, so a gate can assert it with no tolerance.
+ * Counts beside the clocks: both regressions here — a dispatcher back to
+ * offering every entity alive, and a row table that stops being reused — cost
+ * time in proportion to the world, which on a busy machine reads as noise.
+ * These are exact, so a gate can assert them with no tolerance.
*/
-void benchNoteAotCandidates(unsigned candidates);
+void benchNoteAotCandidates(unsigned candidates, unsigned packed);
/** Close the frame, and report once the last timed one is in.
* @return true when the host was asked to quit and the report is out. */
diff --git a/native/host/bindings/AotBindings.cpp b/native/host/bindings/AotBindings.cpp
index 202a1f183..cf2e290d6 100644
--- a/native/host/bindings/AotBindings.cpp
+++ b/native/host/bindings/AotBindings.cpp
@@ -216,12 +216,17 @@ JSValue js_resource(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv)
}
/**
- * es_aot_run(i) -> records this host did not know, or -1 when nothing ran.
+ * es_aot_run(i, scriptEpoch) -> records this host did not know, or -1.
*
* Each query narrows itself to the shortest column it names; the list built here
* is only the FALLBACK for one that cannot (`aot::narrowest`). When it was the
* only road a compiled system cost the size of the WORLD — 2.9x for the same
* 5,000 movers with 45,000 unmatchable entities around them.
+ *
+ * The stamp says whether last frame's rows still stand, and each side supplies
+ * the half it owns: the engine's pool versions are read HERE per call, because
+ * a despawn by the previous system moves them; the script epoch can only come
+ * from the language that owns those pools. An absent argument reuses nothing.
*/
JSValue js_run(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
if (argc < 1) return JS_NewInt32(ctx, -1);
@@ -230,16 +235,24 @@ JSValue js_run(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
AotState& s = state();
if (!s.installed) return JS_NewInt32(ctx, -1);
+ aot::WorldStamp world;
+ double scriptEpoch = 0.0;
+ if (argc >= 2 && JS_ToFloat64(ctx, &scriptEpoch, argv[1]) == 0 && host().registry != nullptr) {
+ // Summed, not paired: both halves only ever count up, so no change in
+ // one can be cancelled by a change in the other.
+ world = aot::WorldStamp{host().registry->layoutEpoch() + scriptEpoch, true};
+ }
+
s.candidates.clear();
if (!s.dispatcher.narrowsAt(i)) {
host().registry->forEachEntity([&s](esengine::Entity e) { s.candidates.push_back(e.id()); });
}
- const auto cmds = s.dispatcher.run(i, s.candidates, resourceAt);
+ const auto cmds = s.dispatcher.run(i, s.candidates, resourceAt, world);
// Asked AFTER the run, because that is where a late binding is settled.
if (!s.dispatcher.boundAt(i)) return JS_NewInt32(ctx, -1);
- // What this system was paid over, for the bench and for the gate that reads
- // it. A no-op unless a bench was asked for.
- benchNoteAotCandidates(s.dispatcher.candidatesWalked());
+ // What this system covered and what it actually wrote, for the bench and the
+ // gates that read them. A no-op unless a bench was asked for.
+ benchNoteAotCandidates(s.dispatcher.candidatesWalked(i), s.dispatcher.rowsPacked(i));
// After the call, never during it: a despawn invalidates the rows it read.
return JS_NewInt32(ctx, static_cast<int>(aot::applyCommands(*host().registry, cmds)));
}
@@ -266,7 +279,7 @@ void registerAotBindings(HostState& h, JSValue global) {
fn("es_aot_bound", js_bound, 1);
fn("es_aot_script_rows", js_scriptRows, 8);
fn("es_aot_resource", js_resource, 3);
- fn("es_aot_run", js_run, 1);
+ fn("es_aot_run", js_run, 2);
fn("es_aot_reset", js_reset, 0);
}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 5d7662e9e..686bbe8e9 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -9322,6 +9322,7 @@ tabIndex: number | undefined
@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null
@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null
@internal resumeIteration: (depth: number) => void
+@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 539553dd0..f4223b1b5 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -9515,6 +9515,7 @@ tabIndex: number | undefined
@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null
@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null
@internal resumeIteration: (depth: number) => void
+@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a9d475410..2b3c54233 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -9317,6 +9317,7 @@ tabIndex: number | undefined
@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null
@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null
@internal resumeIteration: (depth: number) => void
+@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 5c3e8c3b1..d02a55100 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -9569,6 +9569,7 @@ tabIndex: number | undefined
@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null
@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null
@internal resumeIteration: (depth: number) => void
+@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 259be8f14..6ce4d2a8f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -9345,6 +9345,7 @@ tabIndex: number | undefined
@internal resolveHas: (component: AnyComponentDef) => ((entity: Entity) => boolean) | null
@internal resolveSetter: (component: AnyComponentDef) => ((entity: Entity, data: unknown) => void) | null
@internal resumeIteration: (depth: number) => void
+@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
diff --git a/sdk/src/ecs/aot/installNativeAot.ts b/sdk/src/ecs/aot/installNativeAot.ts
index 07871fad0..9bb2f6e47 100644
--- a/sdk/src/ecs/aot/installNativeAot.ts
+++ b/sdk/src/ecs/aot/installNativeAot.ts
@@ -40,7 +40,7 @@ export interface NativeAotBindings {
rowsOffset: number, stride: number, indexMask: number,
ownersOffset: number, ownerCount: number): boolean;
resource(name: string, offset: number, bytes: number): boolean;
- run(index: number): number;
+ run(index: number, scriptEpoch: number): number;
reset(): void;
}
@@ -96,7 +96,8 @@ export function nativeAotBindings(
bound: call<boolean>('es_aot_bound', false),
scriptRows: call<boolean>('es_aot_script_rows', false),
resource: call<boolean>('es_aot_resource', false),
- run: (index) => (run as (i: number) => number)(index),
+ run: (index, scriptEpoch) =>
+ (run as (i: number, e: number) => number)(index, scriptEpoch),
reset: call<void>('es_aot_reset', undefined as void),
};
}
@@ -193,10 +194,14 @@ class NativeAotDispatch implements AotDispatcher {
if (at === undefined) return false;
this.reportPools_();
this.reportResources_(twin);
+ // The epoch goes with the call: the host keeps last frame's row table
+ // when nothing moved, and only this side can say whether a script pool
+ // gained or lost a row.
+ //
// Negative means the host still cannot name everything this system
// reads — a pool with no rows yet, a resource nothing has written.
// The interpreter keeps it this frame and it is asked again next.
- if (this.bindings.run(at) < 0) return false;
+ if (this.bindings.run(at, this.world.scriptLayoutEpoch()) < 0) return false;
// Once, the first time the host takes it. "Installed" says a module
// loaded; this says a system is actually running as machine code, and
// the two are different frames when a pool has to exist first.
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index 64f74914b..6341787de 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -1198,6 +1198,17 @@ export class World {
return (engine ?? 0) + this.scripts_.layoutEpoch;
}
+ /**
+ * @internal The script pools' half of {@link layoutEpoch}, on its own.
+ *
+ * A host that reads the engine's half itself needs only this one, and must
+ * have it: a row added to or deleted from a script pool moves nothing the
+ * registry's version numbers can see.
+ */
+ scriptLayoutEpoch(): number {
+ return this.scripts_.layoutEpoch;
+ }
+
/**
* @internal Where a SCRIPT component's whole column is, for a host that
* walks it in its own address space. Undefined for an engine component,
diff --git a/sdk/tests/aot-native-install.test.ts b/sdk/tests/aot-native-install.test.ts
index f1ae70836..9dd18618d 100644
--- a/sdk/tests/aot-native-install.test.ts
+++ b/sdk/tests/aot-native-install.test.ts
@@ -13,6 +13,11 @@
* The first is the one that fails silently. The runner calls a twin
* wherever it finds one, so a twin for a system the host could not bind
* is a system that never runs at all.
+ *
+ * The fourth is the script pools' epoch. The host keeps last frame's
+ * row table while the world stands, and it can read the engine's half
+ * itself — a script row appearing or going is the half only this side
+ * can see.
*/
import { describe, it, expect } from 'vitest';
import { World } from '../src/ecs/world';
@@ -53,6 +58,7 @@ const MANIFEST: AotManifest = {
function fakeHost(runnable: readonly string[]) {
const order = MANIFEST.systems.map((s) => s.name);
const calls: number[] = [];
+ const epochs: number[] = [];
const reported: { name: string; rows: number; sparseCount: number }[] = [];
const bindings: NativeAotBindings = {
install: () => order.length,
@@ -65,14 +71,15 @@ function fakeHost(runnable: readonly string[]) {
resource: () => true,
// Negative is "I still cannot name everything this reads" — the answer
// that sends the system back to the interpreter for this frame.
- run: (i) => {
+ run: (i, scriptEpoch) => {
if (!runnable.includes(order[i] ?? '')) return -1;
calls.push(i);
+ epochs.push(scriptEpoch);
return 0;
},
reset: () => {},
};
- return { bindings, calls, reported };
+ return { bindings, calls, reported, epochs };
}
function fixture(boundNames: readonly string[]) {
@@ -149,6 +156,33 @@ describe('installing compiled systems on a host that loads a library', () => {
expect(f.reported.length).toBeGreaterThan(afterFirst);
});
+ it('hands the host the script epoch, which moves when a row does', () => {
+ const f = fixture(['DriftSystem']);
+ const Drift = f.Drift;
+ const system = defineSystem([Query(Mut(Drift))], () => {}, { name: 'DriftSystem' });
+ const entity = f.world.spawn();
+ f.world.insert(entity, Drift, { x: 0 });
+
+ f.runner.run(system);
+ f.runner.run(system);
+ // Nothing moved between them, and the host may keep its rows only
+ // because this number said so.
+ expect(f.epochs.length).toBe(2);
+ expect(f.epochs[1]).toBe(f.epochs[0]);
+
+ // A row claimed, and a row given up. Neither moves an address the engine
+ // can see, and a deletion does not even change the column's length — so
+ // this is the only report the host gets.
+ const second = f.world.spawn();
+ f.world.insert(second, Drift, { x: 0 });
+ f.runner.run(system);
+ expect(f.epochs[2]).toBeGreaterThan(f.epochs[1]!);
+
+ f.world.remove(second, Drift);
+ f.runner.run(system);
+ expect(f.epochs[3]).toBeGreaterThan(f.epochs[2]!);
+ });
+
it('marks the Changed ticks the compiled code could not leave', () => {
const f = fixture(['DriftSystem']);
const Drift = f.Drift;
diff --git a/src/esengine/aot/AotDispatcher.hpp b/src/esengine/aot/AotDispatcher.hpp
index a8bbeb506..c5a4aefc1 100644
--- a/src/esengine/aot/AotDispatcher.hpp
+++ b/src/esengine/aot/AotDispatcher.hpp
@@ -20,6 +20,9 @@
* Commands come back rather than being applied. A despawn invalidates
* the rows just handed over, so who applies them decides when — and
* this class does not know how to remove a component by name anyway.
+ *
+ * One arena PER SYSTEM, not one shared: a shared one is overwritten by
+ * the next system and nothing can be kept across frames.
*/
#pragma once
@@ -54,6 +57,7 @@ public:
names_.push_back(decl.name != nullptr ? decl.name : "");
bound_.push_back(::esengine::aot::bind(decl, components, resources, candidates));
}
+ arenas_ = std::vector<CallArena>(bound_.size());
return true;
}
@@ -90,12 +94,12 @@ public:
* Run one system, and hand back what it wrote.
*
* `candidates` is the FALLBACK, walked only by a query that could not name
- * its own column — ask {@link narrowsAt} first. Resources are resolved per
- * call because the contract promises an address for the length of one; the
- * components were resolved at install.
+ * its own column — ask {@link narrowsAt} first. `world` decides whether last
+ * frame's rows still stand; an unknown stamp repacks. Resources are resolved
+ * per call because the contract promises an address for one call only.
*/
std::span<const EsCmd> run(std::size_t i, std::span<const std::uint32_t> candidates,
- const ResourceLookup& resources) {
+ const ResourceLookup& resources, WorldStamp world = {}) {
if (i >= bound_.size()) return {};
// Asked again where install could not name everything: a pool the
// scripting language owns does not exist until an entity has that
@@ -105,16 +109,25 @@ public:
bound_[i] = ::esengine::aot::bind(module_.systems()[i], components_, resources_, candidates_);
}
if (bound_[i].fn == nullptr) return {};
- return runBound(bound_[i], candidates, resources, arena_);
+ return runBound(bound_[i], candidates, resources, arenas_[i], world);
+ }
+
+ /** Entities that system's last {@link run} covered. See CallArena. */
+ std::uint32_t candidatesWalked(std::size_t i) const {
+ return i < arenas_.size() ? arenas_[i].candidatesWalked() : 0u;
}
- /** Entities the last {@link run} was paid over. See CallArena. */
- std::uint32_t candidatesWalked() const { return arena_.candidatesWalked(); }
+ /** Rows that system's last {@link run} wrote — zero when it kept last
+ * frame's, which is the only way to see the saving happen. */
+ std::uint32_t rowsPacked(std::size_t i) const {
+ return i < arenas_.size() ? arenas_[i].rowsPacked() : 0u;
+ }
/** Close the module and forget the bindings — they point into it. */
void reset() {
bound_.clear();
names_.clear();
+ arenas_.clear();
components_ = {};
resources_ = {};
candidates_ = {};
@@ -134,7 +147,8 @@ private:
/** Optional, and absent on a host that cannot enumerate a column: then every
* query falls back to the candidates the caller passes. */
CandidateLookup candidates_;
- CallArena arena_;
+ /** One per system, so a row table can outlive the call that built it. */
+ std::vector<CallArena> arenas_;
};
} // namespace esengine::aot
diff --git a/src/esengine/aot/AotHost.hpp b/src/esengine/aot/AotHost.hpp
index bc428b078..fb4d0bf21 100644
--- a/src/esengine/aot/AotHost.hpp
+++ b/src/esengine/aot/AotHost.hpp
@@ -19,9 +19,10 @@
* after the first frame at a given size.
*
* A row table is a function of two things: which entities match, and
- * where their components are. This answers the first — see
- * {@link narrowest}. The second is open: unlike the web road
- * (sdk/src/ecs/aot/AotDispatch.ts) this repacks every frame.
+ * where their components are. {@link narrowest} answers the first;
+ * {@link WorldStamp} answers the second, and when neither moved last
+ * frame's rows are this frame's. Same model as the web road
+ * (sdk/src/ecs/aot/AotDispatch.ts), reached through different doors.
*/
#pragma once
@@ -59,6 +60,21 @@ using Candidates = std::optional<std::span<const std::uint32_t>>;
/** A column's members, asked per call because a pool grows between them. */
using CandidatesOf = std::function<Candidates()>;
+/**
+ * Whether any stored component MOVED — one number over every pool's version.
+ *
+ * `known` false means nobody could say, and then a held address must be
+ * re-resolved: trusting one because nothing could tell us it moved is how a
+ * compiled system reads somebody else's bytes.
+ */
+struct WorldStamp {
+ double at = 0.0;
+ bool known = false;
+
+ /** Same world, and both sides sure of it. Unknown never equals anything. */
+ bool operator==(const WorldStamp& o) const { return known && o.known && at == o.at; }
+};
+
/** One declared `Query`: its components, in the order the query names them. */
struct QuerySpec {
std::vector<ComponentAt> comps;
@@ -112,23 +128,37 @@ public:
std::uint32_t commandCapacity() const { return static_cast<std::uint32_t>(cmds_.size()); }
/**
- * Entities the last `run` was PAID OVER, summed across its queries.
+ * Entities the last `run` covered, summed across its queries.
*
- * This is what a compiled system costs, not the body — measured at 20
- * ns/entity for three multiply-adds and 21 for four substeps with a square
- * root each. A count, because a clock reads a tenfold scan as a busy machine.
+ * The query's BREADTH, counted whether or not the rows were repacked — it is
+ * what a system would be paid over, and a ceiling on it is what says the
+ * dispatcher is not scanning the world (bench/aot-native/frame-bench.mjs).
*/
std::uint32_t candidatesWalked() const { return walked_; }
+ /** Rows the last `run` actually wrote. Zero when it reused last frame's,
+ * which is the whole saving and the only way to see it happen. */
+ std::uint32_t rowsPacked() const { return packed_; }
+
private:
friend std::span<const EsCmd> run(SystemFn, std::span<const std::uint32_t>,
- std::span<const QuerySpec>, std::span<void* const>, CallArena&);
+ std::span<const QuerySpec>, std::span<void* const>,
+ CallArena&, WorldStamp);
std::vector<es_addr_t> rows_;
std::vector<EsQueryRows> queries_;
std::vector<es_addr_t> resources_;
std::vector<EsCmd> cmds_;
std::uint32_t count_ = 0;
std::uint32_t walked_ = 0;
+ std::uint32_t packed_ = 0;
+ /** The world the rows were packed against, and EVERY column they were packed
+ * from, by identity — a query matches on all of them, and an engine pool can
+ * gain a member without moving an address, so without moving the stamp. */
+ WorldStamp packedAt_;
+ std::vector<std::span<const std::uint32_t>> from_;
+ /** Per-call scratch, kept so a steady frame allocates nothing. */
+ std::vector<std::span<const std::uint32_t>> lists_;
+ std::vector<std::span<const std::uint32_t>> columns_;
EsSysCtx ctx_{};
};
@@ -144,43 +174,77 @@ inline std::span<const EsCmd> run(SystemFn fn,
std::span<const std::uint32_t> fallback,
std::span<const QuerySpec> queries,
std::span<void* const> resources,
- CallArena& arena) {
- arena.rows_.clear();
+ CallArena& arena,
+ WorldStamp world = {}) {
+ // Its own column where a query has one, everybody where it has none. A freed
+ // slot in a script column reads as an entity nothing resolves for, so the
+ // completeness check below drops it like any other miss.
arena.walked_ = 0;
- arena.queries_.assign(queries.size(), EsQueryRows{});
- arena.resources_.assign(resources.size(), es_addr_t{});
-
- // Offsets first, addresses after: one vector holding every query's rows
- // moves under the first query's pointer as the second grows, and the ctx
- // has to point at something that will still be there during the call.
- std::vector<std::size_t> starts(queries.size());
- std::vector<std::uint32_t> counts(queries.size(), 0);
+ arena.lists_.assign(queries.size(), {});
+ arena.columns_.clear();
+ // A query that cannot say who it matches cannot say whether that changed, so
+ // falling back to the caller's list also gives up the row table.
+ bool narrowedEvery = !queries.empty();
for (std::size_t q = 0; q < queries.size(); ++q) {
- starts[q] = arena.rows_.size();
- const auto& comps = queries[q].comps;
- // Its own column where it has one, everybody where it does not. A
- // freed slot in a script column reads as an entity nothing resolves
- // for, so the completeness check below drops it like any other miss.
- const Candidates narrowed = narrowest(queries[q]);
- const std::span<const std::uint32_t> over = narrowed ? *narrowed : fallback;
- arena.walked_ += static_cast<std::uint32_t>(over.size());
- for (std::uint32_t e : over) {
- const std::size_t mark = arena.rows_.size();
- arena.rows_.push_back(static_cast<es_addr_t>(e));
- bool complete = true;
- for (const auto& at : comps) {
- void* p = at(e);
- if (p == nullptr) { complete = false; break; }
- arena.rows_.push_back(reinterpret_cast<es_addr_t>(p));
- }
- if (complete) ++counts[q];
- else arena.rows_.resize(mark);
+ Candidates best;
+ for (const CandidatesOf& source : queries[q].sources) {
+ if (!source) continue;
+ const Candidates got = source();
+ if (!got) continue;
+ arena.columns_.push_back(*got);
+ if (!best || got->size() < best->size()) best = got;
}
+ if (!best) narrowedEvery = false;
+ arena.lists_[q] = best ? *best : fallback;
+ arena.walked_ += static_cast<std::uint32_t>(arena.lists_[q].size());
}
- for (std::size_t q = 0; q < queries.size(); ++q) {
- arena.queries_[q].rows = reinterpret_cast<es_addr_t>(arena.rows_.data() + starts[q]);
- arena.queries_[q].count = counts[q];
+
+ bool reuse = narrowedEvery && (world == arena.packedAt_)
+ && arena.from_.size() == arena.columns_.size();
+ for (std::size_t c = 0; reuse && c < arena.columns_.size(); ++c) {
+ if (arena.columns_[c].data() != arena.from_[c].data()
+ || arena.columns_[c].size() != arena.from_[c].size()) {
+ reuse = false;
+ }
+ }
+
+ arena.packed_ = 0;
+ if (!reuse) {
+ arena.rows_.clear();
+ arena.queries_.assign(queries.size(), EsQueryRows{});
+ // Offsets first, addresses after: one vector holding every query's rows
+ // moves under the first query's pointer as the second grows, and the ctx
+ // has to point at something that will still be there during the call.
+ std::vector<std::size_t> starts(queries.size());
+ std::vector<std::uint32_t> counts(queries.size(), 0);
+ for (std::size_t q = 0; q < queries.size(); ++q) {
+ starts[q] = arena.rows_.size();
+ const auto& comps = queries[q].comps;
+ for (std::uint32_t e : arena.lists_[q]) {
+ const std::size_t mark = arena.rows_.size();
+ arena.rows_.push_back(static_cast<es_addr_t>(e));
+ bool complete = true;
+ for (const auto& at : comps) {
+ void* p = at(e);
+ if (p == nullptr) { complete = false; break; }
+ arena.rows_.push_back(reinterpret_cast<es_addr_t>(p));
+ }
+ if (complete) ++counts[q];
+ else arena.rows_.resize(mark);
+ }
+ arena.packed_ += counts[q];
+ }
+ for (std::size_t q = 0; q < queries.size(); ++q) {
+ arena.queries_[q].rows = reinterpret_cast<es_addr_t>(arena.rows_.data() + starts[q]);
+ arena.queries_[q].count = counts[q];
+ }
+ // Only a table that narrowed EVERY query can be offered again; an
+ // unknown stamp is recorded as unknown and never matches.
+ arena.packedAt_ = narrowedEvery ? world : WorldStamp{};
+ arena.from_ = arena.columns_;
}
+
+ arena.resources_.assign(resources.size(), es_addr_t{});
for (std::size_t r = 0; r < resources.size(); ++r) {
arena.resources_[r] = reinterpret_cast<es_addr_t>(resources[r]);
}
@@ -331,12 +395,13 @@ inline BoundSystem bind(const EsSystemDecl& decl,
inline std::span<const EsCmd> runBound(const BoundSystem& bound,
std::span<const std::uint32_t> fallback,
const ResourceLookup& resources,
- CallArena& arena) {
+ CallArena& arena,
+ WorldStamp world = {}) {
if (bound.fn == nullptr) return {};
std::vector<void*> addresses;
addresses.reserve(bound.resourceNames.size());
for (const char* name : bound.resourceNames) addresses.push_back(resources(name));
- return run(bound.fn, fallback, bound.queries, addresses, arena);
+ return run(bound.fn, fallback, bound.queries, addresses, arena, world);
}
/**
diff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cpp
index 3f4750179..281c7c9ce 100644
--- a/tests/aot/test_aot_host.cpp
+++ b/tests/aot/test_aot_host.cpp
@@ -778,3 +778,155 @@ TEST_CASE("the generated table answers who has a component, and says so by name"
addBystanders(w, 5);
CHECK(of()->size() == w.entities.size() + w.bystanders.size());
}
+
+// ---------------------------------------------------------------------------
+// Keeping the row table. A cache is worth what its invalidation is worth, so
+// every test here moves the world one way and asks whether the rows followed.
+// The stamp is the real pair the host sums, so a hole in it is a hole here.
+// ---------------------------------------------------------------------------
+
+namespace {
+
+const ecs::Transform* xf(World& w, std::uint32_t e) {
+ return w.registry.tryGet<ecs::Transform>(Entity::fromRaw(e));
+}
+
+/** An entity holding a Mover row and NO Transform, so no query matches it yet. */
+void addMoverOnly(World& w) {
+ Entity e = w.registry.create();
+ w.entities.push_back(e.id());
+ w.movers.push_back(MoverRow{60.0, 1.0, -1.0});
+ const std::uint32_t at = e.index();
+ if (at >= w.moverSparse.size()) w.moverSparse.resize(at + 1u, 0u);
+ w.moverSparse[at] = static_cast<std::uint32_t>(w.movers.size());
+ w.moverOwners.push_back(e.id());
+}
+
+} // namespace
+
+TEST_CASE("a table packed against a standing world is not packed again") {
+ World w = makeWorld();
+ addBystanders(w, 100);
+ const aot::BoundSystem bound = aot::bind(*declOf("MoveSystem"), componentsOf(w),
+ resourcesOf(w), candidatesOf(w));
+ REQUIRE(bound.fn != nullptr);
+
+ const aot::WorldStamp world{w.registry.layoutEpoch(), true};
+ aot::CallArena arena;
+ aot::runBound(bound, {}, resourcesOf(w), arena, world);
+ CHECK(arena.rowsPacked() == w.entities.size());
+ const float afterFirst = xf(w, w.entities[1])->position.x;
+
+ // Same world, same stamp: the rows stand, and the system still runs over
+ // them — a saving, not a skip.
+ aot::runBound(bound, {}, resourcesOf(w), arena, world);
+ CHECK(arena.rowsPacked() == 0u);
+ CHECK(arena.candidatesWalked() == w.entities.size());
+ CHECK(xf(w, w.entities[1])->position.x != afterFirst);
+}
+
+TEST_CASE("an unknown stamp is never the same world twice") {
+ World w = makeWorld();
+ const aot::BoundSystem bound = aot::bind(*declOf("MoveSystem"), componentsOf(w),
+ resourcesOf(w), candidatesOf(w));
+ aot::CallArena arena;
+ // The default: a host that cannot date its world. Trusting an address
+ // because nobody could say it moved is how compiled code reads other bytes.
+ for (int i = 0; i < 3; ++i) {
+ aot::runBound(bound, {}, resourcesOf(w), arena);
+ CHECK(arena.rowsPacked() == w.entities.size());
+ }
+}
+
+TEST_CASE("a query that falls back keeps no table") {
+ World w = makeWorld();
+ // No candidate lookup: the list is the caller's, and a caller that cannot
+ // say who matches cannot say whether that changed either.
+ const aot::BoundSystem wide = aot::bind(*declOf("MoveSystem"), componentsOf(w), resourcesOf(w));
+ const aot::WorldStamp world{w.registry.layoutEpoch(), true};
+ aot::CallArena arena;
+ for (int i = 0; i < 3; ++i) {
+ aot::runBound(wide, w.everyEntity(), resourcesOf(w), arena, world);
+ CHECK(arena.rowsPacked() == w.entities.size());
+ }
+}
+
+TEST_CASE("a cached table follows the world, whichever way it moved") {
+ World kept = makeWorld();
+ World fresh = makeWorld();
+ // Scenery first, so Transform is the LONGER column and the query narrows on
+ // Mover. Without it Transform is the shorter one, the narrowed column moves
+ // when it does, and the subcase below stops testing anything.
+ addBystanders(kept, 50);
+ addBystanders(fresh, 50);
+ addMoverOnly(kept);
+ addMoverOnly(fresh);
+
+ const aot::BoundSystem keptBound = aot::bind(*declOf("MoveSystem"), componentsOf(kept),
+ resourcesOf(kept), candidatesOf(kept));
+ // No candidate lookup and no stamp: the control repacks every frame by
+ // construction, so the two agree only if invalidation is right.
+ const aot::BoundSystem freshBound = aot::bind(*declOf("MoveSystem"), componentsOf(fresh),
+ resourcesOf(fresh));
+ aot::CallArena keptArena;
+ aot::CallArena freshArena;
+ double scriptEpoch = 0.0;
+
+ const auto step = [&] {
+ const aot::WorldStamp world{kept.registry.layoutEpoch() + scriptEpoch, true};
+ aot::runBound(keptBound, kept.everyEntity(), resourcesOf(kept), keptArena, world);
+ aot::runBound(freshBound, fresh.everyEntity(), resourcesOf(fresh), freshArena);
+ for (std::size_t i = 0; i < fresh.entities.size(); ++i) {
+ const auto* a = xf(kept, kept.entities[i]);
+ const auto* b = xf(fresh, fresh.entities[i]);
+ REQUIRE((a == nullptr) == (b == nullptr));
+ if (a == nullptr) continue;
+ REQUIRE(a->position.x == b->position.x);
+ REQUIRE(a->position.y == b->position.y);
+ }
+ };
+
+ step();
+ step();
+
+ SUBCASE("an entity joins by gaining the component the query did NOT narrow on") {
+ // The trap this exists for. The query narrows on Mover, whose column does
+ // not move; Transform's does, and an emplace inside its capacity bumps
+ // no version — so only checking EVERY column the query names reports it.
+ for (World* w : { &kept, &fresh }) {
+ w->registry.emplace<ecs::Transform>(Entity::fromRaw(w->entities.back()));
+ }
+ step();
+ step();
+ CHECK(xf(kept, kept.entities.back()) != nullptr);
+ CHECK(xf(kept, kept.entities.back())->position.x != 0.0f);
+ }
+
+ SUBCASE("an entity leaves, leaving a hole no span can see") {
+ // A freed slot keeps the column's pointer AND its length: `next_` never
+ // shrinks. Nothing but the script epoch can report this one.
+ const std::uint32_t gone = kept.entities[4];
+ for (World* w : { &kept, &fresh }) {
+ w->moverOwners[4] = aot::NO_OWNER;
+ w->moverSparse[Entity::fromRaw(w->entities[4]).index()] = 0u;
+ }
+ scriptEpoch += 1.0;
+ step();
+ const float held = xf(kept, gone)->position.x;
+ step();
+ CHECK(xf(kept, gone)->position.x == held);
+ }
+
+ SUBCASE("the same entities, at other addresses") {
+ // What the stamp is really for. Sorting permutes the pool IN PLACE, so
+ // the column keeps its pointer and its length while every row it named
+ // moves; `rebuildSparse` bumps the version and that is the only tell.
+ for (World* w : { &kept, &fresh }) {
+ w->registry.sort<ecs::Transform>([](const ecs::Transform& a, const ecs::Transform& b) {
+ return a.position.x < b.position.x;
+ });
+ }
+ step();
+ step();
+ }
+}