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): KTX2 bakes the engine's orientation at encode, the one place it can

esengine476444c5e8ff
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ea92f9c4c..7925e5418 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,17 @@ published separately; it ships inside the editor.
### Fixed
+- **Compressed textures are no longer upside down.** Every uncompressed image is
+ row-flipped at upload into the engine's texture orientation; a compressed KTX2
+ cannot be — a 4x4 block has no row order to swap — so the cook's KTX2 came out
+ vertically mirrored on every backend that drew it. It went unnoticed because
+ everything that verified the path was symmetric: a solid green square looks the
+ same both ways, and the photograph that would have shown it was only ever looked
+ at on an iOS simulator, where it was filed as a native quirk. The orientation is
+ baked at encode now, where flipping is free and exact, and a test holds the
+ stored row order to the engine's — native and web draw the same file the same
+ way up.
+
- **Coming back to a running game no longer kills it, sometimes.** On Android,
recreating the activity — leave with Back and reopen, rotate, toggle dark mode —
keeps the process and the booted engine but hands every later JS call to a new
diff --git a/build-tools/basis/encoder.d.mts b/build-tools/basis/encoder.d.mts
index d109f5533..481c63fdf 100644
--- a/build-tools/basis/encoder.d.mts
+++ b/build-tools/basis/encoder.d.mts
@@ -22,6 +22,9 @@ export interface EncodeOptions {
/** ETC1S quality 1..255. */
quality?: number;
normalMap?: boolean;
+ /** Flip rows before encoding (default true — the engine samples bottom-up
+ * memory, and compressed blocks cannot be flipped at upload). */
+ yFlip?: boolean;
}
export interface RgbaResult {
diff --git a/build-tools/basis/encoder.mjs b/build-tools/basis/encoder.mjs
index f656b30a6..7d27cc9a3 100644
--- a/build-tools/basis/encoder.mjs
+++ b/build-tools/basis/encoder.mjs
@@ -44,13 +44,20 @@ export const ImageType = { PNG: 'png', JPG: 'jpg', RGBA: 'rgba' };
* Encode a source image to a KTX2 container.
* source: { type: ImageType, data: Uint8Array, width?, height? }
* width/height are read from the PNG header when omitted; required for RGBA.
- * opts: { mode: 'uastc'|'etc1s', mipmaps, srgb, perceptual, quality, normalMap }
+ * opts: { mode: 'uastc'|'etc1s', mipmaps, srgb, perceptual, quality, normalMap, yFlip }
* Returns the KTX2 bytes (Uint8Array).
+ *
+ * yFlip defaults ON because the engine samples bottom-up memory: every
+ * uncompressed upload is row-flipped at load (GL UNPACK_FLIP_Y, and the WebGPU
+ * device's CPU flip that emulates it), but compressed blocks cannot be — a 4x4
+ * block has no valid row order to swap at upload. So the orientation must be
+ * baked here, before encoding, or the texture renders vertically mirrored on
+ * every backend.
*/
export async function encodeToKtx2(source, opts = {}) {
const {
mode = 'uastc', mipmaps = true, srgb = true,
- perceptual = true, quality = 128, normalMap = false,
+ perceptual = true, quality = 128, normalMap = false, yFlip = true,
} = opts;
const m = await loadModule();
@@ -84,6 +91,7 @@ export async function encodeToKtx2(source, opts = {}) {
}
enc.setPerceptual(perceptual);
enc.setMipGen(mipmaps);
+ enc.setYFlip(yFlip);
if (normalMap) enc.setNormalMap();
// RGBA8 is a safe upper bound for UASTC (1 B/px) + mips (~+1/3) + container.
diff --git a/desktop/tests/ktx2-encode.test.ts b/desktop/tests/ktx2-encode.test.ts
index c87b6e298..dab068a34 100644
--- a/desktop/tests/ktx2-encode.test.ts
+++ b/desktop/tests/ktx2-encode.test.ts
@@ -39,6 +39,16 @@ function gradient(size = 64): Uint8Array {
return px;
}
+/** Vertically mirror an RGBA buffer, row by row. */
+function flipRows(px: Uint8Array, width: number, height: number): Uint8Array {
+ const out = new Uint8Array(px.length);
+ const stride = width * 4;
+ for (let y = 0; y < height; y++) {
+ out.set(px.subarray(y * stride, (y + 1) * stride), (height - 1 - y) * stride);
+ }
+ return out;
+}
+
describe('basis KTX2 encoder', () => {
it('encodes raw RGBA → valid KTX2 and round-trips at high PSNR', async () => {
const size = 64;
@@ -54,8 +64,39 @@ describe('basis KTX2 encoder', () => {
expect(back.width).toBe(size);
expect(back.height).toBe(size);
expect(back.pixels.length).toBe(size * size * 4);
- // UASTC on a smooth gradient is near-lossless.
- expect(psnr(src, back.pixels)).toBeGreaterThan(40);
+ // UASTC on a smooth gradient is near-lossless. The payload is stored
+ // bottom-up (the engine's texture memory order), so the round-trip
+ // matches the row-flipped source.
+ expect(psnr(flipRows(src, size, size), back.pixels)).toBeGreaterThan(40);
+ }, 30_000);
+
+ it('stores rows bottom-up: the engine orientation compressed blocks cannot get at upload', async () => {
+ // Top half red, bottom half blue — unambiguous under any codec loss.
+ const size = 16;
+ const src = new Uint8Array(size * size * 4);
+ for (let y = 0; y < size; y++) {
+ for (let x = 0; x < size; x++) {
+ const o = (y * size + x) * 4;
+ src[o] = y < size / 2 ? 255 : 0;
+ src[o + 2] = y < size / 2 ? 0 : 255;
+ src[o + 3] = 255;
+ }
+ }
+ const ktx2 = await encodeToKtx2(
+ { type: ImageType.RGBA, data: src, width: size, height: size },
+ { mode: 'uastc', mipmaps: false },
+ );
+ const back = await transcodeKtx2ToRgba(ktx2);
+ // First stored row is the source's BOTTOM row (blue).
+ expect(back.pixels[2]).toBeGreaterThan(200);
+ expect(back.pixels[0]).toBeLessThan(50);
+ // yFlip: false preserves the source order (top row red).
+ const raw = await transcodeKtx2ToRgba(await encodeToKtx2(
+ { type: ImageType.RGBA, data: src, width: size, height: size },
+ { mode: 'uastc', mipmaps: false, yFlip: false },
+ ));
+ expect(raw.pixels[0]).toBeGreaterThan(200);
+ expect(raw.pixels[2]).toBeLessThan(50);
}, 30_000);
it('encodes a real PNG asset → valid KTX2 with matching dimensions', async () => {