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 host runs compiled systems, and the SDK installs them
yhh89ed8bcbb81a
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex ce138cb71..ac3fd5238 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -326,6 +326,10 @@ if(ESTELLA_QUICKJS_DIR)$<$<BOOL:${ESTELLA_DESKTOP}>:host/media/text_edit.cpp>host/bindings/NetBindings.cpphost/bindings/TextEditorBindings.cpp+ host/bindings/AotBindings.cpp+ # The name table a compiled system is dispatched through — generated+ # from the same reflection the component bindings above come from.+ ${CMAKE_CURRENT_SOURCE_DIR}/../src/esengine/aot/AotComponents.generated.cpphost/media/native_audio.cpphost/media/audio_spectrum.cpphost/media/ktx2_decode.cppdiff --git a/native/host/Bindings.hpp b/native/host/Bindings.hppindex 98af3b25b..4554b9eb6 100644--- a/native/host/Bindings.hpp+++ b/native/host/Bindings.hpp@@ -59,6 +59,11 @@ void registerSteamBindings(HostState& h, JSValue global);/** es_fetch over the platform's native networking. */void registerNetBindings(HostState& h, JSValue global);+/** es_aot_* — the compiled systems a shipped build loads, and the naming a+ * host does for them. Absent on the web, where the module shares the engine's+ * memory and the rows are packed in JS. */+void registerAotBindings(HostState& h, JSValue global);+/** es_textEditor_* over the platform's soft keyboard — bound ONLY when the* platform has one, so the SDK gates its editing surface on real availability* exactly as it does audio. */diff --git a/native/host/Runtime.cpp b/native/host/Runtime.cppindex 70e6df741..adc91d527 100644--- a/native/host/Runtime.cpp+++ b/native/host/Runtime.cpp@@ -422,6 +422,7 @@ void initRuntime(HostState& h) {registerInputBindings(h, global);#if defined(ESTELLA_DESKTOP)registerSteamBindings(h, global);+ registerAotBindings(h, global);#endifregisterNetBindings(h, global);registerTextEditorBindings(h, global);diff --git a/native/host/bindings/AotBindings.cpp b/native/host/bindings/AotBindings.cppnew file mode 100644index 000000000..b53c67189--- /dev/null+++ b/native/host/bindings/AotBindings.cpp@@ -0,0 +1,226 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file AotBindings.cpp+ * @brief es_aot_* — the compiled systems a shipped desktop build loads.+ * @details The web road hands the module the engine's memory and lets JS pack+ * the rows. Here the engine IS the process: an address is a pointer+ * nothing in QuickJS can hold, so the rows are packed on this side and+ * JS says only which system to run.+ *+ * What this owns is the naming. `aot::Dispatcher` does the loading and+ * the calling; the engine's own components come from the generated+ * table; and a project's own live in the pool the SDK allocated out of+ * the shared heap, so JS reports where those rows are — by OFFSET,+ * which is the one currency both sides already speak (heap.hpp).+ *+ * Those reports land in slots with stable addresses, because a pool+ * reallocates as it grows and a resolver bound at install would keep+ * reading the first home (aot::fromMovingRows).+ *+ * @author ESEngine Team+ * @date 2026+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the Apache License, Version 2.0.+ */+#include "Bindings.hpp"++#include "heap.hpp"+#include "esn_shim.hpp"++#include "esengine/aot/AotCommands.hpp"+#include "esengine/aot/AotComponents.generated.hpp"+#include "esengine/aot/AotDispatcher.hpp"+#include "esengine/aot/EngineDigest.generated.h"++#include <deque>+#include <string>+#include <unordered_map>+#include <vector>++using namespace esengine;++namespace eshost {+namespace {++/**+ * Everything the es_aot_* calls share for one loaded module.+ *+ * A deque for the slots, not a vector: `fromMovingRows` holds the address of+ * one, and a vector hands those out and then invalidates them on the next push.+ */+struct AotState {+ aot::Dispatcher dispatcher;+ std::deque<aot::RowSpan> scriptSpans;+ std::unordered_map<std::string, aot::RowSpan*> scriptByName;+ std::unordered_map<std::string, void*> resources;+ /** Candidates for a call, rebuilt per run. Kept so a frame allocates none. */+ std::vector<std::uint32_t> candidates;+ bool installed = false;+};++AotState& state() {+ static AotState s;+ return s;+}++/** The slot for a script component, created on first mention and never moved. */+aot::RowSpan* slotFor(const std::string& name) {+ AotState& s = state();+ auto found = s.scriptByName.find(name);+ if (found != s.scriptByName.end()) return found->second;+ s.scriptSpans.emplace_back();+ aot::RowSpan* slot = &s.scriptSpans.back();+ s.scriptByName.emplace(name, slot);+ return slot;+}++/**+ * Who can name a component here: the engine's own from the generated table,+ * and the project's from whatever JS has reported. A name neither answers for+ * leaves its system unbound, which is the interpreter keeping it.+ */+aot::ComponentAt componentAt(const char* name) {+ if (aot::isEngineComponent(name)) return aot::engineComponentAt(*host().registry, name);+ AotState& s = state();+ auto found = s.scriptByName.find(name);+ return found == s.scriptByName.end() ? aot::ComponentAt{} : aot::fromMovingRows(found->second);+}++void* resourceAt(const char* name) {+ AotState& s = state();+ auto found = s.resources.find(name);+ return found == s.resources.end() ? nullptr : found->second;+}++// — the calls —++/** es_aot_install(path) -> system count, or -1 with the reason logged. */+JSValue js_install(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 1) return JS_NewInt32(ctx, -1);+ const char* path = JS_ToCString(ctx, argv[0]);+ if (path == nullptr) return JS_NewInt32(ctx, -1);++ AotState& s = state();+ std::string why;+ const bool ok = s.dispatcher.install(path, aot::abiHash(ES_ENGINE_ABI_DIGEST),+ componentAt, resourceAt, &why);+ if (!ok) ESHOST_LOGE("[aot] %s: %s", path, why.c_str());+ JS_FreeCString(ctx, path);+ s.installed = ok;+ return JS_NewInt32(ctx, ok ? static_cast<int>(s.dispatcher.count()) : -1);+}++/** es_aot_index(name) -> the index the scheduler keeps, or -1. */+JSValue js_index(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 1) return JS_NewInt32(ctx, -1);+ const char* name = JS_ToCString(ctx, argv[0]);+ if (name == nullptr) return JS_NewInt32(ctx, -1);+ const std::size_t at = state().dispatcher.indexOf(name);+ JS_FreeCString(ctx, name);+ return JS_NewInt32(ctx, at == aot::Dispatcher::npos ? -1 : static_cast<int>(at));+}++/** es_aot_bound(i) -> whether that system resolved; an unbound one interprets. */+JSValue js_bound(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 1) return JS_FALSE;+ std::uint32_t i = 0;+ JS_ToUint32(ctx, &i, argv[0]);+ return JS_NewBool(ctx, state().dispatcher.boundAt(i));+}++/**+ * es_aot_script_rows(name, sparseOff, sparseCount, rowsOff, stride, indexMask)+ *+ * Where a project component's rows are NOW. Called again whenever the pool+ * moves them; passing 0 for the row offset says the pool is gone.+ */+JSValue js_scriptRows(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 6) return JS_FALSE;+ const char* name = JS_ToCString(ctx, argv[0]);+ if (name == nullptr) return JS_FALSE;+ std::uint32_t sparseOff = 0, sparseCount = 0, rowsOff = 0, stride = 0, mask = 0;+ JS_ToUint32(ctx, &sparseOff, argv[1]);+ JS_ToUint32(ctx, &sparseCount, argv[2]);+ JS_ToUint32(ctx, &rowsOff, argv[3]);+ JS_ToUint32(ctx, &stride, argv[4]);+ JS_ToUint32(ctx, &mask, argv[5]);++ // Range-checked through the heap rather than trusted: an offset is a number+ // JS computed, and a wrong one here is a read outside the arena.+ void* sparse = heapPtr(sparseOff, static_cast<std::size_t>(sparseCount) * sizeof(std::uint32_t));+ void* rows = rowsOff == 0 ? nullptr : heapPtr(rowsOff, stride);+ aot::RowSpan* slot = slotFor(name);+ JS_FreeCString(ctx, name);+ if (sparse == nullptr && sparseCount > 0) return JS_FALSE;++ *slot = aot::RowSpan{+ static_cast<const std::uint32_t*>(sparse), sparseCount,+ static_cast<unsigned char*>(rows), stride, mask,+ };+ return JS_TRUE;+}++/** es_aot_resource(name, offset, bytes) -> where one call reads that resource. */+JSValue js_resource(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 3) return JS_FALSE;+ const char* name = JS_ToCString(ctx, argv[0]);+ if (name == nullptr) return JS_FALSE;+ std::uint32_t offset = 0, bytes = 0;+ JS_ToUint32(ctx, &offset, argv[1]);+ JS_ToUint32(ctx, &bytes, argv[2]);+ void* at = heapPtr(offset, bytes);+ if (at != nullptr) state().resources[name] = at;+ JS_FreeCString(ctx, name);+ return JS_NewBool(ctx, at != nullptr);+}++/**+ * es_aot_run(i) -> records this host did not know, or -1 when nothing ran.+ *+ * The candidates are every live entity: a row survives only where every+ * component resolved, so the completeness check IS the filter. Narrowing it to+ * a pool would need the smallest one, and which that is depends on the query.+ */+JSValue js_run(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 1) return JS_NewInt32(ctx, -1);+ std::uint32_t i = 0;+ JS_ToUint32(ctx, &i, argv[0]);+ AotState& s = state();+ if (!s.installed || !s.dispatcher.boundAt(i)) return JS_NewInt32(ctx, -1);++ s.candidates.clear();+ host().registry->forEachEntity([&s](esengine::Entity e) { s.candidates.push_back(e.id()); });+ const auto cmds = s.dispatcher.run(i, s.candidates, resourceAt);+ // 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)));+}++/** es_aot_reset() — close the module and forget every name. */+JSValue js_reset(JSContext* ctx, JSValueConst, int, JSValueConst*) {+ AotState& s = state();+ s.dispatcher.reset();+ s.scriptByName.clear();+ s.scriptSpans.clear();+ s.resources.clear();+ s.installed = false;+ return JS_UNDEFINED;+}++} // namespace++void registerAotBindings(HostState& h, JSValue global) {+ const auto fn = [&](const char* name, JSCFunction* impl, int arity) {+ JS_SetPropertyStr(h.js, global, name, JS_NewCFunction(h.js, impl, name, arity));+ };+ fn("es_aot_install", js_install, 1);+ fn("es_aot_index", js_index, 1);+ fn("es_aot_bound", js_bound, 1);+ fn("es_aot_script_rows", js_scriptRows, 6);+ fn("es_aot_resource", js_resource, 3);+ fn("es_aot_run", js_run, 1);+ fn("es_aot_reset", js_reset, 0);+}++} // namespace eshostdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex a9f259621..e5539b851 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 scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex f6a03e480..4d288c709 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 scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex edb89e614..36ae826cc 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 scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 791dc182e..77f290bcd 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 scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 6307afd1f..b61d7bfc4 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 scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.tsindex d497dab0c..c24dd7b57 100644--- a/sdk/src/ecs/aot/AotSystems.ts+++ b/sdk/src/ecs/aot/AotSystems.ts@@ -112,6 +112,12 @@ export class AotSystems {* the wrong one is the refusal it is supposed to be.*/addressBytes: 4 | 8 = 4,+ /**+ * Which declarations become twins. The handshake is still checked over+ * the WHOLE manifest, because that is what the module is; a host that+ * could bind only some of it still loaded all of it. Default: all.+ */+ runs: (name: string) => boolean = () => true,): void {// Two questions with two fixes, so two answers rather than one that can// only say "something moved".@@ -142,6 +148,7 @@ export class AotSystems {throw new Error(`AOT module refused: it declares '${decl.name}' but exports no `+ `'${decl.symbol}'`);}+ if (!runs(decl.name)) continue;const mutated = decl.queries.map((q) => q.filter((a) => a.mut).map((a) => resolve(a.comp))diff --git a/sdk/src/ecs/aot/installNativeAot.ts b/sdk/src/ecs/aot/installNativeAot.tsnew file mode 100644index 000000000..bf0b17383--- /dev/null+++ b/sdk/src/ecs/aot/installNativeAot.ts@@ -0,0 +1,209 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file installNativeAot.ts+ * @brief Compiled systems on a host that loads a library, not a wasm module.+ *+ * @details The web road hands the module the engine's memory and packs the rows+ * here. A native host IS the engine's process: an address is a pointer+ * nothing in JS can hold, so the host packs them and this says only+ * which system to run (`es_aot_*`, native/host/bindings/AotBindings.cpp).+ *+ * What stays on this side is what only this side knows. Where a script+ * component's rows are, because the pool is ours and it MOVES them; and+ * the Changed ticks, because compiled code never calls back and the+ * host has no idea who is watching.+ *+ * Refuses rather than degrades, exactly as the wasm road does: the+ * handshake is checked here too, at the width a loading host runs at.+ */++import { getComponent, type AnyComponentDef } from '../component';+import type { World } from '../world';+import type { SystemRunner } from '../system';+import type { Entity } from '../../types';+import { WasmPoolMemory, type WasmHeap } from '../WasmPoolMemory';+import { AotSystems, type AotManifest, type AotTwin } from './AotSystems';+import type { AotDispatcher, AotRuntime } from './AotRuntime';++/** `sizeof(es_addr_t)` where a loaded library runs. */+const NATIVE_ADDRESS_BYTES = 8;++/** The `es_aot_*` surface, as one object so a test can stand in for the host. */+export interface NativeAotBindings {+ install(path: string): number;+ index(name: string): number;+ bound(index: number): boolean;+ scriptRows(name: string, sparseOffset: number, sparseCount: number,+ rowsOffset: number, stride: number, indexMask: number): boolean;+ resource(name: string, offset: number, bytes: number): boolean;+ run(index: number): number;+ reset(): void;+}++export interface InstallNativeAotOptions {+ readonly world: World;+ readonly runner: SystemRunner;+ /** Absolute path to the module the package staged. */+ readonly modulePath: string;+ /** What the build wrote beside it — the names and shapes, checked here. */+ readonly manifest: AotManifest;+ /** The host's linear heap: what a pool allocates from, so an offset means+ * the same thing on both sides of the boundary. */+ readonly heap: WasmHeap;+ /** The host calls, for a test to stand in for. Absent ⇒ read off globalThis. */+ readonly bindings?: NativeAotBindings;+}++/** The entity index mask a sparse table is addressed by, from the engine's own. */+const ENTITY_INDEX_MASK = 0xfffff;++/** Read the `es_aot_*` globals a native host bound, or null where it bound none. */+export function nativeAotBindings(+ scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,+): NativeAotBindings | null {+ const fn = (name: string): ((...args: never[]) => unknown) | null =>+ (typeof scope[name] === 'function' ? scope[name] as (...args: never[]) => unknown : null);+ const install = fn('es_aot_install');+ const run = fn('es_aot_run');+ if (install === null || run === null) return null;+ const call = <T>(name: string, fallback: T) => (...args: unknown[]): T => {+ const f = fn(name);+ return f === null ? fallback : (f as (...a: unknown[]) => T)(...args);+ };+ return {+ install: (path) => (install as (p: string) => number)(path),+ index: call<number>('es_aot_index', -1),+ 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),+ reset: call<void>('es_aot_reset', undefined as void),+ };+}++/**+ * Install a module and hand the runner its twins, or null where this host has+ * no `es_aot_*` at all — which is every host but a native one.+ */+export function installNativeAot(opts: InstallNativeAotOptions): AotRuntime | null {+ const bindings = opts.bindings ?? nativeAotBindings();+ if (bindings === null) return null;++ // Before the first pooled component exists: a pool cannot move to other+ // memory once it has rows, and the host addresses only this heap.+ opts.world.useScriptPoolMemory(new WasmPoolMemory(opts.heap));++ const count = bindings.install(opts.modulePath);+ if (count < 0) return null;++ // Only the ones the host BOUND become twins: the runner calls a twin+ // wherever it finds one, so a twin that dispatches to nothing is a system+ // that never runs at all.+ const byTwin = new Map<string, number>();+ for (const decl of opts.manifest.systems) {+ const at = bindings.index(decl.name);+ if (at >= 0 && bindings.bound(at)) byTwin.set(decl.name, at);+ }+ const running = opts.manifest.systems.filter((decl) => byTwin.has(decl.name));++ // The handshake at the loading width, over the WHOLE manifest — that is+ // what the module is. The exports throw because the host holds the function+ // pointers here, so a twin's `call` reaching one is a bug, loudly.+ const systems = new AotSystems();+ const exports: Record<string, unknown> = {};+ for (const decl of opts.manifest.systems) {+ exports[decl.symbol] = () => {+ throw new Error(`AOT: ${decl.name} is the host's to call, not this runtime's`);+ };+ }+ systems.install(opts.manifest, exports, (name) => getComponent(name),+ () => [], NATIVE_ADDRESS_BYTES, (name) => byTwin.has(name));++ // Every script component any running twin names, so one epoch change+ // re-reports all of them rather than whichever twin happened to run first.+ const pooled = new Set<string>();+ for (const decl of running) {+ for (const query of decl.queries) for (const arg of query) pooled.add(arg.comp);+ }++ const runtime: AotRuntime = {+ systems,+ // Absent on this road: nothing here resolves an address, because nothing+ // here can hold one. Present in the type so the wasm road cannot omit it.+ addresses: {+ componentNamed: (name: string) => getComponent(name),+ resourceAt: () => undefined,+ } as unknown as AotRuntime['addresses'],+ ctx: null as unknown as AotRuntime['ctx'],+ dispatcherFor: (world) => new NativeAotDispatch(world, bindings, byTwin, pooled),+ };+ opts.runner.useAot(runtime);+ return runtime;+}++/**+ * One twin's frame on a host that packs its own rows.+ *+ * Two things happen here and nothing else: the pools are re-reported when they+ * may have moved, and the Changed ticks are marked. The call itself is one+ * number crossing the boundary.+ */+class NativeAotDispatch implements AotDispatcher {+ /** The epoch the pools were last reported at. Null means never. */+ private reportedAt_: number | null | undefined = undefined;++ constructor(+ private readonly world: World,+ private readonly bindings: NativeAotBindings,+ private readonly indexByName: ReadonlyMap<string, number>,+ private readonly pooled: ReadonlySet<string>,+ ) {}++ run(twin: AotTwin): void {+ // Every twin that exists is one the host bound; install made sure of it.+ const at = this.indexByName.get(twin.decl.name)!;+ this.reportPools_();+ this.bindings.run(at);+ this.markChanged_(twin);+ }++ /**+ * Tell the host where each script component's rows are NOW.+ *+ * Keyed on the layout epoch, which is what the engine and the pools both+ * bump when anything moved. Null means nobody could say, and then the answer+ * has to be "assume they moved" — the same rule the row cache follows.+ */+ private reportPools_(): void {+ const epoch = this.world.layoutEpoch();+ if (epoch !== null && epoch === this.reportedAt_) return;+ this.reportedAt_ = epoch;+ for (const name of this.pooled) {+ const def = getComponent(name);+ const span = def === undefined ? undefined : this.world.scriptSpanOf(def);+ if (span === undefined) continue;+ this.bindings.scriptRows(name, span.sparse, span.sparseCount,+ span.rows, span.stride, ENTITY_INDEX_MASK);+ }+ }++ /**+ * The ticks the compiled code could not leave. The matched set is walked+ * here rather than carried back: it is the same set — every component+ * present — and a query is cheaper than marshalling the rows. Only when+ * something watches, because that walk is the whole cost.+ */+ private markChanged_(twin: AotTwin): void {+ for (let k = 0; k < twin.decl.queries.length; k++) {+ const mutated = (twin.mutated[k] ?? []).filter((def) => this.world.isChangeTracked(def));+ if (mutated.length === 0) continue;+ const comps = twin.decl.queries[k]!+ .map((arg) => getComponent(arg.comp))+ .filter((def): def is AnyComponentDef => def !== undefined);+ for (const entity of this.world.queryEntities(comps)) {+ for (const def of mutated) this.world.markChanged(entity as Entity, def);+ }+ }+ }+}diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex f97535a98..b415e4e4e 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 Where a SCRIPT component's whole column is, for a host that+ * walks it in its own address space. Undefined for an engine component,+ * whose column belongs to the registry and is reached by its own door.+ */+ scriptSpanOf(component: AnyComponentDef):+ { rows: number; stride: number; sparse: number; sparseCount: number } | undefined {+ if (isBuiltinComponent(component)) return undefined;+ return this.scripts_.poolFor(component._id as symbol)?.span();+ }+/*** @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 isdiff --git a/sdk/tests/aot-native-install.test.ts b/sdk/tests/aot-native-install.test.tsnew file mode 100644index 000000000..1b9c44194--- /dev/null+++ b/sdk/tests/aot-native-install.test.ts@@ -0,0 +1,170 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file aot-native-install.test.ts+ * @brief Installing compiled systems on a host that loads a library.+ *+ * @details The host is stood in for, because what is worth pinning here is not+ * that a `.dll` opens — `tests/aot/test_aot_host.cpp` does that against+ * a real one — but the three things this side owes it: only the systems+ * it BOUND become twins, the pools are re-reported when they may have+ * moved, and the Changed ticks the compiled code cannot leave.+ *+ * 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.+ */+import { describe, it, expect } from 'vitest';+import { World } from '../src/ecs/world';+import { defineComponent } from '../src/ecs/component';+import { defineSystem, SystemRunner } from '../src/ecs/system';+import { Query, Mut, Changed } from '../src/ecs/query';+import { ResourceStorage } from '../src/ecs/resource';+import { engineAbiDigest, projectShapeDigest } from '../src/ecs/aot/abiDigest';+import type { AotManifest } from '../src/ecs/aot/AotSystems';+import { installNativeAot, type NativeAotBindings } from '../src/ecs/aot/installNativeAot';+import type { WasmHeap } from '../src/ecs/WasmPoolMemory';++/** Declared per test, not at module scope: the suite's setup resets the+ * component context, and `installNativeAot` resolves names through it. */+const declareDrift = () => defineComponent('Drift', { x: 0 });++/** A linear heap, the way a native host's arena looks from here. */+function fakeHeap(): WasmHeap {+ const bytes = new Uint8Array(1 << 16);+ let next = 8;+ return {+ _malloc: (size: number) => { const at = next; next += (size + 7) & ~7; return at; },+ _free: () => {},+ HEAPU8: bytes,+ };+}++const MANIFEST: AotManifest = {+ engineAbi: engineAbiDigest(8),+ projectShapes: projectShapeDigest([{ name: 'Drift', fields: ['x'] }]),+ systems: [+ { name: 'DriftSystem', symbol: 'es_sys_Drift', queries: [[{ comp: 'Drift', mut: true }]], resources: [] },+ { name: 'OtherSystem', symbol: 'es_sys_Other', queries: [[{ comp: 'Drift', mut: true }]], resources: [] },+ ],+};++/** A host that bound only the systems it was told to. */+function fakeHost(boundNames: readonly string[]) {+ const order = MANIFEST.systems.map((s) => s.name);+ const calls: number[] = [];+ const reported: { name: string; rows: number; sparseCount: number }[] = [];+ const bindings: NativeAotBindings = {+ install: () => order.length,+ index: (name) => order.indexOf(name),+ bound: (i) => boundNames.includes(order[i] ?? ''),+ scriptRows: (name, _sparse, sparseCount, rows) => {+ reported.push({ name, rows, sparseCount });+ return true;+ },+ resource: () => true,+ run: (i) => { calls.push(i); return 0; },+ reset: () => {},+ };+ return { bindings, calls, reported };+}++function fixture(boundNames: readonly string[]) {+ const Drift = declareDrift();+ const world = new World();+ const runner = new SystemRunner(world, new ResourceStorage());+ const host = fakeHost(boundNames);+ const runtime = installNativeAot({+ world, runner, modulePath: 'systems.dll', manifest: MANIFEST,+ heap: fakeHeap(), bindings: host.bindings,+ });+ return { world, runner, runtime, Drift, ...host };+}++describe('installing compiled systems on a host that loads a library', () => {+ it('makes a twin only of what the host bound, so the rest still interpret', () => {+ const f = fixture(['DriftSystem']);+ const Drift = f.Drift;+ expect(f.runtime).not.toBeNull();+ expect(f.runtime!.systems.size).toBe(1);+ expect(f.runtime!.systems.get('DriftSystem')).toBeDefined();+ expect(f.runtime!.systems.get('OtherSystem')).toBeUndefined();++ let interpreted = 0;+ const other = defineSystem([Query(Mut(Drift))], () => { interpreted++; }, { name: 'OtherSystem' });+ const compiled = defineSystem([Query(Mut(Drift))], () => {+ throw new Error('the closure must not run when the host bound this one');+ }, { name: 'DriftSystem' });++ const entity = f.world.spawn();+ f.world.insert(entity, Drift, { x: 0 });+ f.runner.run(compiled);+ f.runner.run(other);++ expect(f.calls).toEqual([0]);+ expect(interpreted).toBe(1);+ });++ it('says nothing at all where the host bound nothing', () => {+ const f = fixture([]);+ const Drift = f.Drift;+ expect(f.runtime!.systems.size).toBe(0);++ let interpreted = 0;+ const system = defineSystem([Query(Mut(Drift))], () => { interpreted++; }, { name: 'DriftSystem' });+ f.runner.run(system);++ expect(f.calls).toEqual([]);+ expect(interpreted).toBe(1);+ });++ it('tells the host where the rows are, once per move rather than per frame', () => {+ 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);+ const afterFirst = f.reported.length;+ expect(afterFirst).toBeGreaterThan(0);+ expect(f.reported[0]!.name).toBe('Drift');++ // Nothing moved, so nothing is said again — the epoch is the whole rule.+ f.runner.run(system);+ expect(f.reported.length).toBe(afterFirst);++ // A claimed row bumps it, and the host is told the new column.+ const second = f.world.spawn();+ f.world.insert(second, Drift, { x: 0 });+ f.runner.run(system);+ expect(f.reported.length).toBeGreaterThan(afterFirst);+ });++ it('marks the Changed ticks the compiled code could not leave', () => {+ const f = fixture(['DriftSystem']);+ const Drift = f.Drift;+ const system = defineSystem([Query(Mut(Drift))], () => {}, { name: 'DriftSystem' });+ // A watcher is the only thing that can tell: the compiled code calls+ // nothing, so a `Mut` it honoured is invisible unless the host records it.+ const watched: number[] = [];+ const watcher = defineSystem([Query(Changed(Drift))], (query) => {+ let n = 0;+ for (const _ of query as Iterable<unknown>) n++;+ watched.push(n);+ }, { name: 'Watcher' });++ const entity = f.world.spawn();+ f.world.insert(entity, Drift, { x: 0 });+ // Past the tick the insert itself marked, so what the watcher sees next+ // is the dispatcher's doing and not the spawn's.+ f.world.advanceTick();+ f.runner.run(watcher);+ f.world.advanceTick();++ f.runner.run(system);+ f.runner.run(watcher);++ expect(watched.at(-1)).toBe(1);+ });+});