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): upload textures right-side-up — ImageBitmap ignores UNPACK_FLIP_Y

esenginef0aa252ac0e7
diff --git a/desktop/package.json b/desktop/package.json
index 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.esscene
new file mode 100644
index 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 file
diff --git a/desktop/public/scenes/tilemap-flip.textures.json b/desktop/public/scenes/tilemap-flip.textures.json
new file mode 100644
index 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 file
diff --git a/desktop/public/scenes/tilemap-flip/atlas.png b/desktop/public/scenes/tilemap-flip/atlas.png
new file mode 100644
index 000000000..e63a3bdd1
Binary files /dev/null and b/desktop/public/scenes/tilemap-flip/atlas.png differ
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 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.ts
index 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 {