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
refactor: one asset model for every packaged realm
esengineaaad5af90289
diff --git a/desktop/electron/addressableManifest.ts b/desktop/electron/addressableManifest.tsindex 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.tsindex 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 sodiff --git a/desktop/src/gameHost.ts b/desktop/src/gameHost.tsindex 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 agnosticconst { 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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", "Dropreadonly 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: ManifestModelresolvePath: (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 | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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", "Dropreadonly 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: ManifestModelresolvePath: (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 | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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", "Dropreadonly 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: ManifestModelresolvePath: (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 | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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", "Dropreadonly 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: ManifestModelresolvePath: (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 | nulldiff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.tsindex 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.tsindex 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.tsindex 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<Nativeconst 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.tsindex 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): PackagedAsmanifest,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.tsindex 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.tsindex 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