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.

fix(assets): Play applies import settings, so 9-slice survives leaving edit mode

yhhdd6409b1beed
diff --git a/desktop/src/engine/playProtocol.ts b/desktop/src/engine/playProtocol.ts
index cde9f05d2..9633f03f5 100644
--- a/desktop/src/engine/playProtocol.ts
+++ b/desktop/src/engine/playProtocol.ts
@@ -11,6 +11,7 @@
* import of an editor module here would break the realm bundle. Type-only
* imports are erased before resolution and are safe.
*/
+import type { ParsedTextureImportSettings } from 'esengine';
import type { SceneData, PhysicsPluginConfig, AudioProjectConfig, ThemeOverrides, AddressableManifest } from 'esengine';
/**
@@ -53,6 +54,11 @@ export interface PlayNetConfig {
export interface PlayPayload {
sceneData: SceneData;
assetManifest: Record<string, string>;
+ /** Per-texture import settings (filter/wrap/sRGB, 9-slice border) keyed by the
+ * authored `@uuid:` ref, so the realm samples and slices its textures exactly
+ * as the edit viewport does. They describe the ASSET, so they travel beside
+ * the scene rather than inside it. */
+ textureImports?: Record<string, ParsedTextureImportSettings>;
/** AddressableManifest (groups + bundle modes) so `Assets.loadGroup` — remote /
* lazy groups — works in Play exactly as in a shipped build. */
manifest?: AddressableManifest;
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index f8855c0ef..863c59804 100644
--- a/desktop/src/playHost.ts
+++ b/desktop/src/playHost.ts
@@ -208,6 +208,9 @@ async function buildAppAndRun(msg: InitMessage): Promise<void> {
canvas,
sceneData: msg.sceneData,
assetManifest: msg.assetManifest,
+ // Per-texture import settings from the editor's asset database, so the realm
+ // samples and 9-slices its textures exactly as the edit viewport does.
+ textureImports: msg.textureImports,
// Addressable manifest → Assets.loadGroup works in the realm (remote / lazy
// groups) just like a shipped build. Remote assets resolve same-origin
// estella:// via assetBaseUrl, so no remoteRoot is set here.
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 186fa4ad8..f047d7d43 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -3,6 +3,7 @@
import { createStore } from 'zustand/vanilla';
import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, flattenPrefab, collectExternalEntityRefs, collapseInstance, applyDeltaToSource, buildVariant, validateOverrides, setTextureParams, setTextureSliceBorder, textureImportSettingsFrom, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides, resolveAssetGroup, folderGroupMode, withFolderGroup, folderAlwaysInclude, withFolderAlwaysInclude, withActiveRemoteRoot } from 'esengine';
import { importerDefaults, applyImporterEdit } from './assetImporter';
+import type { ParsedTextureImportSettings } from 'esengine';
import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData, ThemeOverrides, StaleOverride, PrefabOverride, AddressableManifest, AssetGroupsConfig, AssetGroupMode } from 'esengine';
import { EngineHost } from '@/engine/EngineHost';
import { applyWidgetTheme } from '@/engine/widgetTheme';
@@ -1495,6 +1496,7 @@ class ProjectStoreImpl {
playPayload(): {
sceneData: SceneData;
assetManifest: Record<string, string>;
+ textureImports: Record<string, ParsedTextureImportSettings>;
manifest: AddressableManifest;
entrySceneName?: string;
extraScenes?: Array<{ name: string; path: string }>;
@@ -1513,6 +1515,15 @@ class ProjectStoreImpl {
// same-origin estella:// — no cross-scheme dance needed.
const assetManifest: Record<string, string> = {};
for (const [uuid, path] of this.uuidToPath) assetManifest[uuid] = `estella://project/${path}`;
+ // Import settings ride to the realm keyed by the authored `@uuid:` ref — the
+ // spelling a component holds — so a played scene samples and slices exactly
+ // as the edit viewport does. They stay OUT of the scene: they describe the
+ // asset, and a copy in the scene goes stale when the `.meta` changes.
+ const textureImports: Record<string, ParsedTextureImportSettings> = {};
+ for (const [uuid, importer] of this.uuidToImporter) {
+ const settings = textureImportSettingsFrom(importer);
+ if (settings) textureImports[UUID_PREFIX + uuid] = settings;
+ }
// Play == ship: register every other project scene under its export name
// (scenes-dir-relative path sans extension — the same rule exportGame's
// discoverProjectScenes uses), so SceneManager.switchTo('levels/boss')
@@ -1560,7 +1571,7 @@ class ProjectStoreImpl {
const uiTheme = this.uiTheme();
const uiThemeOverrides = this.uiThemeOverrides();
return {
- sceneData, assetManifest, manifest: this.buildPlayManifest(), physicsEnabled: f.enabled, physicsConfig,
+ sceneData, assetManifest, textureImports, manifest: this.buildPlayManifest(), physicsEnabled: f.enabled, physicsConfig,
...(currentScene ? { entrySceneName: exportSceneName(currentScene) } : {}),
...(extraScenes.length > 0 ? { extraScenes } : {}),
...(audioConfig.buses ? { audioConfig } : {}),
diff --git a/sdk/etc/dragonbones.api.md b/sdk/etc/dragonbones.api.md
index 3dde489d4..ef0b599cb 100644
--- a/sdk/etc/dragonbones.api.md
+++ b/sdk/etc/dragonbones.api.md
@@ -141,6 +141,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
## applyDragonBonesEntities — function
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 230cf11a4..f15e478c8 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4850,6 +4850,7 @@ physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
+textureImports: Record<string, ParsedTextureImportSettings> | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
wasmBaseUrl: string | undefined
@@ -5599,6 +5600,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
## RuntimeBuildConfig — interface
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 524b3c010..a129f606a 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5004,6 +5004,7 @@ physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
+textureImports: Record<string, ParsedTextureImportSettings> | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
wasmBaseUrl: string | undefined
@@ -5763,6 +5764,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
## RuntimeBuildConfig — interface
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 96867b4bc..c39b7a748 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4845,6 +4845,7 @@ physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
+textureImports: Record<string, ParsedTextureImportSettings> | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
wasmBaseUrl: string | undefined
@@ -5594,6 +5595,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
## RuntimeBuildConfig — interface
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index eb4085e9e..0a4e2905e 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5060,6 +5060,7 @@ physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
+textureImports: Record<string, ParsedTextureImportSettings> | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
wasmBaseUrl: string | undefined
@@ -5809,6 +5810,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
## RuntimeBuildConfig — interface
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index 2b3623a8d..e869ba470 100644
--- a/sdk/etc/spine.api.md
+++ b/sdk/etc/spine.api.md
@@ -59,6 +59,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
## Spine — const
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 014876a97..fb24fa450 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4852,6 +4852,7 @@ physicsConfig: PhysicsPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
+textureImports: Record<string, ParsedTextureImportSettings> | undefined
uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
wasmBaseUrl: string | undefined
@@ -5601,6 +5602,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
## RuntimeBuildConfig — interface
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 8b2b5361a..a1fbbced0 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -40,7 +40,6 @@ import type { SceneData } from '../scene';
import { SceneHandle, type ReleaseCallback } from './SceneHandle';
import type { AssetRegistry } from './AssetRegistry';
import { UUID_REF_PREFIX } from './AssetRegistry';
-import { textureImportSettingsFrom } from './textureImportSettings';
import type { AssetRefCounter } from './AssetRefCounter';
import { log } from '../logger';
@@ -1345,18 +1344,6 @@ export class Assets {
setAssetRegistry(registry: AssetRegistry): void {
this.assetRegistry_ = registry;
this.assetRefResolver_ = (ref) => registry.resolveRef(ref);
- // The registry carries each asset's importer block (the cook copies it
- // into the ship manifest verbatim), so a shipped game has the same
- // import settings the editor does — it just never read them. Default the
- // texture resolver to it, so filter/wrap/sRGB and the 9-slice border
- // survive the build. A host that installed its own resolver keeps it.
- if (!this.textureImportResolver_) {
- this.textureImportResolver_ = (ref) => {
- const path = this.resolveLoadPath_(ref);
- const entry = registry.getEntryByPath(path) ?? registry.getEntryByPath(ref);
- return textureImportSettingsFrom(entry?.importer);
- };
- }
}
getAssetRegistry(): AssetRegistry | null {
diff --git a/sdk/src/playRealmRuntime.ts b/sdk/src/playRealmRuntime.ts
index b2adc9e54..fd995eed5 100644
--- a/sdk/src/playRealmRuntime.ts
+++ b/sdk/src/playRealmRuntime.ts
@@ -22,6 +22,7 @@ import { VideoPlayer } from './video/VideoAPI';
import { initRuntime } from './runtimeLoader';
import type { ThemeOverrides } from './ui';
import type { RuntimeAssetSource } from './runtimeAssets';
+import type { ParsedTextureImportSettings } from './asset/textureImportSettings';
import { HttpBackend } from './asset/Backend';
import { Catalog, type CatalogData } from './asset/Catalog';
import type { AddressableManifest } from './asset/AddressableManifest';
@@ -54,6 +55,13 @@ export interface PlayRealmRuntimeConfig {
* Omit when files are served at their logical paths (the editor realm).
*/
assetPathMap?: Record<string, string>;
+ /**
+ * Per-texture import settings (filter/wrap/sRGB, 9-slice border) keyed by the
+ * authored ref. Supplied by the editor from its asset database so a played
+ * scene samples and slices its textures exactly as the edit viewport does —
+ * without the settings being copied into the scene, where they would go stale.
+ */
+ textureImports?: Record<string, ParsedTextureImportSettings>;
/**
* Logical path → build-path catalog for the same cooked case: loaders fetch
* their INNER text refs (a material's shader) through Catalog.getBuildPath,
@@ -142,6 +150,7 @@ function createPlayRealmSource(
manifest: Record<string, string>,
assetBaseUrl?: string,
pathMap?: Record<string, string>,
+ textureImports?: Record<string, ParsedTextureImportSettings>,
): RuntimeAssetSource {
const backend = new HttpBackend({ baseUrl: '' });
return {
@@ -152,6 +161,10 @@ function createPlayRealmSource(
// manifest's resolved URLs — both keep the real extension, which is all
// the .eslocale discovery filters on.
listAssetPaths: () => (pathMap ? Object.keys(pathMap) : Object.values(manifest)),
+ // Keyed by the AUTHORED ref (`@uuid:…` or a project path) — the same
+ // spelling a component holds — because that is what the loader asks with,
+ // before resolveRef turns it into a realm URL.
+ ...(textureImports ? { textureImportSettings: (ref: string) => textureImports[ref] } : {}),
};
}
@@ -162,7 +175,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);
+ const source = createPlayRealmSource(assetManifest, assetBaseUrl, config.assetPathMap, config.textureImports);
applyAssetRefResolvers(app, (ref) => resolvePlayAssetRef(ref, assetManifest, assetBaseUrl, config.assetPathMap));
const entryName = config.entrySceneName ?? '__play';
await initRuntime({
diff --git a/sdk/src/runtimeAssets.ts b/sdk/src/runtimeAssets.ts
index 22af70e5f..5ebc44549 100644
--- a/sdk/src/runtimeAssets.ts
+++ b/sdk/src/runtimeAssets.ts
@@ -12,6 +12,7 @@ import { linearColorSpace } from './env';
import type { ESEngineModule } from './wasm';
import { linearColorSpace } from './env';
import type { Backend } from './asset/Backend';
+import type { ParsedTextureImportSettings } from './asset/textureImportSettings';
import { requireResourceManager } from './resourceManager';
import { withMalloc } from './wasmScratch';
@@ -49,6 +50,18 @@ export interface RuntimeAssetSource {
* warns when a scene needs them).
*/
listAssetPaths?(): string[];
+ /**
+ * Per-texture import settings (filter/wrap/sRGB and the 9-slice border) for a
+ * ref. These belong to the ASSET, not to any scene that uses it, which is why
+ * they arrive through the realm's source alongside `resolveRef` rather than
+ * being copied into every scene that references the texture — a copy in the
+ * scene goes stale the moment the `.meta` changes.
+ *
+ * Optional: a realm without it renders with loader defaults. Each realm has
+ * the data already — the editor from its asset database, a cooked build from
+ * the `importer` block the cook copies into the ship manifest.
+ */
+ textureImportSettings?(ref: string): ParsedTextureImportSettings | undefined;
}
export interface TextureParams {
diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.ts
index ce5d2d873..83eb66c6a 100644
--- a/sdk/src/runtimeLoader.ts
+++ b/sdk/src/runtimeLoader.ts
@@ -110,8 +110,17 @@ function ensureRuntimeAssets(
return mod ? transcoderFromModule(mod as unknown as BasisWasmModule) : null;
});
+ // Two suppliers, one resolver, in precedence order:
+ // - the REALM's asset source describes the ASSET (the editor's database, a
+ // cooked build's manifest) and is authoritative;
+ // - the per-scene map below is the embedder's channel for a scene that
+ // carries its own `textureImporterSettings`.
+ // Asset-level wins: a stale copy inside a scene must not override what the
+ // asset actually says today.
const settings: Record<string, TextureImportSettings> = {};
- assets.setTextureImportSettingsResolver((ref) => settings[ref]);
+ assets.setTextureImportSettingsResolver(
+ (ref) => source.textureImportSettings?.(ref) ?? settings[ref],
+ );
runtimeImportSettings.set(assets, settings);
app.insertResource(AssetsResource, assets);