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): which road a build takes is a fact about the host, not the caller

yhhafbb686a5fcb
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 6250a1d48..ad0f8637b 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -729,7 +729,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
progress({ phase: 'Compiling systems', detail: `${built.manifest.systems.length} system(s)` });
await mkdir(path.join(payloadDir, 'aot'), { recursive: true });
await cp(built.modulePath, path.join(payloadDir, 'aot', 'systems.wasm'));
- aot = { wasm: 'aot/systems.wasm', manifest: built.manifest };
+ aot = { module: `aot/${path.basename(built.modulePath)}`, manifest: built.manifest };
}
}
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index 646bc9ba7..f2b25ff0e 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -338,7 +338,7 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
progress({ phase: 'Compiling systems', detail: `${built.manifest.systems.length} system(s)` });
await mkdir(path.join(absOut, 'aot'), { recursive: true });
await cp(built.modulePath, path.join(absOut, 'aot', 'systems.wasm'));
- aotArg = `, aot: ${JSON.stringify({ wasm: 'aot/systems.wasm', manifest: built.manifest })}`;
+ aotArg = `, aot: ${JSON.stringify({ module: 'aot/systems.wasm', manifest: built.manifest })}`;
}
const entrySrc =
`import { ${profile.runtimeInit}${installsPlatform ? ', installMiniGamePlatform' : ''}${themeColors ? ', parseThemeOverrides' : ''} } from 'esengine';\n` +
diff --git a/pipeline/tests/export-compiled-systems.test.ts b/pipeline/tests/export-compiled-systems.test.ts
index 00719de60..196174e65 100644
--- a/pipeline/tests/export-compiled-systems.test.ts
+++ b/pipeline/tests/export-compiled-systems.test.ts
@@ -114,10 +114,10 @@ describe('what a package carries for a compiled system', () => {
const res = await run(f);
expect(res.errors).toEqual([]);
const cfg = config(f.out);
- expect(cfg.aot?.wasm).toBe('aot/systems.wasm');
+ expect(cfg.aot?.module).toBe('aot/systems.wasm');
// The path in the config is the path in the package, or the runtime 404s
// at boot and falls back to interpreting with nothing to see.
- expect(existsSync(path.join(f.out, cfg.aot!.wasm))).toBe(true);
+ expect(existsSync(path.join(f.out, cfg.aot!.module))).toBe(true);
expect(cfg.aot?.manifest.systems.map((s) => s.name)).toEqual(['ExportDriftSystem']);
expect(cfg.aot?.manifest.engineAbi).toMatch(/^[0-9a-f]{16}$/);
} finally { rmSync(f.root, { recursive: true, force: true }); }
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index e5539b851..ec555b54d 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -564,7 +564,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (source: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5100,7 +5100,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string; manifest: AotManifest; } | undefined
+aot: { module: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6609,7 +6609,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
+aot: { module: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 4d288c709..4a128c1aa 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -564,7 +564,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (source: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5283,7 +5283,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string; manifest: AotManifest; } | undefined
+aot: { module: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6802,7 +6802,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
+aot: { module: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 36ae826cc..a14f35372 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -559,7 +559,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (source: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5095,7 +5095,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string; manifest: AotManifest; } | undefined
+aot: { module: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6604,7 +6604,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
+aot: { module: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 77f290bcd..5e221dec3 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -559,7 +559,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (source: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -4817,7 +4817,7 @@ url: string
## MiniGameRuntimeConfig — interface @experimental
```
-aot: { wasm: string; manifest: AotManifest; } | undefined
+aot: { module: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -5341,7 +5341,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string; manifest: AotManifest; } | undefined
+aot: { module: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6850,7 +6850,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
+aot: { module: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b61d7bfc4..db5c67304 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -559,7 +559,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (source: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5102,7 +5102,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string; manifest: AotManifest; } | undefined
+aot: { module: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6611,7 +6611,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
+aot: { module: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
@@ -9223,7 +9223,7 @@ tileTerrain: Map<number, number>
## WeChatRuntimeConfig — interface @experimental
```
-aot: { wasm: string; manifest: AotManifest; } | undefined
+aot: { module: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 7b4b039d3..4f624d1e1 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -9,6 +9,8 @@ import { World } from '../ecs/world';
import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, rescopeSystem, type RunCondition } from '../ecs/system';
import { builtinResource, ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';
import { installAot, prepareAot, type AotHost } from '../ecs/aot/installAot';
+import { installNativeAot, nativeAotBindings } from '../ecs/aot/installNativeAot';
+import { createNativeHeap } from '../ecs/bridge/nativeHeap';
import type { AotManifest } from '../ecs/aot/AotSystems';
import type { AotRuntime } from '../ecs/aot/AotRuntime';
import { EventRegistry, eventNamed, type EventDef } from '../ecs/event';
@@ -914,8 +916,14 @@ export class App {
* allocated elsewhere, or trust a module built for other offsets.
*/
async installCompiledSystems(
- wasm: string | BufferSource, manifest: AotManifest,
+ source: string | BufferSource, manifest: AotManifest,
): Promise<number> {
+ // Which road is a fact about the HOST, not about the caller: a host
+ // that loads a library packs the rows itself, and an address there is a
+ // pointer nothing here can hold.
+ const native = this.installNative_(source, manifest);
+ if (native !== null) return native;
+ const wasm = source;
const module = this.module_;
if (!module) {
throw new Error('installCompiledSystems: this App has no engine module, and a compiled '
@@ -948,6 +956,28 @@ export class App {
return this.aot_.systems.size;
}
+ /**
+ * The same, where the host loads a library. Null when this is not such a
+ * host, which is every host but a native one — and then the caller falls
+ * through to the module road above.
+ */
+ private installNative_(module: string | BufferSource, manifest: AotManifest): number | null {
+ if (typeof module !== 'string') return null;
+ const bindings = nativeAotBindings();
+ const heap = createNativeHeap();
+ if (bindings === null || heap === null) return null;
+ this.ensureTime_();
+ this.aot_ = installNativeAot({
+ world: this.world_,
+ runner: this.ensureRunner_(),
+ modulePath: module,
+ manifest,
+ heap,
+ bindings,
+ });
+ return this.aot_?.systems.size ?? 0;
+ }
+
// =========================================================================
// Run
// =========================================================================
diff --git a/sdk/src/runtime/miniGameRuntime.ts b/sdk/src/runtime/miniGameRuntime.ts
index 59e411d0d..bea23b21f 100644
--- a/sdk/src/runtime/miniGameRuntime.ts
+++ b/sdk/src/runtime/miniGameRuntime.ts
@@ -124,7 +124,7 @@ export interface MiniGameRuntimeConfig {
* the export staged them at. A path and never bytes: WXWebAssembly compiles
* a package file and nothing else, which is also why the seam instantiates.
*/
- aot?: { wasm: string; manifest: AotManifest };
+ aot?: { module: string; manifest: AotManifest };
}
export async function initMiniGameRuntime(config: MiniGameRuntimeConfig): Promise<void> {
diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.ts
index f5f1d58f9..ffc381352 100644
--- a/sdk/src/runtime/packagedRuntime.ts
+++ b/sdk/src/runtime/packagedRuntime.ts
@@ -94,7 +94,7 @@ export interface PackagedGameConfig {
* keep in step. Absent unless the project marked something `@compiled`, so a
* runtime reads presence and needs no mode flag.
*/
- aot?: { wasm: string; manifest: AotManifest };
+ aot?: { module: string; manifest: AotManifest };
}
/** The packaged realm's resolved asset index — manifest, catalog, resolution. */
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index e10475013..2f148aa26 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -575,7 +575,7 @@ export interface RuntimeInitConfig {
* before the first scene registers, the only moment where no component
* exists yet to be left behind in the wrong memory.
*/
- aot?: { wasm: string | BufferSource; manifest: AotManifest };
+ aot?: { module: string | BufferSource; manifest: AotManifest };
}
export async function initRuntime(config: RuntimeInitConfig): Promise<void> {
@@ -587,7 +587,7 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {
// and before any exists (its rows must be in the memory the module reads).
// A module that disagrees with this engine or project throws here.
if (config.aot) {
- const installed = await app.installCompiledSystems(config.aot.wasm, config.aot.manifest);
+ const installed = await app.installCompiledSystems(config.aot.module, config.aot.manifest);
log.info('runtime', `AOT: ${installed} compiled system(s) installed`);
}