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(sdk): an atlas page is decoded by whatever this realm decodes KTX2 with

esengine392361cfccf5
diff --git a/sdk/src/dragonbones/loadDragonBonesScene.ts b/sdk/src/dragonbones/loadDragonBonesScene.ts
index d9d94815b..7304cf569 100644
--- a/sdk/src/dragonbones/loadDragonBonesScene.ts
+++ b/sdk/src/dragonbones/loadDragonBonesScene.ts
@@ -28,8 +28,8 @@ import { discoverSceneAssets } from '../asset/discoverAssets';
import { getAssetTypeEntry } from '../assetTypes';
import { requireResourceManager } from '../wasm/resourceManager';
import { log } from '../util/logger';
-import { createTextureFromPixels, type RuntimeAssetSource } from '../runtime/runtimeAssets';
-import { isKtx2Path, type BasisTranscoder } from '../asset/compressed';
+import { createAtlasPageTexture, type RuntimeAssetSource } from '../runtime/runtimeAssets';
+import type { BasisTranscoder } from '../asset/compressed';
import type { DragonBonesManager } from './DragonBonesManager';
/** Lazily yields the realm's Basis transcoder, or null where a cook cannot have
@@ -152,20 +152,15 @@ async function uploadAtlasImage_(
try {
const staged = resolveRef(imagePath);
- let decoded: { width: number; height: number; pixels: Uint8Array };
- if (isKtx2Path(staged)) {
- const transcoder = await transcoderProvider?.();
- if (!transcoder) throw new Error('KTX2 atlas page but no Basis transcoder in this realm');
- const rgba = transcoder.transcodeToRgba(new Uint8Array(await source.backend.fetchBinary(staged)));
- if (!rgba) throw new Error(`KTX2 transcode failed: ${staged}`);
- decoded = { width: rgba.width, height: rgba.height, pixels: rgba.data };
- } else {
- decoded = await source.decodePixels(staged, false);
- }
+ const page = await createAtlasPageTexture(
+ staged,
+ (p) => source.backend.fetchBinary(p),
+ (p) => source.decodePixels(p, false),
+ transcoderProvider, module,
+ );
const rm = requireResourceManager();
- const handle = createTextureFromPixels(module, decoded, false);
- rm.registerTextureWithPath(handle, imagePath);
- return rm.getTextureGLId(handle);
+ rm.registerTextureWithPath(page.handle, imagePath);
+ return rm.getTextureGLId(page.handle);
} catch (err) {
log.warn('runtime', `Failed to load DragonBones atlas image: ${imagePath}`, err);
return -1;
diff --git a/sdk/src/runtime/runtimeAssets.ts b/sdk/src/runtime/runtimeAssets.ts
index 76dc2b3d7..a661c5f72 100644
--- a/sdk/src/runtime/runtimeAssets.ts
+++ b/sdk/src/runtime/runtimeAssets.ts
@@ -14,6 +14,7 @@ import { linearColorSpace } from '../ecs/env';
import type { Backend } from '../asset/Backend';
import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';
import { requireResourceManager } from '../wasm/resourceManager';
+import { isKtx2Path, type BasisTranscoder } from '../asset/compressed';
import { withMalloc } from '../wasm/wasmScratch';
/**
@@ -77,6 +78,38 @@ const WRAP_MODE_MAP: Record<string, number> = { 'repeat': 0, 'clamp': 1, 'mirror
/** Upload decoded RGBA pixels as a GL texture; returns the engine texture handle.
* `module` is the wasm-heap marshalling vehicle; it may be null on the native
* (embedded-Dawn) backend, whose ResourceManager takes the bytes directly. */
+/**
+ * A texture for an ATLAS PAGE, in whichever form the cook left it. A KTX2 page
+ * goes to the ResourceManager where it can decode one (a native host's own basis)
+ * and to the realm's wasm transcoder where it cannot — the choice TextureLoader
+ * makes for an ordinary texture, which is why it is not made twice more.
+ */
+export async function createAtlasPageTexture(
+ staged: string,
+ fetchBinary: (path: string) => Promise<ArrayBuffer>,
+ decodePixels: (path: string) => Promise<{ width: number; height: number; pixels: Uint8Array }>,
+ transcoderProvider: (() => Promise<BasisTranscoder | null>) | undefined,
+ module: ESEngineModule | null,
+): Promise<{ handle: number; width: number; height: number }> {
+ if (!isKtx2Path(staged)) {
+ const decoded = await decodePixels(staged);
+ return { handle: createTextureFromPixels(module, decoded, false), ...decoded };
+ }
+ const bytes = new Uint8Array(await fetchBinary(staged));
+ const rm = requireResourceManager();
+ if (rm.createTextureFromKTX2) {
+ const r = rm.createTextureFromKTX2(bytes, linearColorSpace());
+ if (!r) throw new Error(`KTX2 transcode failed: ${staged}`);
+ return r;
+ }
+ const transcoder = await transcoderProvider?.();
+ if (!transcoder) throw new Error('KTX2 atlas page but no Basis transcoder in this realm');
+ const rgba = transcoder.transcodeToRgba(bytes);
+ if (!rgba) throw new Error(`KTX2 transcode failed: ${staged}`);
+ const decoded = { width: rgba.width, height: rgba.height, pixels: rgba.data };
+ return { handle: createTextureFromPixels(module, decoded, false), ...decoded };
+}
+
export function createTextureFromPixels(
module: ESEngineModule | null,
result: { width: number; height: number; pixels: Uint8Array },
diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.ts
index eaf9e4179..c313f4874 100644
--- a/sdk/src/spine/loadSpineScene.ts
+++ b/sdk/src/spine/loadSpineScene.ts
@@ -25,8 +25,8 @@ import { requireResourceManager } from '../wasm/resourceManager';
import { log } from '../util/logger';
import { SpineManager, type SpineVersion } from './SpineManager';
import { parseSpineAtlasPages } from './atlasPages';
-import { createTextureFromPixels, type RuntimeAssetSource } from '../runtime/runtimeAssets';
-import { isKtx2Path, type BasisTranscoder } from '../asset/compressed';
+import { createAtlasPageTexture, type RuntimeAssetSource } from '../runtime/runtimeAssets';
+import type { BasisTranscoder } from '../asset/compressed';
/**
* The in-place editable spine props from a SpineAnimation component's data — the
@@ -130,22 +130,17 @@ export async function loadSpineAssets(
// file, so the derived logical path resolves through the
// manifest/catalog like every other fetch.
const staged = resolveRef(texPath);
- let result: { width: number; height: number; pixels: Uint8Array };
- if (isKtx2Path(staged)) {
- const transcoder = await transcoderProvider?.();
- if (!transcoder) throw new Error('KTX2 atlas page but no Basis transcoder in this realm');
- const rgba = transcoder.transcodeToRgba(new Uint8Array(await source.backend.fetchBinary(staged)));
- if (!rgba) throw new Error(`KTX2 transcode failed: ${staged}`);
- result = { width: rgba.width, height: rgba.height, pixels: rgba.data };
- } else {
- result = await source.decodePixels(staged, false);
- }
- const handle = createTextureFromPixels(module, result, false);
- rm.registerTextureWithPath(handle, texPath);
+ const page = await createAtlasPageTexture(
+ staged,
+ (p) => source.backend.fetchBinary(p),
+ (p) => source.decodePixels(p, false),
+ transcoderProvider, module,
+ );
+ rm.registerTextureWithPath(page.handle, texPath);
textures.set(texName, {
- glId: rm.getTextureGLId(handle),
- w: result.width,
- h: result.height,
+ glId: rm.getTextureGLId(page.handle),
+ w: page.width,
+ h: page.height,
});
} catch (err) {
log.warn('runtime', `Failed to load texture: ${texPath}`, err);
diff --git a/sdk/tests/spine-atlas-page-resolve.test.ts b/sdk/tests/spine-atlas-page-resolve.test.ts
index 2895e752e..fe064475a 100644
--- a/sdk/tests/spine-atlas-page-resolve.test.ts
+++ b/sdk/tests/spine-atlas-page-resolve.test.ts
@@ -11,17 +11,19 @@
*/
import { describe, it, expect, vi } from 'vitest';
-const { rm, createTextureFromPixels } = vi.hoisted(() => ({
+// The page-form decision (KTX2 through the realm's decoder, else the image path)
+// lives in runtimeAssets and is the thing under test, so only the upload below it
+// is stood in for — a ResourceManager that takes bytes, as a native host's does.
+const { rm } = vi.hoisted(() => ({
rm: {
registerTextureWithPath: vi.fn(),
getTextureGLId: vi.fn(() => 7),
+ createTextureFromBytes: vi.fn(() => 11),
},
- createTextureFromPixels: vi.fn(() => 11),
}));
vi.mock('../src/wasm/resourceManager', () => ({
requireResourceManager: () => rm,
}));
-vi.mock('../src/runtime/runtimeAssets', () => ({ createTextureFromPixels }));
import { loadSpineAssets } from '../src/spine/loadSpineScene';
import type { RuntimeAssetSource } from '../src/runtime/runtimeAssets';
@@ -103,6 +105,25 @@ describe('loadSpineAssets resolves atlas page paths through the manifest', () =>
expect(source.decodePixels).toHaveBeenCalledWith('spineboy.png', false);
});
+ // A device has no wasm transcoder and never will; its host decodes KTX2 in C++.
+ // Asking for the transcoder there is what left every Spine atlas unloadable.
+ it('takes a KTX2 page from the ResourceManager when it can decode one', async () => {
+ const source = makeSource({ 'assets/spine/spineboy.png': 'assets/spine/spineboy.ktx2' });
+ const createTextureFromKTX2 = vi.fn(() => ({ handle: 21, width: 8, height: 8 }));
+ Object.assign(rm, { createTextureFromKTX2 });
+ try {
+ const info = await loadSpineAssets({} as never, source, null, PAIR);
+
+ expect(createTextureFromKTX2).toHaveBeenCalledTimes(1);
+ expect(source.decodePixels).not.toHaveBeenCalled();
+ expect(rm.registerTextureWithPath).toHaveBeenCalledWith(21, 'assets/spine/spineboy.png');
+ const tex = info.get('assets/spine/boy.skel:assets/spine/boy.atlas')!.textures.get('spineboy.png');
+ expect(tex).toEqual({ glId: 7, w: 8, h: 8 });
+ } finally {
+ delete (rm as { createTextureFromKTX2?: unknown }).createTextureFromKTX2;
+ }
+ });
+
it('a KTX2 page in a realm without basis warns and skips, not throws', async () => {
const source = makeSource({ 'assets/spine/spineboy.png': 'assets/spine/spineboy.ktx2' });
const info = await loadSpineAssets({} as never, source, null, PAIR, async () => null);