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.

refactor: one asset model for every packaged realm

esengineaaad5af90289
diff --git a/desktop/electron/addressableManifest.ts b/desktop/electron/addressableManifest.ts
index 5ef643fcf..0a57ecf0c 100644
--- a/desktop/electron/addressableManifest.ts
+++ b/desktop/electron/addressableManifest.ts
@@ -56,6 +56,7 @@ export async function buildAddressableManifest(absOut: string): Promise<string>
const flat = JSON.parse(await readFile(path.join(absOut, 'assets.manifest.json'), 'utf8')) as FlatManifest;
type Entry = {
path: string; address?: string; type: string; size: number; labels: string[]; contentHash?: string;
+ compressedFormats?: string[];
metadata?: { atlasPage?: number; atlasFrame?: { x: number; y: number; width: number; height: number }; atlasPageWidth?: number; atlasPageHeight?: number };
};
type Group = { bundleMode: string; labels: string[]; assets: Record<string, Entry> };
@@ -69,6 +70,10 @@ export async function buildAddressableManifest(absOut: string): Promise<string>
});
const entry: Entry = { path: e.path, type: addrType(e.type), size, labels: [] };
if (e.contentHash) entry.contentHash = e.contentHash;
+ // Which GPU formats the texture was encoded for. The runtime reads this off
+ // the addressable manifest — the flat one it came from is a build-time
+ // intermediate that no longer ships.
+ if (e.compressedFormats?.length) entry.compressedFormats = e.compressedFormats;
// The logical source path rides as the asset's address: path-style refs
// resolve through it. Only meaningful when staging renamed the file.
if (e.sourcePath && e.sourcePath !== e.path) entry.address = e.sourcePath;
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index c0db77b84..7c63b62dd 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -21,7 +21,7 @@
*/
import type { BuildOptions, Plugin } from 'esbuild';
import { loadEsbuild } from './esbuildRuntime';
-import { writeFile, mkdir, cp, readdir } from 'node:fs/promises';
+import { writeFile, mkdir, cp, readdir, rm } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets, loadAssetGroups } from './cookAssets';
@@ -424,6 +424,10 @@ export async function exportGame(opts: {
// work on web + desktop too (not just mini-games). Additive: the eager boot
// still reads the flat manifest; this powers on-demand + hot-update delivery.
await writeFile(path.join(payloadDir, 'asset-manifest.json'), await buildAddressableManifest(payloadDir));
+ // The flat manifest is a build-time intermediate: the addressable one above is
+ // derived from it, and every runtime now reads only that. Dropping it keeps one
+ // asset model in the package — the mini-game export has always done this.
+ await rm(path.join(payloadDir, 'assets.manifest.json'), { force: true });
// Hot-update delivery baked into game.config.json: the active build profile's
// CDN root (an explicit opts.hotUpdate override wins), plus a persistence key so
diff --git a/desktop/src/gameHost.ts b/desktop/src/gameHost.ts
index ac03d5e59..53746b2a4 100644
--- a/desktop/src/gameHost.ts
+++ b/desktop/src/gameHost.ts
@@ -11,12 +11,12 @@
* Builtin scenes run as-is; project custom-script bundles are a follow-up
* (shared with the play realm's import-map work).
*/
-import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, atlasCatalogFields, parseThemeOverrides, Assets } from 'esengine';
-import type { CatalogData, CookedAtlasInfo, ESEngineModule, SceneData, AddressableManifest, PackagedGameConfig } from 'esengine';
-
-interface CookedManifest {
- entries: { uuid: string; path: string; sourcePath?: string; type: string; atlas?: CookedAtlasInfo }[];
-}
+import {
+ createWebApp, setEditorMode, setPlayMode, parseThemeOverrides, Assets,
+ indexPackagedManifest, createPackagedAssetSource, applyAssetRefResolvers, initRuntime,
+ HttpBackend, fetchDecodePixels,
+} from 'esengine';
+import type { ESEngineModule, SceneData, AddressableManifest, PackagedGameConfig } from 'esengine';
async function boot(): Promise<void> {
const canvas = document.getElementById('canvas') as HTMLCanvasElement;
@@ -42,39 +42,14 @@ async function boot(): Promise<void> {
}
const cfg = (await (await fetch('./game.config.json')).json()) as PackagedGameConfig;
- const manifest = (await (await fetch('./assets.manifest.json')).json()) as CookedManifest;
- // Addressable manifest (v2.0): powers Assets.loadGroup + hot-update. Optional —
- // a legacy build without it degrades to eager-only (the flat manifest above).
- const addressable = await fetch('./asset-manifest.json')
- .then((r) => (r.ok ? (r.json() as Promise<AddressableManifest>) : null))
- .catch(() => null);
+ // The addressable manifest is the asset index — the same one the WeChat and
+ // native runtimes read. It resolves every ref spelling to its staged path and
+ // carries the atlas metadata the catalog needs, so there is one asset model
+ // across every packaged realm rather than a flat map here and a manifest there.
+ const index = indexPackagedManifest(
+ (await (await fetch('./asset-manifest.json')).json()) as AddressableManifest,
+ );
const sceneData = (await (await fetch(`./${cfg.entryScene}`)).json()) as SceneData;
- const assetManifest: Record<string, string> = {};
- // Logical → staged resolution for PATH-style refs, twice over: `pathMap` for
- // Assets-level refs (resolved before extension sniffing, so a .png staged as
- // .ktx2 transcodes), `catalog` buildPaths for the loaders' inner text refs
- // (a material's shader). Both derive from the manifest's sourcePath — the
- // asset's logical identity that content-addressed staging preserves.
- const pathMap: Record<string, string> = {};
- const catalog: CatalogData = { version: 1, entries: {} };
- for (const e of manifest.entries) {
- assetManifest[e.uuid.toLowerCase()] = `./${e.path}`;
- const logical = e.sourcePath ?? e.path;
- // Atlas-packed frame: its `path` already points at the PAGE file (URL-level
- // redirect); the catalog additionally carries frame/uv so the scene loader
- // can aim each sprite's uvOffset/uvScale at its rect — keyed by every ref
- // spelling a scene can use, `@uuid:` included.
- const atlasFields = e.atlas ? atlasCatalogFields(e.atlas, `./${e.path}`) : null;
- if (atlasFields) {
- catalog.entries[`@uuid:${e.uuid.toLowerCase()}`] = { type: e.type, buildPath: `./${e.path}`, ...atlasFields };
- }
- pathMap[logical] = `./${e.path}`;
- catalog.entries[logical] = { type: e.type, buildPath: `./${e.path}`, ...(atlasFields ?? {}) };
- // The cook writes project-absolute refs as "/<logical>" when the logical
- // path lacks a passthrough prefix — register that spelling too.
- pathMap[`/${logical}`] = `./${e.path}`;
- catalog.entries[`/${logical}`] = { type: e.type, buildPath: `./${e.path}`, ...(atlasFields ?? {}) };
- }
const wasmBase = new URL('./wasm/', import.meta.url).href; // relative → mount-path agnostic
const { default: createModule } = (await import(/* @vite-ignore */ `${wasmBase}esengine.js`)) as {
@@ -134,26 +109,32 @@ async function boot(): Promise<void> {
// registers lazily by path, so SceneManager.switchTo('name') fetches it on
// first use — the same registration shape the WeChat runtime uses.
const sceneList = cfg.scenes ?? [];
- const entryName = sceneList.find((s) => s.path === cfg.entryScene)?.name;
- await initPlayRealmRuntime({
+ const entryName = sceneList.find((s) => s.path === cfg.entryScene)?.name ?? '__play';
+ // Cross-origin images taint a canvas, so a cooked build decodes through
+ // fetch+blob rather than the platform's Image path.
+ const source = createPackagedAssetSource(index, {
+ backend: new HttpBackend({ baseUrl: '' }),
+ decodePixels: (path) => fetchDecodePixels(path),
+ });
+ applyAssetRefResolvers(app, index.resolvePath);
+ await initRuntime({
app,
module,
- canvas,
- sceneData,
- entrySceneName: entryName,
- extraScenes: sceneList
- .filter((s) => s.path !== cfg.entryScene)
- .map((s) => ({ name: s.name, path: `./${s.path}` })),
- assetManifest,
- assetPathMap: pathMap,
- catalogData: catalog,
- manifest: addressable,
+ source,
+ manifest: index.manifest,
+ catalog: index.catalog,
remoteRoot: cfg.hotUpdate?.remoteRoot,
persistUpdateKey: cfg.hotUpdate?.persistUpdateKey,
- wasmBaseUrl: wasmBase.replace(/\/$/, ''),
+ scenes: [
+ { name: entryName, data: sceneData },
+ ...sceneList.filter((s) => s.path !== cfg.entryScene).map((s) => ({ name: s.name, path: s.path })),
+ ],
+ firstScene: entryName,
+ aspectRatio: canvas.width / canvas.height,
uiTheme: cfg.uiTheme,
uiThemeOverrides: parseThemeOverrides(cfg.uiThemeColors),
});
+ app.run();
}
boot().catch((err) => {
diff --git a/desktop/tests/export-desktop.test.ts b/desktop/tests/export-desktop.test.ts
index 4f2d2a4cf..36febe2b5 100644
--- a/desktop/tests/export-desktop.test.ts
+++ b/desktop/tests/export-desktop.test.ts
@@ -66,14 +66,17 @@ describe('exportGame (desktop)', () => {
// Web payload nested under app/.
const app = path.join(out, 'app');
- for (const f of ['index.html', 'game.js', 'scripts.mjs', 'game.config.json', 'assets.manifest.json']) {
+ for (const f of ['index.html', 'game.js', 'scripts.mjs', 'game.config.json', 'asset-manifest.json']) {
expect(existsSync(path.join(app, f))).toBe(true);
}
expect(existsSync(path.join(app, 'wasm', 'esengine.js'))).toBe(true);
expect(existsSync(path.join(app, 'sdk', 'index.js'))).toBe(true);
// Content-addressed by default: the texture ships as assets/<hash>.png.
- const m = JSON.parse(readFileSync(path.join(app, 'assets.manifest.json'), 'utf8'));
- const tex = m.entries.find((e: { type: string }) => e.type === 'texture');
+ const m = JSON.parse(readFileSync(path.join(app, 'asset-manifest.json'), 'utf8')) as
+ { groups: Record<string, { assets: Record<string, { type: string; path: string }> }> };
+ const tex = Object.values(m.groups)
+ .flatMap((g) => Object.values(g.assets))
+ .find((a) => a.type === 'texture')!;
expect(tex.path).toMatch(/^assets\/[0-9a-f]{16}\.png$/);
expect(existsSync(path.join(app, tex.path))).toBe(true);
diff --git a/desktop/tests/export-game.test.ts b/desktop/tests/export-game.test.ts
index 7d88de5d1..368d2330d 100644
--- a/desktop/tests/export-game.test.ts
+++ b/desktop/tests/export-game.test.ts
@@ -53,6 +53,13 @@ beforeAll(async () => {
afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+/** Every asset in an addressable manifest, paired with its uuid key. */
+function manifestAssets(manifest: unknown): Array<[string, { type: string; path: string; address?: string; compressedFormats?: string[] }]> {
+ const groups = (manifest as { groups: Record<string, { assets: Record<string, never> }> }).groups;
+ return Object.values(groups).flatMap((g) => Object.entries(g.assets)) as never;
+}
+
describe('exportGame', () => {
it('produces an import-map web build (cook + host + sdk + scripts + wasm + html)', async () => {
const res = await exportGame({
@@ -77,11 +84,13 @@ describe('exportGame', () => {
expect(has('scripts.mjs')).toBe(true);
expect(has('sdk/index.js')).toBe(true);
expect(has('game.config.json')).toBe(true);
- expect(has('assets.manifest.json')).toBe(true);
+ // The flat manifest is a build-time intermediate — only the addressable one ships.
+ expect(has('assets.manifest.json')).toBe(false);
+ expect(has('asset-manifest.json')).toBe(true);
expect(has('scenes/main.esscene')).toBe(true);
// Content-addressing is on by default now: the texture ships as assets/<hash>.png.
- const m = JSON.parse(readFileSync(path.join(out, 'assets.manifest.json'), 'utf8'));
- const tex = m.entries.find((e: { type: string }) => e.type === 'texture');
+ const m = JSON.parse(readFileSync(path.join(out, 'asset-manifest.json'), 'utf8'));
+ const tex = manifestAssets(m).find(([, a]) => a.type === 'texture')![1];
expect(tex.path).toMatch(/^assets\/[0-9a-f]{16}\.png$/);
expect(has(tex.path)).toBe(true);
expect(has('wasm/esengine.js')).toBe(true);
@@ -142,8 +151,8 @@ describe('exportGame', () => {
expect(res.ok).toBe(true);
expect(res.errors).toEqual([]);
- const manifest = JSON.parse(readFileSync(path.join(out2, 'assets.manifest.json'), 'utf8'));
- const tex = manifest.entries.find((e: { uuid: string }) => e.uuid === TEX);
+ const manifest = JSON.parse(readFileSync(path.join(out2, 'asset-manifest.json'), 'utf8'));
+ const tex = manifestAssets(manifest).find(([uuid]) => uuid.toLowerCase() === TEX)![1];
// The PNG was encoded to KTX2 and named by content hash; refs stay uuid-based.
expect(tex.path).toMatch(/^assets\/[0-9a-f]{16}\.ktx2$/);
expect(tex.compressedFormats).toEqual(['astc-4x4', 'etc2-rgba8', 's3tc-dxt5']);
diff --git a/desktop/tests/export-native.test.ts b/desktop/tests/export-native.test.ts
index ac6d17cb1..b2f770059 100644
--- a/desktop/tests/export-native.test.ts
+++ b/desktop/tests/export-native.test.ts
@@ -59,8 +59,10 @@ describe('exportGame (native)', () => {
// What the native runtime reads off the device.
expect(existsSync(path.join(out, 'game.config.json'))).toBe(true);
- expect(existsSync(path.join(out, 'assets.manifest.json'))).toBe(true);
expect(existsSync(path.join(out, 'asset-manifest.json'))).toBe(true);
+ // The flat manifest is a build-time intermediate — the addressable one is the
+ // runtime contract, and it is the only one that ships.
+ expect(existsSync(path.join(out, 'assets.manifest.json'))).toBe(false);
expect(JSON.parse(readFileSync(path.join(out, 'game.config.json'), 'utf8')).entryScene)
.toBe('scenes/main.esscene');
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 44b7f7de3..4e7243430 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1329 stable · 17 beta · 0 deprecated
+Symbols: 1334 stable · 17 beta · 0 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -848,6 +848,14 @@ readonly ["Button", "Toggle", "Slider", "Dialog", "TextInput", "Progress", "Drop
readonly BundleMode[]
```
+## Backend — interface
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: ((url: string) => void) | undefined
+```
+
## BehaviorContext — interface
```
commands: CommandsInstance
@@ -3024,6 +3032,16 @@ sideModules: SideModuleHost | undefined
| { type: 'polygon'; points: number[] }
```
+## HttpBackend — class
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: (url: string) => void
+static new (options: HttpBackendOptions): HttpBackend
+static prototype: HttpBackend
+```
+
## INTERACTION_CONTROLLER — const
```
"$interaction"
@@ -4098,6 +4116,12 @@ model: ManifestModel
resolvePath: (ref: string) => string
```
+## PackagedAssetSourceOptions — interface
+```
+backend: Backend | undefined
+decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height: number; pixels: Uint8Array; }>) | undefined
+```
+
## PackagedGameConfig — interface
```
colorSpace: "gamma" | "linear" | undefined
@@ -8005,6 +8029,11 @@ AnimationPlugin
(def: AnimatorControllerDef): AnimatorEdge[]
```
+## applyAssetRefResolvers — function
+```
+(app: App, resolveRef: (ref: string) => string): void
+```
+
## applyAudioProjectConfig — function
```
(audio: AudioAPI, config: AudioProjectConfig | undefined): void
@@ -8377,7 +8406,7 @@ Plugin
## createPackagedAssetSource — function
```
-(index: PackagedAssetIndex): RuntimeAssetSource
+(index: PackagedAssetIndex, options?: PackagedAssetSourceOptions): RuntimeAssetSource
```
## createProgress — function
@@ -8620,6 +8649,11 @@ DragPlugin
(z: number, w: number): number
```
+## fetchDecodePixels — function
+```
+(url: string): Promise<DecodedPixels>
+```
+
## findControllerOwner — function
```
(world: World, entity: Entity, name: string): Entity | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index e1b128d11..5b5b5b544 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1343 stable · 22 beta · 0 deprecated
+Symbols: 1348 stable · 22 beta · 0 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -848,6 +848,14 @@ readonly ["Button", "Toggle", "Slider", "Dialog", "TextInput", "Progress", "Drop
readonly BundleMode[]
```
+## Backend — interface
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: ((url: string) => void) | undefined
+```
+
## BehaviorContext — interface
```
commands: CommandsInstance
@@ -3032,6 +3040,16 @@ sideModules: SideModuleHost | undefined
| { type: 'polygon'; points: number[] }
```
+## HttpBackend — class
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: (url: string) => void
+static new (options: HttpBackendOptions): HttpBackend
+static prototype: HttpBackend
+```
+
## INTERACTION_CONTROLLER — const
```
"$interaction"
@@ -4217,6 +4235,12 @@ model: ManifestModel
resolvePath: (ref: string) => string
```
+## PackagedAssetSourceOptions — interface
+```
+backend: Backend | undefined
+decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height: number; pixels: Uint8Array; }>) | undefined
+```
+
## PackagedGameConfig — interface
```
colorSpace: "gamma" | "linear" | undefined
@@ -8124,6 +8148,11 @@ AnimationPlugin
(def: AnimatorControllerDef): AnimatorEdge[]
```
+## applyAssetRefResolvers — function
+```
+(app: App, resolveRef: (ref: string) => string): void
+```
+
## applyAudioProjectConfig — function
```
(audio: AudioAPI, config: AudioProjectConfig | undefined): void
@@ -8526,7 +8555,7 @@ Plugin
## createPackagedAssetSource — function
```
-(index: PackagedAssetIndex): RuntimeAssetSource
+(index: PackagedAssetIndex, options?: PackagedAssetSourceOptions): RuntimeAssetSource
```
## createProgress — function
@@ -8769,6 +8798,11 @@ DragPlugin
(z: number, w: number): number
```
+## fetchDecodePixels — function
+```
+(url: string): Promise<DecodedPixels>
+```
+
## findControllerOwner — function
```
(world: World, entity: Entity, name: string): Entity | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 94b20e615..fc8223aee 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1328 stable · 19 beta · 0 deprecated
+Symbols: 1333 stable · 19 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -843,6 +843,14 @@ readonly ["Button", "Toggle", "Slider", "Dialog", "TextInput", "Progress", "Drop
readonly BundleMode[]
```
+## Backend — interface
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: ((url: string) => void) | undefined
+```
+
## BehaviorContext — interface
```
commands: CommandsInstance
@@ -3019,6 +3027,16 @@ sideModules: SideModuleHost | undefined
| { type: 'polygon'; points: number[] }
```
+## HttpBackend — class
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: (url: string) => void
+static new (options: HttpBackendOptions): HttpBackend
+static prototype: HttpBackend
+```
+
## INTERACTION_CONTROLLER — const
```
"$interaction"
@@ -4093,6 +4111,12 @@ model: ManifestModel
resolvePath: (ref: string) => string
```
+## PackagedAssetSourceOptions — interface
+```
+backend: Backend | undefined
+decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height: number; pixels: Uint8Array; }>) | undefined
+```
+
## PackagedGameConfig — interface
```
colorSpace: "gamma" | "linear" | undefined
@@ -8000,6 +8024,11 @@ AnimationPlugin
(def: AnimatorControllerDef): AnimatorEdge[]
```
+## applyAssetRefResolvers — function
+```
+(app: App, resolveRef: (ref: string) => string): void
+```
+
## applyAudioProjectConfig — function
```
(audio: AudioAPI, config: AudioProjectConfig | undefined): void
@@ -8372,7 +8401,7 @@ Plugin
## createPackagedAssetSource — function
```
-(index: PackagedAssetIndex): RuntimeAssetSource
+(index: PackagedAssetIndex, options?: PackagedAssetSourceOptions): RuntimeAssetSource
```
## createProgress — function
@@ -8615,6 +8644,11 @@ DragPlugin
(z: number, w: number): number
```
+## fetchDecodePixels — function
+```
+(url: string): Promise<DecodedPixels>
+```
+
## findControllerOwner — function
```
(world: World, entity: Entity, name: string): Entity | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 5210c106b..d06f283bc 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1339 stable · 17 beta · 0 deprecated
+Symbols: 1344 stable · 17 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -843,6 +843,14 @@ readonly ["Button", "Toggle", "Slider", "Dialog", "TextInput", "Progress", "Drop
readonly BundleMode[]
```
+## Backend — interface
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: ((url: string) => void) | undefined
+```
+
## BehaviorContext — interface
```
commands: CommandsInstance
@@ -3019,6 +3027,16 @@ sideModules: SideModuleHost | undefined
| { type: 'polygon'; points: number[] }
```
+## HttpBackend — class
+```
+fetchBinary: (path: string) => Promise<ArrayBuffer>
+fetchText: (path: string) => Promise<string>
+resolveUrl: (path: string) => string
+setBaseUrl: (url: string) => void
+static new (options: HttpBackendOptions): HttpBackend
+static prototype: HttpBackend
+```
+
## INTERACTION_CONTROLLER — const
```
"$interaction"
@@ -4100,6 +4118,12 @@ model: ManifestModel
resolvePath: (ref: string) => string
```
+## PackagedAssetSourceOptions — interface
+```
+backend: Backend | undefined
+decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height: number; pixels: Uint8Array; }>) | undefined
+```
+
## PackagedGameConfig — interface
```
colorSpace: "gamma" | "linear" | undefined
@@ -8024,6 +8048,11 @@ AnimationPlugin
(def: AnimatorControllerDef): AnimatorEdge[]
```
+## applyAssetRefResolvers — function
+```
+(app: App, resolveRef: (ref: string) => string): void
+```
+
## applyAudioProjectConfig — function
```
(audio: AudioAPI, config: AudioProjectConfig | undefined): void
@@ -8396,7 +8425,7 @@ Plugin
## createPackagedAssetSource — function
```
-(index: PackagedAssetIndex): RuntimeAssetSource
+(index: PackagedAssetIndex, options?: PackagedAssetSourceOptions): RuntimeAssetSource
```
## createProgress — function
@@ -8639,6 +8668,11 @@ DragPlugin
(z: number, w: number): number
```
+## fetchDecodePixels — function
+```
+(url: string): Promise<DecodedPixels>
+```
+
## findControllerOwner — function
```
(world: World, entity: Entity, name: string): Entity | null
diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.ts
index 626db8b2c..c44c6a6ee 100644
--- a/sdk/src/asset/index.ts
+++ b/sdk/src/asset/index.ts
@@ -29,7 +29,7 @@ export {
export { xxh64, contentHashHex, contentHashOf } from './contentHash';
export { AsyncCache } from './AsyncCache';
export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';
-export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels } from './imageDecode';
+export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels, fetchDecodePixels } from './imageDecode';
export { AssetRefCounter, type AssetRefInfo } from './AssetRefCounter';
export { Assets as AssetsImpl, type AssetsOptions, type AssetBundle, type SceneAssetResult, type MissingAsset, type CheckForUpdateOptions, type ApplyUpdateResult, type AssetDownloadFailure, type InvalidateListener } from './Assets';
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 8720cc082..04945fce2 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -56,6 +56,9 @@ export {
type CatalogEntry,
decodeImageBitmap,
decodeImagePixels,
+ fetchDecodePixels,
+ HttpBackend,
+ type Backend,
imageBitmapOptions,
type DecodedPixels,
type AddressableManifest,
@@ -241,7 +244,9 @@ export {
indexPackagedManifest,
catalogFromManifest,
createPackagedAssetSource,
+ applyAssetRefResolvers,
type PackagedAssetIndex,
+ type PackagedAssetSourceOptions,
type PackagedGameConfig,
} from './packagedRuntime';
diff --git a/sdk/src/nativeGameRuntime.ts b/sdk/src/nativeGameRuntime.ts
index e5277359b..c27151e54 100644
--- a/sdk/src/nativeGameRuntime.ts
+++ b/sdk/src/nativeGameRuntime.ts
@@ -20,7 +20,7 @@ import { initRuntime } from './runtimeLoader';
import { createNativeApp } from './ecs/nativeRuntime';
import type { NativeBridge } from './platform/native';
import { platformReadTextFile } from './platform';
-import { loadPackagedAssetIndex, createPackagedAssetSource, type PackagedGameConfig } from './packagedRuntime';
+import { loadPackagedAssetIndex, createPackagedAssetSource, applyAssetRefResolvers, type PackagedGameConfig } from './packagedRuntime';
import type { SceneData } from './scene';
import type { ThemeOverrides } from './ui';
import { parseThemeOverrides } from './ui';
@@ -57,6 +57,7 @@ export async function initNativeGame(options: NativeGameOptions): Promise<Native
const index = await loadPackagedAssetIndex();
const source = createPackagedAssetSource(index);
+ applyAssetRefResolvers(app, index.resolvePath);
const scenes = config.scenes ?? [{ name: 'main', path: config.entryScene }];
const entry = scenes.find((s) => s.path === config.entryScene) ?? scenes[0];
diff --git a/sdk/src/packagedRuntime.ts b/sdk/src/packagedRuntime.ts
index ae29fda3c..061fbe7c6 100644
--- a/sdk/src/packagedRuntime.ts
+++ b/sdk/src/packagedRuntime.ts
@@ -13,10 +13,14 @@
*/
import { toBuildPath } from './assetTypes';
+import { extractUuid } from './asset/AssetRegistry';
import { platformReadTextFile, platformLoadImagePixels } from './platform';
import { ManifestModel, type AddressableManifest } from './asset/AddressableManifest';
import { Catalog, atlasCatalogFields, type CatalogEntry } from './asset/Catalog';
-import { FileSystemBackend } from './asset/Backend';
+import { FileSystemBackend, type Backend } from './asset/Backend';
+import { Audio } from './audio/Audio';
+import { VideoPlayer } from './video/VideoAPI';
+import type { App } from './app';
import type { RuntimeAssetSource } from './runtimeAssets';
/**
@@ -101,7 +105,10 @@ export function indexPackagedManifest(manifest: AddressableManifest): PackagedAs
manifest,
model,
catalog: catalogFromManifest(manifest),
- resolvePath: (ref) => model.resolvePath(ref, toBuildPath),
+ // A scene spells asset refs `@uuid:<v4>`, while the manifest indexes bare
+ // uuids — strip the prefix before looking up, or every `@uuid:` ref falls
+ // through as a literal path and 404s.
+ resolvePath: (ref) => model.resolvePath(extractUuid(ref) ?? ref, toBuildPath),
// The logical address where there is one (content-addressed packs rename
// the staged file), else the staged path — either keeps the extension
// .eslocale discovery filters on.
@@ -109,16 +116,41 @@ export function indexPackagedManifest(manifest: AddressableManifest): PackagedAs
};
}
+/** Transport overrides for realms that do not read bytes off a device. */
+export interface PackagedAssetSourceOptions {
+ /** Where bytes come from; the platform's packaged-file reader by default. */
+ backend?: Backend;
+ /** Image → RGBA; the platform's decode by default. A cooked web build passes
+ * a fetch+blob decoder instead: drawing a cross-origin image into a canvas
+ * taints it, and getImageData then throws. */
+ decodePixels?: RuntimeAssetSource['decodePixels'];
+}
+
/**
- * The asset source a packaged realm runs on: files off the device, the platform's
- * image decode, and manifest-driven ref resolution. Identical for every packaged
- * realm — the platform layer is what differs, and it is already abstracted.
+ * The asset source a packaged realm runs on: manifest-driven ref resolution over
+ * whatever transport the realm has. One construction for every realm that ships
+ * cooked content — a mini-game, a native app, a cooked web build — so a fix to
+ * how refs or asset listings resolve reaches all three.
*/
-export function createPackagedAssetSource(index: PackagedAssetIndex): RuntimeAssetSource {
+export function createPackagedAssetSource(
+ index: PackagedAssetIndex,
+ options: PackagedAssetSourceOptions = {},
+): RuntimeAssetSource {
return {
- backend: new FileSystemBackend(),
- decodePixels: (path) => platformLoadImagePixels(path),
+ backend: options.backend ?? new FileSystemBackend(),
+ decodePixels: options.decodePixels ?? ((path) => platformLoadImagePixels(path)),
resolveRef: index.resolvePath,
listAssetPaths: index.assetPaths,
};
}
+
+/**
+ * Route audio and video refs through the same resolver as every other asset.
+ * `playSFX` / a video source take plain paths rather than `@uuid:` refs, so
+ * without this they would miss the logical→staged mapping a cooked build needs —
+ * one resolution channel, not a parallel base-URL scheme per media type.
+ */
+export function applyAssetRefResolvers(app: App, resolveRef: (ref: string) => string): void {
+ if (app.hasResource(Audio)) app.getResource(Audio).setRefResolver(resolveRef);
+ if (app.hasResource(VideoPlayer)) app.getResource(VideoPlayer).setRefResolver(resolveRef);
+}
diff --git a/sdk/src/playRealmRuntime.ts b/sdk/src/playRealmRuntime.ts
index 3303ef91d..b2adc9e54 100644
--- a/sdk/src/playRealmRuntime.ts
+++ b/sdk/src/playRealmRuntime.ts
@@ -29,6 +29,7 @@ import type { SceneData } from './scene';
import type { PhysicsPluginConfig } from './physics/PhysicsPlugin';
import type { AudioProjectConfig } from './audio/AudioProjectConfig';
import { fetchDecodePixels } from './asset/imageDecode';
+import { applyAssetRefResolvers } from './packagedRuntime';
import { extractUuid, UUID_REF_PREFIX } from './asset/AssetRegistry';
export interface PlayRealmRuntimeConfig {
@@ -162,21 +163,7 @@ function createPlayRealmSource(
export async function initPlayRealmRuntime(config: PlayRealmRuntimeConfig): Promise<void> {
const { app, module, canvas, sceneData, assetManifest, assetBaseUrl } = config;
const source = createPlayRealmSource(assetManifest, assetBaseUrl, config.assetPathMap);
- // Audio fetches its own buffers (playSFX/playBGM take plain paths, not uuid
- // refs) — route them through the SAME resolver as every other asset: the
- // editor realm prefixes the project root, cooked builds hit their
- // logical→staged map. One resolution channel, no parallel baseUrl logic.
- if (app.hasResource(Audio)) {
- app.getResource(Audio).setRefResolver(
- (ref) => resolvePlayAssetRef(ref, assetManifest, assetBaseUrl, config.assetPathMap),
- );
- }
- // Video source refs resolve through the same channel (see the Audio note above).
- if (app.hasResource(VideoPlayer)) {
- app.getResource(VideoPlayer).setRefResolver(
- (ref) => resolvePlayAssetRef(ref, assetManifest, assetBaseUrl, config.assetPathMap),
- );
- }
+ applyAssetRefResolvers(app, (ref) => resolvePlayAssetRef(ref, assetManifest, assetBaseUrl, config.assetPathMap));
const entryName = config.entrySceneName ?? '__play';
await initRuntime({
app,
diff --git a/sdk/src/wechatRuntime.ts b/sdk/src/wechatRuntime.ts
index a6184a483..b488eacda 100644
--- a/sdk/src/wechatRuntime.ts
+++ b/sdk/src/wechatRuntime.ts
@@ -16,7 +16,7 @@ import type { RuntimeAssetSource } from './runtimeAssets';
import { FileSystemBackend } from './asset/Backend';
import { applyBuildRuntimeConfig, type RuntimeBuildConfig } from './defaults';
import { platformReadTextFile, platformInstantiateWasm, platformLoadImagePixels } from './platform';
-import { loadPackagedAssetIndex, createPackagedAssetSource } from './packagedRuntime';
+import { loadPackagedAssetIndex, createPackagedAssetSource, applyAssetRefResolvers } from './packagedRuntime';
import { createWeChatSideModuleHost, type WeChatSideModuleFactories } from './sideModules';
import type { Vec2 } from './types';
import type { SceneData } from './scene';
@@ -137,6 +137,7 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<vo
// Canonical asset source: WeChat filesystem backend, wx image decode, manifest
// ref resolution (bare-uuid → build path).
const source = createPackagedAssetSource(index);
+ applyAssetRefResolvers(app, index.resolvePath);
// The first scene loads eagerly (the game boots into it); every other
// registers lazily by path — SceneManager fetches scenes/<name>.json