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
fix(sdk): upload textures right-side-up — ImageBitmap ignores UNPACK_FLIP_Y
esenginef0aa252ac0e7
diff --git a/desktop/package.json b/desktop/package.jsonindex 86af336f5..1072d962f 100644--- a/desktop/package.json+++ b/desktop/package.json@@ -19,6 +19,7 @@"verify:render:text": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-text-sdf.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-text-sdf.textures.json electron scripts/headless-verify.mjs","verify:render:text:rect": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-text-rect.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-text-sdf.textures.json electron scripts/headless-verify.mjs","verify:render:uinode": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-node-flex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-node-flex.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 electron scripts/headless-verify.mjs",+ "verify:render:tilemap": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-flip.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.46,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.84,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.46,\\\"y\\\":0.84,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.84,\\\"y\\\":0.84,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs","verify:smoke": "vite build && electron scripts/headless-smoke.mjs","mcp": "electron electron/mcp/server.mjs","mcp:smoke": "vite build && node electron/mcp/smoke.mjs"diff --git a/desktop/public/scenes/tilemap-flip.esscene b/desktop/public/scenes/tilemap-flip.esscenenew file mode 100644index 000000000..0ae83b7e7--- /dev/null+++ b/desktop/public/scenes/tilemap-flip.esscene@@ -0,0 +1,67 @@+{+ "version": "1.0",+ "name": "TilemapFlip",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 16,+ "y": -16,+ "z": 10+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 40,+ "isActive": true,+ "priority": 0+ }+ }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Tilemap",+ "parent": null,+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "TilemapLayer",+ "data": {+ "cellSize": {+ "x": 16,+ "y": 16+ },+ "tileset": "@uuid:aaaaaaaa-1111-2222-3333-444444444444",+ "tilesetColumns": 2,+ "tilesetRows": 2,+ "visible": true,+ "chunks": "RVNUTQEAAAAAAAAAAAAAAAEAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"+ }+ }+ ],+ "visible": true+ }+ ]+}\ No newline at end of filediff --git a/desktop/public/scenes/tilemap-flip.textures.json b/desktop/public/scenes/tilemap-flip.textures.jsonnew file mode 100644index 000000000..a8625788a--- /dev/null+++ b/desktop/public/scenes/tilemap-flip.textures.json@@ -0,0 +1,3 @@+{+ "aaaaaaaa-1111-2222-3333-444444444444": "/scenes/tilemap-flip/atlas.png"+}\ No newline at end of filediff --git a/desktop/public/scenes/tilemap-flip/atlas.png b/desktop/public/scenes/tilemap-flip/atlas.pngnew file mode 100644index 000000000..e63a3bdd1Binary files /dev/null and b/desktop/public/scenes/tilemap-flip/atlas.png differdiff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex cee4378f0..ce5b338fe 100644--- a/desktop/scripts/headless-verify.mjs+++ b/desktop/scripts/headless-verify.mjs@@ -63,7 +63,7 @@ function serveDist() {}function finish(result, server) {- const ok = result.ok && result.capture?.rendered;+ const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true);console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE}`);console.log('DRIVE_RESULT ' + JSON.stringify(result));process.exitCode = ok ? 0 : 1;@@ -110,6 +110,29 @@ app.whenReady().then(async () => {return { w: c.width, h: c.height, totalPixels: px.length / 4, nonZeroPixels: nonZero, min, max, spread, rendered: spread > 16 };})()`);const drawCalls = await exec('window.__estellaHeadless.api.getStats().drawCalls');+ // Optional color/orientation assertion: ESTELLA_VERIFY_EXPECT is a JSON array of+ // { x, y, rgb:[r,g,b], tol? } where x,y are normalized [0,1] from the TOP-LEFT.+ // This is the guard the all-textures-upside-down upload bug would have tripped+ // (TextureLoader imageOrientation) — `rendered` (color variation) alone misses it.+ let expect = null;+ if (process.env.ESTELLA_VERIFY_EXPECT) {+ const points = JSON.parse(process.env.ESTELLA_VERIFY_EXPECT);+ expect = await exec(`(() => {+ const pts = ${JSON.stringify(points)};+ const c = window.__estellaHeadless.api.captureViewport();+ const { width: w, height: h, rgba } = c;+ const out = pts.map((p) => {+ const px = Math.round(p.x * (w - 1));+ const glRow = (h - 1) - Math.round(p.y * (h - 1)); // GL readback is bottom-up+ const i = (glRow * w + px) * 4;+ const got = [rgba[i], rgba[i + 1], rgba[i + 2]];+ const tol = p.tol ?? 24;+ const ok = got.every((g, k) => Math.abs(g - p.rgb[k]) <= tol);+ return { x: p.x, y: p.y, want: p.rgb, got, ok };+ });+ return { points: out, ok: out.every((o) => o.ok) };+ })()`);+ }// Optional PNG dump (ESTELLA_VERIFY_OUT) of the engine framebuffer (not the// page) so the rendered frame can be eyeballed. GL readback is bottom-up → flip.if (process.env.ESTELLA_VERIFY_OUT) {@@ -124,7 +147,7 @@ app.whenReady().then(async () => {})()`);await writeFile(process.env.ESTELLA_VERIFY_OUT, Buffer.from(dataUrl.split(',')[1], 'base64'));}- finish({ ok: true, entityCount, drawCalls, capture }, server);+ finish({ ok: true, entityCount, drawCalls, capture, expect }, server);} catch (e) {finish({ ok: false, error: String((e && e.stack) || e) }, server);}diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex d960f4d34..3c4c0fc07 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -97,7 +97,7 @@ export class TextureLoader implements AssetLoader<TextureResult> {return this.loadCompressed(path, ctx, settings);}const url = ctx.backend.resolveUrl(ctx.catalog.getBuildPath(path));- const img = await this.loadImage(url);+ const img = await this.loadImage(url, flip);return this.createTextureFromImage(img, flip, settings);}@@ -121,7 +121,15 @@ export class TextureLoader implements AssetLoader<TextureResult> {return { handle: r.handle, width: r.width, height: r.height };}- private loadImage(src: string): Promise<HTMLImageElement | ImageBitmap> {+ /**+ * Decode `src` into a GPU-uploadable source. When `createImageBitmap` is+ * available we bake the vertical orientation into the bitmap here via+ * `imageOrientation`, NOT later via `UNPACK_FLIP_Y_WEBGL`: Chromium/ANGLE+ * silently ignore that pixel-store flag for `ImageBitmap` sources, so relying+ * on it uploads every texture upside-down. The raw `<img>` fallback keeps the+ * flag (it works for element/pixel sources) — see {@link createTextureFromImage}.+ */+ private loadImage(src: string, flip: boolean): Promise<HTMLImageElement | ImageBitmap> {return new Promise((resolve, reject) => {const img = platformCreateImage();img.crossOrigin = 'anonymous';@@ -131,6 +139,7 @@ export class TextureLoader implements AssetLoader<TextureResult> {const bitmap = await createImageBitmap(img, {premultiplyAlpha: 'none',colorSpaceConversion: 'none',+ imageOrientation: flip ? 'flipY' : 'from-image',});resolve(bitmap);return;@@ -151,10 +160,16 @@ export class TextureLoader implements AssetLoader<TextureResult> {const { width, height } = img;const gl = this.getWebGL2Context();+ // A bitmap is already oriented by loadImage (imageOrientation); flipping it+ // again at upload would double-flip it. Only raw <img>/pixel sources need+ // the UNPACK_FLIP_Y_WEBGL flip.+ const uploadFlip = (typeof ImageBitmap !== 'undefined' && img instanceof ImageBitmap)+ ? false : flip;+if (gl) {- return this.createTextureWebGL2(gl, img, width, height, flip, settings);+ return this.createTextureWebGL2(gl, img, width, height, uploadFlip, settings);}- return this.createTextureFallback(img, width, height, flip);+ return this.createTextureFallback(img, width, height, uploadFlip);}private getWebGL2Context(): WebGL2RenderingContext | null {