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(assets): KTX2 bakes the engine's orientation at encode, the one place it can
esengine476444c5e8ff
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 newdiff --git a/build-tools/basis/encoder.d.mts b/build-tools/basis/encoder.d.mtsindex 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.mjsindex 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.tsindex 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 () => {