Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(aot): the native host runs compiled systems, and the SDK installs them

yhh89ed8bcbb81a
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index 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.cpp
host/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.cpp
host/media/native_audio.cpp
host/media/audio_spectrum.cpp
host/media/ktx2_decode.cpp
diff --git a/native/host/Bindings.hpp b/native/host/Bindings.hpp
index 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.cpp
index 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);
#endif
registerNetBindings(h, global);
registerTextEditorBindings(h, global);
diff --git a/native/host/bindings/AotBindings.cpp b/native/host/bindings/AotBindings.cpp
new file mode 100644
index 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 eshost
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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) => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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) => void
diff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 is
diff --git a/sdk/tests/aot-native-install.test.ts b/sdk/tests/aot-native-install.test.ts
new file mode 100644
index 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);
+ });
+});