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(sdk): one image-decode path for every texture provider
esengine549e4e17aab8
diff --git a/desktop/src/engine/spineLoad.ts b/desktop/src/engine/spineLoad.tsindex 139df25c3..4722ddd4f 100644--- a/desktop/src/engine/spineLoad.ts+++ b/desktop/src/engine/spineLoad.ts@@ -2,12 +2,12 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { SpinePlugin, loadSpineSceneEntities } from 'esengine/spine';import type { RuntimeAssetProvider } from 'esengine/spine';-import type { App, SceneData } from 'esengine';+import { decodeImagePixels, type App, type SceneData } from 'esengine';/*** Fetch-backed asset provider for spine in the editor: skeleton/atlas come over- * fetch as text/bytes; the atlas PNG is decoded to RGBA via createImageBitmap →- * canvas → getImageData (the same path the play realm uses — robust across the+ * fetch as text/bytes; the atlas PNG is decoded to RGBA via the shared+ * `decodeImagePixels` (the same path the play realm uses — robust across the* editor's http/app:// origins). `toUrl` maps an asset ref to a fetchable URL.*/class EditorSpineProvider implements RuntimeAssetProvider {@@ -32,19 +32,7 @@ class EditorSpineProvider implements RuntimeAssetProvider {async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {const r = await fetch(this.toUrl(ref));if (!r.ok) throw new Error(`spine texture ${r.status}: ${ref}`);- const bitmap = await createImageBitmap(await r.blob(), {- premultiplyAlpha: 'none',- colorSpaceConversion: 'none',- });- const canvas = document.createElement('canvas');- canvas.width = bitmap.width;- canvas.height = bitmap.height;- const ctx = canvas.getContext('2d');- if (!ctx) throw new Error('2d context unavailable for spine texture decode');- ctx.drawImage(bitmap, 0, 0);- bitmap.close?.();- const data = ctx.getImageData(0, 0, canvas.width, canvas.height);- return { width: canvas.width, height: canvas.height, pixels: new Uint8Array(data.data.buffer) };+ return decodeImagePixels(await r.blob());}}diff --git a/sdk/src/asset/imageDecode.ts b/sdk/src/asset/imageDecode.tsnew file mode 100644index 000000000..5a8af609e--- /dev/null+++ b/sdk/src/asset/imageDecode.ts@@ -0,0 +1,66 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file imageDecode.ts+ * @brief The single image-decode path for every texture provider (editor,+ * play realm, preview, spine). Routing all of them through one module+ * keeps premultiply / colorspace / orientation identical, so the+ * edit/play/ship paths can't drift — that drift is the texture-flip+ * class of bug. Vertical orientation is baked via `imageOrientation`,+ * NEVER `UNPACK_FLIP_Y_WEBGL`, which Chromium/ANGLE silently ignore for+ * `ImageBitmap` sources (uploads every texture upside-down otherwise).+ */+import { platformCreateCanvas } from '../platform';++/**+ * Canonical `createImageBitmap` options. premultiply + colorspace conversion are+ * OFF so the engine owns blending and color (matching the C++ upload); `flip`+ * bakes a vertical flip into the bitmap so callers upload it as-is.+ */+export function imageBitmapOptions(flip: boolean): ImageBitmapOptions {+ return {+ premultiplyAlpha: 'none',+ colorSpaceConversion: 'none',+ imageOrientation: flip ? 'flipY' : 'from-image',+ };+}++/**+ * Decode a source into a GL-oriented `ImageBitmap` for direct `texImage2D` upload+ * (the editor/web TextureLoader). With `flip`, the result samples file-top at v=1;+ * upload it with `UNPACK_FLIP_Y_WEBGL` off (the orientation is already baked).+ */+export function decodeImageBitmap(src: ImageBitmapSource, flip: boolean): Promise<ImageBitmap> {+ return createImageBitmap(src, imageBitmapOptions(flip));+}++export interface DecodedPixels {+ width: number;+ height: number;+ pixels: Uint8Array;+}++/**+ * Decode a source into a top-first RGBA pixel buffer for the C++ `createTexture`+ * upload path (play realm, preview, spine). Orientation stays top-first here; the+ * consumer chooses the final convention via `createTextureFromPixels(flipY)` —+ * v=1=top for general textures, v=0=top for spine / bitmap fonts.+ */+export async function decodeImagePixels(src: ImageBitmapSource): Promise<DecodedPixels> {+ const bitmap = await decodeImageBitmap(src, false);+ try {+ const canvas = platformCreateCanvas(bitmap.width, bitmap.height);+ canvas.width = bitmap.width;+ canvas.height = bitmap.height;+ const ctx = canvas.getContext('2d', { willReadFrequently: true }) as+ | CanvasRenderingContext2D+ | OffscreenCanvasRenderingContext2D+ | null;+ if (!ctx) throw new Error('imageDecode: 2D context unavailable for pixel decode');+ ctx.drawImage(bitmap as CanvasImageSource, 0, 0);+ const data = ctx.getImageData(0, 0, bitmap.width, bitmap.height);+ return { width: bitmap.width, height: bitmap.height, pixels: new Uint8Array(data.data.buffer) };+ } finally {+ bitmap.close?.();+ }+}diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.tsindex 86010f305..9e101fbf9 100644--- a/sdk/src/asset/index.ts+++ b/sdk/src/asset/index.ts@@ -8,6 +8,7 @@ export {} from './AddressableManifest';export { AsyncCache } from './AsyncCache';export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';+export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels } from './imageDecode';export { MaterialLoader, type LoadedMaterial, type ShaderLoader } from './MaterialLoader';export { AssetRefCounter, type AssetRefInfo } from './AssetRefCounter';diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex 3c4c0fc07..e01498d95 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -2,6 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { AssetLoader, LoadContext, TextureResult } from '../AssetLoader';import { platformCreateCanvas, platformCreateImage } from '../../platform';+import { decodeImageBitmap } from '../imageDecode';import { requireResourceManager } from '../../resourceManager';import type { ESEngineModule } from '../../wasm';import { withMalloc } from '../../wasmScratch';@@ -136,12 +137,7 @@ export class TextureLoader implements AssetLoader<TextureResult> {img.onload = async () => {if (typeof createImageBitmap !== 'undefined') {try {- const bitmap = await createImageBitmap(img, {- premultiplyAlpha: 'none',- colorSpaceConversion: 'none',- imageOrientation: flip ? 'flipY' : 'from-image',- });- resolve(bitmap);+ resolve(await decodeImageBitmap(img, flip));return;} catch {// fallbackdiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex a64b493e2..1bcf2e284 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -50,6 +50,10 @@ export {assetPlugin,MaterialLoader,AssetRefCounter,+ decodeImageBitmap,+ decodeImagePixels,+ imageBitmapOptions,+ type DecodedPixels,type AddressableManifest,type AddressableManifestGroup,type AddressableManifestAsset,diff --git a/sdk/src/playRealmRuntime.ts b/sdk/src/playRealmRuntime.tsindex 7cfc4d040..86dea43fa 100644--- a/sdk/src/playRealmRuntime.ts+++ b/sdk/src/playRealmRuntime.ts@@ -21,6 +21,7 @@ import type { AddressableManifest } from './asset/AddressableManifest';import type { SceneData } from './scene';import { fetchPhysicsModule } from './physics';import type { Vec2 } from './types';+import { decodeImagePixels } from './asset/imageDecode';const UUID_PREFIX = '@uuid:';@@ -47,12 +48,11 @@ export interface PlayRealmRuntimeConfig {/*** Fetches scene assets over the realm origin, resolving `@uuid:` refs through the- * editor-supplied manifest. Images are decoded via fetch → blob →- * `createImageBitmap` → canvas → getImageData (NOT `<img crossorigin>`: Chromium- * refuses CORS-mode images for custom schemes like `estella://`, and a non-CORS- * `<img>` would taint the canvas so getImageData throws — fetch+blob sidesteps- * both). `estella://` is fetchable because it's a privileged supportFetchAPI- * scheme; the editor's handler returns `access-control-allow-origin: *`.+ * editor-supplied manifest. Images go fetch → blob → the shared `decodeImagePixels`+ * (NOT `<img crossorigin>`: Chromium refuses CORS-mode images for custom schemes+ * like `estella://`, and a non-CORS `<img>` would taint the canvas so getImageData+ * throws — fetch+blob sidesteps both). `estella://` is fetchable because it's a+ * privileged supportFetchAPI scheme; the editor returns `access-control-allow-origin: *`.*/class FetchAssetProvider implements RuntimeAssetProvider {constructor(private readonly manifest: Record<string, string>) {}@@ -68,19 +68,7 @@ class FetchAssetProvider implements RuntimeAssetProvider {const url = this.resolvePath(ref);const res = await fetch(url);if (!res.ok) throw new Error(`image fetch failed (${res.status}): ${url}`);- const bitmap = await createImageBitmap(await res.blob(), { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });- try {- const cv = document.createElement('canvas');- cv.width = bitmap.width;- cv.height = bitmap.height;- const ctx = cv.getContext('2d');- if (!ctx) throw new Error('2d context unavailable');- ctx.drawImage(bitmap, 0, 0);- const id = ctx.getImageData(0, 0, bitmap.width, bitmap.height);- return { width: bitmap.width, height: bitmap.height, pixels: new Uint8Array(id.data.buffer) };- } finally {- bitmap.close();- }+ return decodeImagePixels(await res.blob());}async readText(ref: string): Promise<string> {diff --git a/sdk/src/preview/WebAssetProvider.ts b/sdk/src/preview/WebAssetProvider.tsindex 51402bde5..d53370863 100644--- a/sdk/src/preview/WebAssetProvider.ts+++ b/sdk/src/preview/WebAssetProvider.ts@@ -9,6 +9,7 @@ import type { RuntimeAssetProvider } from '../runtimeLoader';import type { SceneData } from '../scene';import { getComponentAssetFieldDescriptors, getComponentSpineFieldDescriptor } from '../scene';import { getAssetTypeEntry } from '../assetTypes';+import { decodeImagePixels } from '../asset/imageDecode';import { log } from '../logger';export class WebAssetProvider implements RuntimeAssetProvider {@@ -124,20 +125,8 @@ export class WebAssetProvider implements RuntimeAssetProvider {}async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {- const url = this.resolveUrl(ref);- const resp = await fetch(url);- const blob = await resp.blob();- const bitmap = await createImageBitmap(blob);- const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);- const ctx = canvas.getContext('2d')!;- ctx.drawImage(bitmap, 0, 0);- const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height);- bitmap.close();- return {- width: imageData.width,- height: imageData.height,- pixels: new Uint8Array(imageData.data.buffer),- };+ const resp = await fetch(this.resolveUrl(ref));+ return decodeImagePixels(await resp.blob());}resolvePath(ref: string): string {