A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(assets): one runtime Assets per App — caches, refcounts and manifest survive scene switches
yhhc531c71dbd39
diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.tsindex 1574f6f32..357ad3aa3 100644--- a/sdk/src/runtimeLoader.ts+++ b/sdk/src/runtimeLoader.ts@@ -29,6 +29,7 @@ import { log } from './logger';import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';import { loadSpineAssets, applySpineEntities } from './spine/loadSpineScene';import { transcoderFromModule, type BasisWasmModule } from './asset/basisTranscoder';+import type { AddressableManifest, ManifestModel } from './asset/AddressableManifest';// =============================================================================// Public Interface@@ -39,24 +40,43 @@ import { transcoderFromModule, type BasisWasmModule } from './asset/basisTranscoexport type { RuntimeAssetSource } from './runtimeAssets';// =============================================================================-// Scene-local Assets channel+// Per-App runtime Assets channel// =============================================================================+// Marks Assets instances built here and holds their merged per-scene texture+// import settings, so later scene loads extend the map instead of replacing+// the instance (and so `ensureRuntimeAssets` can tell its own instance apart+// from the default AssetPlugin one it must replace).+const runtimeImportSettings = new WeakMap<AssetsClass, Record<string, TextureImportSettings>>();+/**- * Build a scene-local `Assets` that loads this realm's scene through the single- * canonical asset channel, driven by the realm's `RuntimeAssetSource`:+ * The per-App runtime `Assets`, loading through the single canonical asset+ * channel driven by the realm's `RuntimeAssetSource`:* - fetch (text/binary, incl. KTX2 containers) → `source.backend`* - texture pixels → `source.decodePixels` (handles `estella://` / WeChat* package files / inlined data-URLs that a URL `<img>` can't)* - KTX2 transcode → the same self-gating Basis side-module the editor wires* `source.resolveRef` is the single ref resolver, so refs resolve to their real- * (extension-bearing) build paths before KTX2 detection and fetch. No ref- * counter / catalog is attached (parity with the old runtime loader, which- * tracked neither and applied no atlas-frame indirection).+ * (extension-bearing) build paths before KTX2 detection and fetch.+ *+ * Created ONCE per App and installed as the app resource, replacing the default+ * AssetPlugin instance (whose HttpBackend/URL `<img>` decode can't read this+ * realm's sources). Every later scene load reuses it, so caches, refcounts and+ * the addressable manifest survive scene switches — `Assets.loadGroup` keeps+ * working after the first scene, and re-entering a scene revives resident+ * textures instead of re-decoding. The first scene load's `source` wins; one+ * App is expected to keep one asset source for its lifetime. No ref counter /+ * catalog is attached (parity with the old runtime loader, which tracked+ * neither and applied no atlas-frame indirection).*/-function createSceneAssets(- app: App, module: ESEngineModule, source: RuntimeAssetSource, sceneData: SceneData,+function ensureRuntimeAssets(+ app: App, module: ESEngineModule, source: RuntimeAssetSource,): AssetsClass {+ if (app.hasResource(AssetsResource)) {+ const existing = app.getResource(AssetsResource);+ if (runtimeImportSettings.has(existing)) return existing;+ }+initBuiltinAssetFields();const assets = AssetsClass.create({backend: source.backend,@@ -77,25 +97,35 @@ function createSceneAssets(return mod ? transcoderFromModule(mod as unknown as BasisWasmModule) : null;});- // Per-texture import settings (filter/wrap) keyed by the scene's stored ref:- // normalize keys through resolveRef so they match the resolved path the- // TextureLoader sees, and map the stored {filterMode,wrapMode} shape to the- // loader's {filter,wrap}.- const resolveRef = source.resolveRef ?? ((r: string) => r);+ const settings: Record<string, TextureImportSettings> = {};+ assets.setTextureImportSettingsResolver((ref) => settings[ref]);+ runtimeImportSettings.set(assets, settings);++ app.insertResource(AssetsResource, assets);+ return assets;+}++/**+ * Merge a scene's stored per-texture import settings (filter/wrap) into the+ * runtime Assets' resolver map. Keys normalize through resolveRef so they match+ * the resolved path the TextureLoader sees; the stored {filterMode,wrapMode}+ * shape maps to the loader's {filter,wrap}. Merging (not replacing) keeps+ * settings from previously loaded scenes live — the same texture carries the+ * same .meta-derived settings in every scene, so last-wins is safe.+ */+function mergeSceneTextureImportSettings(+ assets: AssetsClass, sceneData: SceneData, resolveRef: (ref: string) => string,+): void {+ const settings = runtimeImportSettings.get(assets);const rawSettings = (sceneData as { textureImporterSettings?: Record<string, TextureParams> }).textureImporterSettings;- if (rawSettings) {- const resolved: Record<string, TextureImportSettings> = {};- for (const [ref, s] of Object.entries(rawSettings)) {- resolved[resolveRef(ref)] = {- filter: s.filterMode as TextureImportSettings['filter'],- wrap: s.wrapMode as TextureImportSettings['wrap'],- };- }- assets.setTextureImportSettingsResolver((ref) => resolved[ref]);+ if (!settings || !rawSettings) return;+ for (const [ref, s] of Object.entries(rawSettings)) {+ settings[resolveRef(ref)] = {+ filter: s.filterMode as TextureImportSettings['filter'],+ wrap: s.wrapMode as TextureImportSettings['wrap'],+ };}-- return assets;}/** Apply 9-slice borders to loaded textures. `textureHandles` is keyed by the@@ -176,14 +206,12 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis// Eager scene assets (textures / fonts / materials / anim-clips / tilemaps /// audio) load through the single canonical Assets channel — one per-type// loader implementation, shared with the editor — driven by this realm's- // provider. Spine stays a two-phase load+apply below (skipSpine).- const sceneAssets = createSceneAssets(app, module, source, sceneData);- // Expose the realm's Assets (with its manifest ref-resolver) as the app resource- // so plugins that resolve `@uuid:` refs at runtime — the tilemap plugin looks up- // its `Tilemap.source` / `.estileset` refs each frame — find the SAME resolver the- // preload keyed the caches with. Without this the shipping runtime app has no- // Assets resource, so those refs resolve to nothing and tilemaps never render.- app.insertResource(AssetsResource, sceneAssets);+ // source. The instance is per-App (installed as the app resource, so plugins+ // that resolve `@uuid:` refs at runtime — e.g. the tilemap plugin — find the+ // SAME resolver the preload keyed the caches with) and persists across scene+ // loads. Spine stays a two-phase load+apply below (skipSpine).+ const sceneAssets = ensureRuntimeAssets(app, module, source);+ mergeSceneTextureImportSettings(sceneAssets, sceneData, source.resolveRef ?? ((r) => r));const assetResult = await sceneAssets.preloadSceneAssets(sceneData, undefined, { skipSpine: true });sceneAssets.resolveSceneAssetPaths(sceneData, assetResult);applyTextureMetadata(sceneData, assetResult.textureHandles, source.resolveRef ?? ((ref) => ref));@@ -261,6 +289,13 @@ export interface RuntimeInitConfig {app: App;module: ESEngineModule;source: RuntimeAssetSource;+ /**+ * Addressable manifest for the app's Assets, enabling `Assets.loadGroup`+ * (on-demand groups / subpackages) from game code. Set here — on the+ * per-App runtime instance — rather than on whatever Assets resource+ * existed before initRuntime, which the runtime instance replaces.+ */+ manifest?: AddressableManifest | ManifestModel | null;scenes: Array<{ name: string; data: SceneData }>;firstScene: string;spineModule?: SpineWasmModule | null;@@ -279,6 +314,11 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {flushPendingSystems(app);+ // Install the per-App runtime Assets up front (scene loads reuse it) and+ // hand it the manifest so on-demand loadGroup works from the first frame.+ const assets = ensureRuntimeAssets(app, config.module, config.source);+ if (config.manifest) assets.setManifest(config.manifest);+const sceneOpts: Omit<LoadRuntimeSceneOptions, 'sceneData' | 'sceneName'> = {app: config.app,module: config.module,diff --git a/sdk/src/wechatRuntime.ts b/sdk/src/wechatRuntime.tsindex 8b71a2fbe..dc8dbbc37 100644--- a/sdk/src/wechatRuntime.ts+++ b/sdk/src/wechatRuntime.ts@@ -16,7 +16,6 @@ import { applyBuildRuntimeConfig, type RuntimeBuildConfig } from './defaults';import { platformReadTextFile, platformInstantiateWasm, platformLoadImagePixels } from './platform';import { toBuildPath } from './assetTypes';import { ManifestModel, type AddressableManifest } from './asset/AddressableManifest';-import { Assets } from './asset/AssetPlugin';import { createWeChatSideModuleHost, type WeChatSideModuleFactories } from './sideModules';import type { Vec2 } from './types';import type { SceneData } from './scene';@@ -116,12 +115,6 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<voapplyBuildRuntimeConfig(app, config.runtimeConfig);}- // Hand the manifest to the App's Assets so game code can `Assets.loadGroup(name)`- // on demand — a lazy (subpackage) group triggers wx.loadSubpackage first, the- // eager 'main' group loads directly. Eager scene assets still load through the- // runtime loader below; this enables the on-demand subpackage path.- if (app.hasResource(Assets)) app.getResource(Assets).setManifest(manifest);-// Canonical asset source: WeChat filesystem backend, wx image decode, manifest// ref resolution (bare-uuid → build path).const source: RuntimeAssetSource = {@@ -136,10 +129,17 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<voscenes.push({ name, data: JSON.parse(sceneText) });}+ // The manifest rides into initRuntime, which sets it on the per-App runtime+ // Assets — so game code can `Assets.loadGroup(name)` on demand (a lazy+ // subpackage group triggers wx.loadSubpackage first, an eager 'main' group+ // loads directly), and it survives scene switches. Setting it on the+ // pre-initRuntime Assets resource was a bug: the runtime instance replaced+ // that resource, so loadGroup lost the manifest after the first scene load.await initRuntime({app,module,source,+ manifest: manifestModel,scenes,firstScene: config.firstScene,physicsConfig: config.physicsConfig,diff --git a/sdk/tests/runtime-assets-persistence.test.ts b/sdk/tests/runtime-assets-persistence.test.tsnew file mode 100644index 000000000..11b5db521--- /dev/null+++ b/sdk/tests/runtime-assets-persistence.test.ts@@ -0,0 +1,109 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Per-App runtime Assets: loadRuntimeScene must create the runtime+ * Assets ONCE and reuse it across scene loads — replacing the default+ * AssetPlugin resource, keeping the addressable manifest (loadGroup)+ * and accumulating per-scene texture import settings. The old+ * instance-per-scene behavior silently dropped the manifest and all+ * caches/refcounts on every scene switch.+ */+import { describe, it, expect } from 'vitest';+import { loadRuntimeScene } from '../src/runtimeLoader';+import { Assets as AssetsResource } from '../src/asset/AssetPlugin';+import { Assets as AssetsClass } from '../src/asset/Assets';+import { ManifestModel } from '../src/asset/AddressableManifest';+import { World } from '../src/world';+import type { App } from '../src/app';+import type { Backend } from '../src/asset/Backend';+import type { ESEngineModule } from '../src/wasm';+import type { SceneData } from '../src/scene';++const fakeModule = { _malloc: () => 0, _free: () => {} } as unknown as ESEngineModule;++const fakeBackend: Backend = {+ resolveUrl: (p: string) => p,+ fetchText: async () => '',+ fetchBinary: async () => new ArrayBuffer(0),+} as unknown as Backend;++function makeFakeApp(): App {+ const resources = new Map<unknown, unknown>();+ return {+ world: new World(),+ hasResource: (r: unknown) => resources.has(r),+ getResource: (r: unknown) => resources.get(r),+ insertResource: (r: unknown, v: unknown) => { resources.set(r, v); },+ getPlugin: () => null,+ sideModules: undefined,+ } as unknown as App;+}++function makeScene(+ name: string,+ textureImporterSettings?: Record<string, { filterMode: string; wrapMode: string }>,+): SceneData {+ const scene: SceneData = { version: '1.0', name, entities: [] };+ if (textureImporterSettings) {+ (scene as SceneData & { textureImporterSettings: unknown }).textureImporterSettings =+ textureImporterSettings;+ }+ return scene;+}++function loadScene(app: App, sceneData: SceneData): Promise<void> {+ return loadRuntimeScene({+ app,+ module: fakeModule,+ sceneData,+ source: {+ backend: fakeBackend,+ decodePixels: () => Promise.reject(new Error('no textures in this test')),+ },+ spineManager: null,+ });+}++describe('per-App runtime Assets persistence', () => {+ it('replaces a pre-existing (AssetPlugin) Assets resource once, then reuses its own', async () => {+ const app = makeFakeApp();+ const pluginAssets = AssetsClass.create({ backend: fakeBackend, module: fakeModule });+ app.insertResource(AssetsResource, pluginAssets);++ await loadScene(app, makeScene('a'));+ const first = app.getResource(AssetsResource);+ expect(first).not.toBe(pluginAssets);++ await loadScene(app, makeScene('b'));+ expect(app.getResource(AssetsResource)).toBe(first);+ });++ it('keeps the addressable manifest across scene loads (loadGroup stays armed)', async () => {+ const app = makeFakeApp();+ await loadScene(app, makeScene('a'));++ const assets = app.getResource(AssetsResource);+ assets.setManifest(ManifestModel.empty());+ expect(assets.getManifest()).not.toBeNull();++ await loadScene(app, makeScene('b'));+ expect(app.getResource(AssetsResource)).toBe(assets);+ expect(assets.getManifest()).not.toBeNull();+ });++ it('accumulates texture import settings across scenes instead of replacing them', async () => {+ const app = makeFakeApp();+ await loadScene(app, makeScene('a', {+ 'assets/a.png': { filterMode: 'nearest', wrapMode: 'repeat' },+ }));+ await loadScene(app, makeScene('b', {+ 'assets/b.png': { filterMode: 'linear', wrapMode: 'clamp' },+ }));++ const assets = app.getResource(AssetsResource) as unknown as {+ textureImportResolver_: ((ref: string) => { filter?: string; wrap?: string } | undefined) | null;+ };+ expect(assets.textureImportResolver_?.('assets/a.png')).toEqual({ filter: 'nearest', wrap: 'repeat' });+ expect(assets.textureImportResolver_?.('assets/b.png')).toEqual({ filter: 'linear', wrap: 'clamp' });+ });+});