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.

perf(aot): a compiled system's cost was the plumbing, so the plumbing went

yhh19e820cb363d
diff --git a/bench/aot-frame/README.md b/bench/aot-frame/README.md
index b156b0600..34124f57a 100644
--- a/bench/aot-frame/README.md
+++ b/bench/aot-frame/README.md
@@ -33,28 +33,35 @@ computed different things have no ratio between them.
recomposed every frame whether or not it moved, so the idle run is the same engine
work minus the system.
-Per entity per frame, across the three bodies (a run varies about ±10% here, so
-these are ranges over the bodies AND over repeated runs):
-
-| entities | interpreted | compiled | ratio |
-|---|---|---|---|
-| 1,000 | 181–239 ns | 95–99 ns | 1.8–2.5× |
-| 5,000 | 213–252 ns | 97–117 ns | 1.9–2.3× |
-| 20,000 | 253–301 ns | 142–147 ns | 1.7–2.1× |
-
-**The compiled cost does not move with the body.** Thin is three multiply-adds; heavy
-is four unrolled integration substeps with a square root and a bounce test each. The
-compiled column is the same number for both, at every scale. What a compiled system
-costs today is not its code — it is the row array, the address per component per row,
-the SysCtx and the `Changed` marking the host does around the call. That is the
-measurement REARCH_AOT.md §7.2 was owed: **~110 ns per entity per frame of plumbing**.
-
-**The interpreted cost barely moves with the body either** — under V8 the body is
-JIT-compiled to machine code, so thirty extra flops disappear next to the per-entity
-protocol (a component copy in, a proxy, a write-back). Both sides are plumbing.
-
-So the ~2× here is **entirely the cheaper boundary**, not faster arithmetic, and it is
-the same effect §16 measured for §12.B from the other side.
+Per entity per frame, in nanoseconds:
+
+| entities | body | interpreted | compiled | ratio |
+|---|---|---|---|---|
+| 1,000 | thin / thick / heavy / script | 159 / 182 / 171 / 245 | 28 / 30 / 33 / 23 | 5.2–10.6× |
+| 5,000 | thin / thick / heavy / script | 162 / 183 / 168 / 251 | 28 / 30 / 34 / 27 | 5.0–9.2× |
+| 20,000 | thin / thick / heavy / script | 200 / 241 / 200 / 354 | 32 / 37 / 37 / 29 | 5.4–12.2× |
+
+`script` is `thin` again over a script component instead of the engine's `Transform`.
+Interpreted, it is the most expensive row on the board — a pooled component costs more
+to hand to a closure than an engine one does. Compiled, it is the cheapest.
+
+**The first measurement of this said 83 ns compiled, and the plumbing was the reason.**
+Packing rows was allocating a `[entity, addr, addr]` array per entity per frame,
+copying it word by word into the arena, rebuilding the query cache's key from scratch
+every frame, and re-finding each component's address resolver per entity. That work is
+now a plan built once per system and a flat block written straight through
+(`AotDispatch`). Same machine, same minute, interpreted column unchanged:
+
+| | before | after |
+|---|---|---|
+| thin compiled | 83.1 ns | 27.5 ns |
+| script compiled | 81.9 ns | 27.3 ns |
+| thin interpreted (control) | 163.2 ns | 162.3 ns |
+
+**The body is only now becoming visible.** Under 83 ns of plumbing, thin and heavy
+compiled to the same number; under 27 ns, heavy costs about 20% more than thin. That is
+the shape to expect from here: the closer the plumbing gets to zero, the more a ratio
+depends on what the system actually computes.
## What this is NOT
diff --git a/bench/aot-frame/frame-bench.mjs b/bench/aot-frame/frame-bench.mjs
index 562229799..d611770af 100644
--- a/bench/aot-frame/frame-bench.mjs
+++ b/bench/aot-frame/frame-bench.mjs
@@ -135,9 +135,13 @@ async function measure(sdk, fixture, wasmDir, body, compiled) {
world.insert(e, fixture.Mover, {
dx: rand() - 0.5, dy: rand() - 0.5, speed: 40 + rand() * 80, boost: rand() < 0.5 ? 1 : 0,
});
+ if (body === 'script') world.insert(e, fixture.Pos, { x: 0, y: 0, z: 0 });
entities.push(e);
}
- const systems = { thin: fixture.thinSystem, thick: fixture.thickSystem, heavy: fixture.heavySystem };
+ const systems = {
+ thin: fixture.thinSystem, thick: fixture.thickSystem,
+ heavy: fixture.heavySystem, script: fixture.scriptSystem,
+ };
if (body) app.addSystemToSchedule(Schedule.Update, systems[body]);
const step = async () => {
@@ -157,7 +161,7 @@ async function measure(sdk, fixture, wasmDir, body, compiled) {
// measurements of one thing, and the ratio between them means nothing.
let checksum = 0;
for (const e of entities) {
- const p = world.get(e, Transform).position;
+ const p = body === 'script' ? world.get(e, fixture.Pos) : world.get(e, Transform).position;
checksum += p.x + p.y + p.z;
}
@@ -172,6 +176,8 @@ const CONFIGS = [
{ key: 'thick compiled', body: 'thick', compiled: true },
{ key: 'heavy interpreted', body: 'heavy', compiled: false },
{ key: 'heavy compiled', body: 'heavy', compiled: true },
+ { key: 'script interpreted', body: 'script', compiled: false },
+ { key: 'script compiled', body: 'script', compiled: true },
{ key: 'idle scene', body: null, compiled: false },
];
@@ -239,7 +245,7 @@ async function main() {
+ `${c.body ? ((r.median - idle.median) * 1e6 / ENTITIES).toFixed(1) : ''}`);
}
console.log('-'.repeat(72));
- for (const body of ['thin', 'thick', 'heavy']) {
+ for (const body of ['thin', 'thick', 'heavy', 'script']) {
const i = of(`${body} interpreted`);
const c = of(`${body} compiled`);
const agree = i.checksum === c.checksum;
@@ -247,7 +253,7 @@ async function main() {
+ `frame ${(i.median / c.median).toFixed(2)}x `
+ `${agree ? 'same result' : `RESULT MISMATCH ${i.checksum} vs ${c.checksum}`}`);
}
- const mismatched = ['thin', 'thick', 'heavy'].some((body) =>
+ const mismatched = ['thin', 'thick', 'heavy', 'script'].some((body) =>
of(`${body} interpreted`).checksum !== of(`${body} compiled`).checksum);
console.log('-'.repeat(72));
console.log('A ratio here is a FLOOR: this runtime has a JIT, and AOT exists for the ones');
diff --git a/bench/aot-frame/project/src/systems.ts b/bench/aot-frame/project/src/systems.ts
index be5051b8c..9692790bc 100644
--- a/bench/aot-frame/project/src/systems.ts
+++ b/bench/aot-frame/project/src/systems.ts
@@ -15,6 +15,8 @@
import { defineComponent, defineSystem, Query, Mut, Res, Time, Transform } from 'esengine';
export const Mover = defineComponent('BenchMover', { dx: 0, dy: 0, speed: 0, boost: 0 });
+/** A script component standing where `Transform` stands, for the `script` body. */
+export const Pos = defineComponent('BenchPos', { x: 0, y: 0, z: 0 });
/**
* Three multiply-adds per entity.
@@ -32,6 +34,26 @@ export const thinSystem = defineSystem(
{ name: 'BenchThin' },
);
+/**
+ * `thin` again, over a script component instead of the engine's `Transform`.
+ *
+ * The difference between the two is the BRIDGE: an engine component's address
+ * comes from a wasm call per entity per frame, a script one's from a pool this
+ * SDK owns. Which of them the plumbing is made of decides where Stage 3 goes.
+ *
+ * @compiled
+ */
+export const scriptSystem = defineSystem(
+ [Query(Mut(Pos), Mover), Res(Time)],
+ (query, time) => {
+ for (const [, pos, mover] of query) {
+ pos.x += mover.dx * mover.speed * time.delta;
+ pos.y += mover.dy * mover.speed * time.delta;
+ }
+ },
+ { name: 'BenchScript' },
+);
+
/**
* Four substeps with a bounce test each, unrolled — the subset has no loop but
* `rowLoop`. Its weight separates the cost of a BODY from the cost of handing
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index d296ba3f8..b9a4423a9 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -9276,6 +9276,7 @@ tabIndex: number | undefined
## World — class @public
```
@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
+@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a9e8112d4..5ca60bf8b 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -9469,6 +9469,7 @@ tabIndex: number | undefined
## World — class @public
```
@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
+@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index b5a7083ae..1276e4518 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -9271,6 +9271,7 @@ tabIndex: number | undefined
## World — class @public
```
@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
+@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index b4859b7a4..c0f9a177d 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -9523,6 +9523,7 @@ tabIndex: number | undefined
## World — class @public
```
@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
+@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 21df5f6ee..cdb0bd633 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -9299,6 +9299,7 @@ tabIndex: number | undefined
## World — class @public
```
@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
+@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
diff --git a/sdk/src/ecs/aot/AotContext.ts b/sdk/src/ecs/aot/AotContext.ts
index b7940e121..4a907de61 100644
--- a/sdk/src/ecs/aot/AotContext.ts
+++ b/sdk/src/ecs/aot/AotContext.ts
@@ -34,8 +34,6 @@ export interface AotCommand {
readonly a: number;
}
-/** A row: the entity, then one address per component the query names. */
-export type AotRow = readonly number[];
/**
* The per-call scratch, in engine memory. One instance per system is enough —
@@ -60,15 +58,21 @@ export class AotContext {
/**
* Lay out one call and answer the ctx address.
*
- * `queries[k]` is the rows of the k-th declared Query, in the order the
- * system will walk them; `resources[j]` is the address of the j-th declared
- * Res. Both are the caller's because both come from maps the caller owns.
+ * The rows arrive packed — every query's, back to back, in query order —
+ * because the caller wrote them there as it walked. `offsets[k]`/`counts[k]`
+ * locate the k-th Query's; `resources[j]` is the j-th Res. One `set` copies
+ * the block, where a row at a time was a word at a time (bench/aot-frame).
*/
- build(queries: readonly (readonly AotRow[])[], resources: readonly number[]): number {
- const rowWords = queries.reduce(
- (n, rows) => n + rows.reduce((m, r) => m + r.length, 0), 0);
+ build(
+ rows: Uint32Array,
+ rowWords: number,
+ offsets: Uint32Array,
+ counts: Uint32Array,
+ resources: readonly number[],
+ ): number {
+ const queryCount = counts.length;
const need = SYSCTX_WORDS
- + queries.length * QUERYROWS_WORDS
+ + queryCount * QUERYROWS_WORDS
+ rowWords
+ resources.length
+ 1 // the count, which the code writes back
@@ -79,27 +83,21 @@ export class AotContext {
const w = this.words;
// Laid out in one pass, each table after the last, so the addresses are
// known before anything that points at them is written.
- let at = SYSCTX_WORDS;
- const queryTable = at;
- at += queries.length * QUERYROWS_WORDS;
- const rowsAt: number[] = [];
- for (const rows of queries) {
- rowsAt.push(at);
- for (const row of rows) {
- for (const v of row) w[at++] = v;
- }
- }
+ const queryTable = SYSCTX_WORDS;
+ const rowsAt = queryTable + queryCount * QUERYROWS_WORDS;
+ w.set(rows.subarray(0, rowWords), rowsAt);
+ let at = rowsAt + rowWords;
const resTable = at;
for (const r of resources) w[at++] = r;
const countAt = at++;
w[countAt] = 0;
const cmdBuf = at;
- queries.forEach((rows, k) => {
+ for (let k = 0; k < queryCount; k++) {
const slot = queryTable + k * QUERYROWS_WORDS;
- w[slot] = base + rowsAt[k]! * 4;
- w[slot + 1] = rows.length;
- });
+ w[slot] = base + (rowsAt + offsets[k]!) * 4;
+ w[slot + 1] = counts[k]!;
+ }
w[0] = base + queryTable * 4;
w[1] = base + resTable * 4;
w[2] = base + cmdBuf * 4;
diff --git a/sdk/src/ecs/aot/AotDispatch.ts b/sdk/src/ecs/aot/AotDispatch.ts
new file mode 100644
index 000000000..bb1e7b175
--- /dev/null
+++ b/sdk/src/ecs/aot/AotDispatch.ts
@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AotDispatch.ts
+ * @brief One call of the contract, in place of the closure.
+ *
+ * @details `REARCH_AOT_ABI.md` §2.1 gives the host four jobs around a compiled
+ * system: pack the rows, resolve the resources, ready the command
+ * buffer, apply what came back. This is that host on web, and what it
+ * costs is not a detail — `bench/aot-frame` measured the packing at
+ * ~110 ns per entity per frame, the same for a three-multiply body and
+ * for one with four unrolled integration steps. A compiled system's
+ * cost today IS this file.
+ *
+ * So everything a call does twice is done once. A PLAN per system holds
+ * what cannot change between frames: the resolved components, one
+ * address resolver each, and the query cache's key and dependency ids —
+ * the same two the interpreted `QueryInstance` precomputes, through the
+ * same door, so the two paths cannot disagree about what a query means.
+ *
+ * Rows are written straight into a flat scratch and handed over as one
+ * block. The nested `[entity, addr, addr]` arrays this replaced were two
+ * allocations per entity per frame and then a word-by-word copy of the
+ * same numbers.
+ */
+
+import type { AnyComponentDef } from '../component';
+import { computeQueryCacheKey, type World } from '../world';
+import type { Entity } from '../../types';
+import { CMD_DESPAWN } from './AotContext';
+import type { AotRuntime } from './AotRuntime';
+import type { AotTwin } from './AotSystems';
+
+/** No `With`/`Without` on a compiled query; the subset has no syntax for one. */
+const NO_FILTERS: AnyComponentDef[] = [];
+
+/** What one declared Query needs, resolved once. */
+interface QueryPlan {
+ /** The components it names, in the order the rows must carry them. */
+ readonly comps: AnyComponentDef[];
+ /** One address resolver per component, hoisted out of the row loop. */
+ readonly resolvers: ((entity: Entity) => number | undefined)[];
+ /** The components it may write AND something is watching — the only ones
+ * worth a `Changed` tick, since `recordChanged` would drop the rest. */
+ readonly mutated: AnyComponentDef[];
+ readonly key: string;
+ readonly depIds: symbol[];
+ /** `1 + comps.length`: the entity, then one address each (§2.2). */
+ readonly width: number;
+ /** False when a name in the manifest is not a component of this world; such
+ * a query matches nothing rather than reading address zero. */
+ readonly resolved: boolean;
+}
+
+interface Plan {
+ readonly queries: QueryPlan[];
+ readonly resources: readonly string[];
+ /** Rows for every query, back to back, in query order. */
+ scratch: Uint32Array;
+ /** Rows written per query this call. */
+ readonly counts: Uint32Array;
+ /** Where each query's rows begin in `scratch`, in words. */
+ readonly offsets: Uint32Array;
+ /** How much of `scratch` this call filled. */
+ rowWords: number;
+}
+
+/**
+ * The compiled half of the scheduler: given a twin, run it against this world.
+ *
+ * One per installed runtime, holding one plan per twin — a system's shape is
+ * fixed by the build that produced it, so nothing here is recomputed per frame.
+ */
+export class AotDispatch {
+ private readonly plans = new Map<AotTwin, Plan>();
+
+ constructor(private readonly world: World, private readonly runtime: AotRuntime) {}
+
+ run(twin: AotTwin): void {
+ const plan = this.planFor_(twin);
+ this.packRows_(plan);
+
+ const resources = plan.resources.map((name) => this.runtime.addresses.resourceAt(name) ?? 0);
+ this.runtime.ctx.build(plan.scratch, plan.rowWords, plan.offsets, plan.counts, resources);
+ twin.call(this.runtime.ctx.address);
+
+ for (const cmd of this.runtime.ctx.commands()) {
+ // Only despawn is in the v1 record set (REARCH_AOT_ABI.md §2.3).
+ if (cmd.kind === CMD_DESPAWN) this.world.despawn(cmd.a as unknown as Entity);
+ }
+ this.markChanged_(plan);
+ }
+
+ /** Drop the plans; the next call rebuilds them. */
+ reset(): void {
+ this.plans.clear();
+ }
+
+ /**
+ * Every row of every query, written into one block.
+ *
+ * A row whose components cannot all answer is not written: an address of zero
+ * is a real address, and the compiled code would read somebody else's bytes.
+ */
+ private packRows_(plan: Plan): void {
+ let at = 0;
+ for (let k = 0; k < plan.queries.length; k++) {
+ const q = plan.queries[k];
+ plan.offsets[k] = at;
+ if (!q.resolved) {
+ plan.counts[k] = 0;
+ continue;
+ }
+ const entities = this.world.queryEntities(
+ q.comps, NO_FILTERS, NO_FILTERS, q.key, undefined, q.depIds);
+ plan.scratch = grow(plan.scratch, at + entities.length * q.width);
+ const rows = plan.scratch;
+ const width = q.width;
+ const resolvers = q.resolvers;
+ let n = 0;
+ for (let i = 0; i < entities.length; i++) {
+ const entity = entities[i];
+ const write = at + n * width;
+ let whole = true;
+ for (let c = 0; c < resolvers.length; c++) {
+ const address = resolvers[c](entity);
+ if (address === undefined) { whole = false; break; }
+ rows[write + 1 + c] = address;
+ }
+ if (!whole) continue;
+ rows[write] = entity as unknown as number;
+ n++;
+ }
+ plan.counts[k] = n;
+ at += n * width;
+ }
+ plan.rowWords = at;
+ }
+
+ /**
+ * The `Changed` ticks the compiled code could not record — it never calls
+ * back. Asked once per component rather than per row: `recordChanged`
+ * self-gates on the same answer, and on a hot path with nothing listening
+ * that is a per-row cost spent for nothing.
+ */
+ private markChanged_(plan: Plan): void {
+ for (let k = 0; k < plan.queries.length; k++) {
+ const q = plan.queries[k];
+ const n = plan.counts[k];
+ if (q.mutated.length === 0 || n === 0) continue;
+ for (const def of q.mutated) {
+ if (!this.world.isChangeTracked(def)) continue;
+ const base = plan.offsets[k];
+ for (let i = 0; i < n; i++) {
+ this.world.markChanged(plan.scratch[base + i * q.width] as unknown as Entity, def);
+ }
+ }
+ }
+ }
+
+ private planFor_(twin: AotTwin): Plan {
+ let plan = this.plans.get(twin);
+ if (plan) return plan;
+ const queries = twin.decl.queries.map((args, k): QueryPlan => {
+ const comps: AnyComponentDef[] = [];
+ for (const a of args) {
+ const def = this.runtime.addresses.componentNamed(a.comp);
+ if (def) comps.push(def);
+ }
+ const resolved = comps.length === args.length;
+ return {
+ comps,
+ resolvers: comps.map((c) => this.world.addressResolver(c)),
+ mutated: [...(twin.mutated[k] ?? [])],
+ key: computeQueryCacheKey(comps),
+ depIds: comps.map((c) => c._id as symbol),
+ width: 1 + comps.length,
+ resolved,
+ };
+ });
+ plan = {
+ queries,
+ resources: twin.decl.resources,
+ scratch: new Uint32Array(0),
+ counts: new Uint32Array(queries.length),
+ offsets: new Uint32Array(queries.length),
+ rowWords: 0,
+ };
+ this.plans.set(twin, plan);
+ return plan;
+ }
+}
+
+/** At least `words` long, keeping what is already written. */
+function grow(rows: Uint32Array, words: number): Uint32Array {
+ if (rows.length >= words) return rows;
+ const bigger = new Uint32Array(Math.max(words, rows.length * 2, 64));
+ bigger.set(rows);
+ return bigger;
+}
diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.ts
index b8b248c79..5c0ad1674 100644
--- a/sdk/src/ecs/bridge/BuiltinBridge.ts
+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts
@@ -674,6 +674,11 @@ export class BuiltinBridge {
* Null where this backend serves no flat memory.
*/
resolveComponentAddress(cppName: string): ((entity: Entity) => number | undefined) | null {
+ // Where there is a pointer function, ask it: the heap resolver below also
+ // fills three typed-array views for the accessors to read fields through,
+ // and a caller that wants only the address pays for them per entity.
+ const ptrFn = this.resolvePtrFn(cppName);
+ if (ptrFn) return (e: Entity) => ptrFn(e) || undefined;
const resolveHeap = this.memory_?.resolveComponentHeap(cppName);
if (!resolveHeap) return null;
const heap: ComponentHeap = SCRATCH_HEAP();
diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.ts
index 6958fb7d7..2c12ff0c1 100644
--- a/sdk/src/ecs/system.ts
+++ b/sdk/src/ecs/system.ts
@@ -17,7 +17,7 @@ import {
} from './event';
import type { Entity } from '../types';
import type { World } from './world';
-import { CMD_DESPAWN, type AotRow } from './aot/AotContext';
+import { AotDispatch } from './aot/AotDispatch';
import type { AotRuntime } from './aot/AotRuntime';
import type { AotTwin } from './aot/AotSystems';
@@ -411,6 +411,9 @@ export class SystemRunner {
* there is nothing to dispatch to (docs/REARCH_AOT.md §9).
*/
private aot_: AotRuntime | null = null;
+ /** The compiled half of this runner: everything a twin needs around its call
+ * (docs/REARCH_AOT_ABI.md §2.1), and the plans that keep it off the frame. */
+ private aotDispatch_: AotDispatch | null = null;
constructor(world: World, resources: ResourceStorage, eventRegistry?: EventRegistry) {
this.world_ = world;
@@ -421,6 +424,7 @@ export class SystemRunner {
/** @internal Install the twins a build produced. */
useAot(runtime: AotRuntime | null): void {
this.aot_ = runtime;
+ this.aotDispatch_ = runtime ? new AotDispatch(this.world_, runtime) : null;
}
setTimingEnabled(enabled: boolean): void {
@@ -555,50 +559,12 @@ export class SystemRunner {
}
/**
- * One call of the contract in place of the closure: materialise the rows,
- * lay out a SysCtx, call the compiled symbol, apply what it recorded. The
- * compiled code calls nothing, so everything it could not do is here — the
- * commands it appended, and the Changed ticks a `Mut` implies.
+ * A compiled system's frame: the dispatcher does the contract, this keeps the
+ * scheduler's own books — what it cost, and when it last ran.
*/
private runCompiled_(system: SystemDef, twin: AotTwin): void {
- const aot = this.aot_!;
const t0 = this.timings_ ? performance.now() : 0;
-
- const queries: AotRow[][] = [];
- for (const args of twin.decl.queries) {
- const comps: AnyComponentDef[] = [];
- for (const a of args) {
- const def = aot.addresses.componentNamed(a.comp);
- if (def) comps.push(def);
- }
- const rows: AotRow[] = [];
- if (comps.length === args.length) {
- for (const entity of this.world_.getEntitiesWithComponents(comps)) {
- const row: number[] = [entity as unknown as number];
- let whole = true;
- for (const def of comps) {
- const at = aot.addresses.componentAt(def, entity);
- // A query that matched but whose storage cannot answer is
- // not a row. Reading zero would be a read of address zero.
- if (at === undefined) { whole = false; break; }
- row.push(at);
- }
- if (whole) rows.push(row);
- }
- }
- queries.push(rows);
- }
-
- const resources = twin.decl.resources.map((name) => aot.addresses.resourceAt(name) ?? 0);
- aot.ctx.build(queries, resources);
- twin.call(aot.ctx.address);
-
- for (const cmd of aot.ctx.commands()) {
- // Only despawn is in the v1 record set (REARCH_AOT_ABI.md §2.3).
- if (cmd.kind === CMD_DESPAWN) this.world_.despawn(cmd.a as unknown as Entity);
- }
- this.markCompiledChanges_(twin, queries);
-
+ this.aotDispatch_!.run(twin);
if (this.timings_) {
const name = system._name;
this.timings_.set(name, (this.timings_.get(name) ?? 0) + (performance.now() - t0));
@@ -606,23 +572,6 @@ export class SystemRunner {
this.systemTicks_.set(system._id, this.world_.getWorldTick());
}
- /**
- * The Changed ticks the compiled code could not record. Asked ONCE per
- * component rather than per entity: `recordChanged` self-gates on the same
- * answer, and on the hot path with nothing listening this is where a
- * per-row loop would have been spent for nothing.
- */
- private markCompiledChanges_(twin: AotTwin, queries: readonly AotRow[][]): void {
- twin.mutated.forEach((comps, k) => {
- const rows = queries[k];
- if (!rows || rows.length === 0) return;
- for (const def of comps) {
- if (!this.world_.isChangeTracked(def)) continue;
- for (const row of rows) this.world_.markChanged(row[0] as unknown as Entity, def);
- }
- });
- }
-
private flushSystem_(system: SystemDef, args: unknown[], t0: number): void {
for (let i = 0; i < args.length; i++) {
if (args[i] instanceof CommandsInstance) {
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index ca848d272..04343b05f 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -11,7 +11,7 @@ import type { CppRegistry, ESEngineModule } from '../wasm';
import { handleWasmError } from '../wasm/wasmError';
import { BuiltinBridge, convertFromWasm, convertForWasm, type BridgeConnectOptions, type BuiltinMethods } from './bridge/BuiltinBridge';
import { ScriptStorage } from './ScriptStorage';
-import type { PoolMemory } from './ScriptPool';
+import type { PoolMemory, ScriptPool } from './ScriptPool';
import { NameIndex } from './NameIndex';
import { ChangeTracker } from './ChangeTracker';
import { QueryCache, type QueryCacheStats } from './QueryCache';
@@ -1182,14 +1182,23 @@ export class World {
* entity per frame.
*/
addressOfComponent(component: AnyComponentDef, entity: Entity): number | undefined {
+ return this.addressResolver(component)(entity);
+ }
+
+ /**
+ * @internal The same answer as a function, for a caller with a whole column
+ * to walk: the lookup above is per entity, and a loop that pays it per row is
+ * paying to be told the same thing every time.
+ */
+ addressResolver(component: AnyComponentDef): (entity: Entity) => number | undefined {
let at = this.addressOf_.get(component._id as symbol);
if (at === undefined) {
at = isBuiltinComponent(component)
? (this.builtin_.resolveComponentAddress(component._cppName) ?? NO_ADDRESS)
- : (e: Entity) => this.scripts_.poolFor(component._id as symbol)?.address(e);
+ : scriptAddress(this.scripts_, component._id as symbol);
this.addressOf_.set(component._id as symbol, at);
}
- return at(entity);
+ return at;
}
/** Cleared with the bridge, because a reconnect may serve other memory. */
@@ -1198,3 +1207,17 @@ export class World {
/** A component whose backend serves no flat memory: never has an address. */
const NO_ADDRESS = (): undefined => undefined;
+
+/**
+ * A script component's address, with the pool looked up once rather than per
+ * entity. Sound because a pool is never dropped once made, and because the pool
+ * re-views itself after a growth — the block moving is its business, not this
+ * closure's.
+ */
+function scriptAddress(scripts: ScriptStorage, id: symbol): (entity: Entity) => number | undefined {
+ let pool: ScriptPool | undefined;
+ return (entity: Entity) => {
+ pool ??= scripts.poolFor(id);
+ return pool?.address(entity);
+ };
+}
diff --git a/sdk/tests/aot-context.test.ts b/sdk/tests/aot-context.test.ts
index c30139db5..07f344416 100644
--- a/sdk/tests/aot-context.test.ts
+++ b/sdk/tests/aot-context.test.ts
@@ -32,6 +32,24 @@ import type { Entity } from '../src/types';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
const e = (n: number): Entity => n as unknown as Entity;
const N = 16;
+
+/**
+ * The rows as the dispatcher hands them over: one flat block in query order,
+ * with where each query starts and how many it has. Packing them is
+ * `AotDispatch`'s job in a running world; this is the same shape by hand, which
+ * is what keeps this test about the ARENA and not about the packer.
+ */
+function packed(rows: readonly (readonly number[])[]): {
+ words: Uint32Array; rowWords: number; offsets: Uint32Array; counts: Uint32Array;
+} {
+ const width = rows.length > 0 ? rows[0]!.length : 0;
+ const words = new Uint32Array(rows.length * width);
+ rows.forEach((r, i) => words.set(r, i * width));
+ return {
+ words, rowWords: rows.length * width,
+ offsets: new Uint32Array([0]), counts: new Uint32Array([rows.length]),
+ };
+}
const FRAMES = 8;
function findEmcc(): string | null {
@@ -161,8 +179,9 @@ describe('a compiled system, called by the SDK', () => {
const ctx = new AotContext(memory);
for (let f = 0; f < FRAMES; f++) {
- const rows = live.map((id) => [id, pool.address(e(id))!] as const);
- const at = ctx.build([rows], [resources.addressOf('Time')!]);
+ const rows = packed(live.map((id) => [id, pool.address(e(id))!]));
+ const at = ctx.build(rows.words, rows.rowWords, rows.offsets, rows.counts,
+ [resources.addressOf('Time')!]);
decay(at);
// The same loop, in TypeScript, over the plain objects.
@@ -210,7 +229,10 @@ describe('a compiled system, called by the SDK', () => {
const ctx = new AotContext(memory);
// An empty query still needs a well-formed table: `count` is zero and
// `rows` must point somewhere the code will not read.
- (api['es_sys_Decay'] as (c: number) => void)(ctx.build([[]], [resources.addressOf('Time')!]));
+ const none = packed([]);
+ (api['es_sys_Decay'] as (c: number) => void)(ctx.build(
+ none.words, none.rowWords, none.offsets, none.counts,
+ [resources.addressOf('Time')!]));
expect(ctx.commands()).toEqual([]);
});
});