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
feat(aot): the native row table is kept while the world stands
yhh94e32f85d836
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 thenative road every compiled system was handed EVERY LIVE ENTITY as a candidateeach frame and resolved every component of each one. The absence of adiff --git a/bench/aot-native/frame-bench.mjs b/bench/aot-native/frame-bench.mjsindex 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.mdindex 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.cppindex 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 includedSpan 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.hppindex 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.cppindex 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.mdindex 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: () => numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: () => numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: () => numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: () => numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: () => numberdiff --git a/sdk/src/ecs/aot/installNativeAot.ts b/sdk/src/ecs/aot/installNativeAot.tsindex 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.tsindex 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.tsindex 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.hppindex 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::aotdiff --git a/src/esengine/aot/AotHost.hpp b/src/esengine/aot/AotHost.hppindex 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.cppindex 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();+ }+}