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
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.mdindex 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 enginework 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 NOTdiff --git a/bench/aot-frame/frame-bench.mjs b/bench/aot-frame/frame-bench.mjsindex 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.tsindex 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 handingdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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[]) => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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[]) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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[]) => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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[]) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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[]) => voiddiff --git a/sdk/src/ecs/aot/AotContext.ts b/sdk/src/ecs/aot/AotContext.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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([]);});});