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(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.ts
index 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/basisTransco
export 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.ts
index 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<vo
applyBuildRuntimeConfig(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<vo
scenes.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.ts
new file mode 100644
index 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' });
+ });
+});