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): a texture ships in whichever form is smaller
esenginea93f425da9cd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4cda6e6a0..e54b34703 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -32,6 +32,15 @@ published separately; it ships inside the editor.### Fixed+- **A texture that encodes larger than its source now ships as the source.** Compressing to+ KTX2 is a win on detailed art and a loss on flat art — Basis writes about a byte per pixel+ where PNG writes almost nothing, so the space-shooter example's 512px background came out+ 35× its PNG and its atlas page 9×. The build encodes, compares, and keeps whichever is+ smaller, the way it has always done for audio. Nothing needing a transcoder also means the+ package stops carrying one: that example's WeChat main package went from 4.83MB — over the+ platform's 4MB cap, so it could not be uploaded at all — to 3.29MB, with no project setting+ changed. The build log says how many textures it left raw and what that saved.+- **A WeChat mini-game boots again.** Its package had no platform in it: the SDK entryinstalled one as a module side effect, and the lean entry added for smaller packages ispure re-exports — so the install sat in a shared chunk the bundler was free to drop, anddiff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.tsindex a285d262c..159437335 100644--- a/pipeline/src/assets/cookAssets.ts+++ b/pipeline/src/assets/cookAssets.ts@@ -30,7 +30,7 @@ import { readTextureCookSettings } from '../project/importSettings';// The branch below IS this function — a cook that re-derived the choice would// be a second answer to the question an inspector asks before a build runs.import {- decideTextureCook, cookIntentDefeated, explainTextureCook,+ decideTextureCook, cookIntentDefeated, explainTextureCook, keepSmaller,type TextureCookDecision,} from './textureCookDecision';// Single-source content hash (sdk/src/asset/contentHash.ts). Imported as source —@@ -557,6 +557,8 @@ export async function cookAssets(// one fact about the project's source art, and one line per JPEG would bury// the per-asset findings that each need their own fix.const defeatedByFormat: string[] = [];+ /** Encoded, measured, thrown away — summarized once rather than per texture. */+ const grewUnderEncoding: Array<{ path: string; saved: number }> = [];// ---- Auto-atlas (`<name>.atlas/` folder convention) -----------------------// Pack the reachable PNGs of each atlas directory into pages BEFORE the@@ -592,13 +594,20 @@ export async function cookAssets(if (images.length === 0) continue;const pages = packAtlas(images);for (let n = 0; n < pages.length; n++) {- let pageBytes: Uint8Array = encodePagePng(pages[n]);+ const pagePng: Uint8Array = encodePagePng(pages[n]);+ let pageBytes: Uint8Array = pagePng;let pageExt = '.png';let compressedFormats: string[] | undefined;if (encodePng) {- pageBytes = await encodePng(pageBytes);- pageExt = '.ktx2';- compressedFormats = COMPRESSED_TARGETS;+ // Same question the loose textures ask, and the same answer when the+ // page is flat art: a page nobody compresses also spares the package+ // the transcoder, which is the larger half of the bill.+ const encoded = await encodePng(pagePng);+ if (encoded.byteLength < pagePng.byteLength) {+ pageBytes = encoded;+ pageExt = '.ktx2';+ compressedFormats = COMPRESSED_TARGETS;+ } else grewUnderEncoding.push({ path: `${dir}.page${n}`, saved: encoded.byteLength - pagePng.byteLength });}const pageHash = contentHashHex(pageBytes);const { name: group, delivery } = resolveAssetGroup(`${dir}/`, groupsConfig);@@ -716,11 +725,15 @@ export async function cookAssets(// when the encoder was loaded — an absent one here is a broken invariant// and should say so rather than silently ship raw.const enc = textureEnc!;- data = rgba+ const encoded = rgba? await enc.encodeToKtx2({ type: enc.ImageType.RGBA, data: rgba, width: tw, height: th }, { mode: cook.selected, srgb: tex.srgb }): await enc.encodeToKtx2({ type: enc.ImageType.PNG, data }, { mode: cook.selected, srgb: tex.srgb });- ext = '.ktx2';- compressedFormats = COMPRESSED_TARGETS;+ cook = keepSmaller(cook, encoded.byteLength, data.byteLength);+ if (cook.selected !== 'raw') {+ data = encoded;+ ext = '.ktx2';+ compressedFormats = COMPRESSED_TARGETS;+ } else grewUnderEncoding.push({ path: entry.path, saved: encoded.byteLength - data.byteLength });}}// WAV sources re-encode to MP3 (universal decode); other audio formats are@@ -906,6 +919,12 @@ export async function cookAssets(const unused = index.entries.filter((e) => !reachable.has(e.uuid)).map((e) => e.uuid);const includedPaths = [...reachable].map((uuid) => byUuid.get(uuid)?.path).filter((p): p is string => p !== undefined);+ if (grewUnderEncoding.length) {+ const bytes = grewUnderEncoding.reduce((n, g) => n + g.saved, 0);+ const kb = (n: number) => `${Math.round(n / 1024)}KB`;+ warnings.push(`${grewUnderEncoding.length} texture(s) ship raw because the KTX2 came out `+ + `larger — ${kb(bytes)} the package does not carry. Flat art compresses better as PNG.`);+ }if (defeatedByFormat.length) {const shown = defeatedByFormat.slice(0, 3).join(', ');warnings.push(`${defeatedByFormat.length} image(s) ask to be compressed but are not PNG, so they `diff --git a/pipeline/src/assets/textureCookDecision.ts b/pipeline/src/assets/textureCookDecision.tsindex 885219e27..2e9150a4a 100644--- a/pipeline/src/assets/textureCookDecision.ts+++ b/pipeline/src/assets/textureCookDecision.ts@@ -54,7 +54,9 @@ export type TextureCookReason =| 'asset-opt-out'| 'atlas-page'| 'not-block-aligned'- | 'not-raster';+ | 'not-raster'+ /** Encoded and thrown away: the KTX2 came out larger than the image. */+ | 'bigger-than-raw';export interface TextureCookDecision {/** The mode this asset asked for, or `none` when it opted out. */@@ -106,16 +108,29 @@ export function decideTextureCook(input: TextureCookInputs): TextureCookDecisionreturn { requested, selected: input.format, reason: 'compressed' };}+/**+ * The payload once the encoder has answered: a KTX2 bigger than the image it+ * encoded is not a compression, whatever it was asked for. Basis writes about a+ * byte per pixel and PNG writes almost nothing for flat art — a 512px sky came+ * out 35x its PNG, and obliged the package to carry a megabyte of transcoder.+ */+export function keepSmaller(+ d: TextureCookDecision, encodedBytes: number, rawBytes: number,+): TextureCookDecision {+ if (d.selected === 'raw' || encodedBytes < rawBytes) return d;+ return { ...d, selected: 'raw', reason: 'bigger-than-raw' };+}+/*** True when the asset asked for an encoding and the build did not give it.*- * Opting out is not a defeat, nor is a build that skips assets on purpose — both- * are choices. This catches the silent kind: a request that survived every+ * Opting out, a build that skips assets, and an encoding that came out bigger+ * are all choices. This catches the silent kind: a request that survived every* dialog and lost to the image itself, or to the folder it was dropped in.*/export function cookIntentDefeated(d: TextureCookDecision): boolean {if (d.requested === 'none') return false;- if (d.reason === 'build-skips-assets') return false;+ if (d.reason === 'build-skips-assets' || d.reason === 'bigger-than-raw') return false;return d.selected !== d.requested;}@@ -139,5 +154,7 @@ export function explainTextureCook(+ 'is not a multiple of 4, which a block-compressed texture must be';case 'not-raster':return 'shipped raw — only PNG sources are encoded';+ case 'bigger-than-raw':+ return 'shipped raw — the KTX2 came out larger than the image';}}diff --git a/pipeline/tests/cook-assets.test.ts b/pipeline/tests/cook-assets.test.tsindex 9d5eb5ab4..1283232c9 100644--- a/pipeline/tests/cook-assets.test.ts+++ b/pipeline/tests/cook-assets.test.ts@@ -13,6 +13,7 @@ import { cookAssets } from '../src/assets/cookAssets';import type { TextureCookDecision } from '../src/assets/textureCookDecision';import { decodePngImage } from '../src/assets/atlasPacker';import { contentHashHex } from '../../sdk/src/asset/contentHash';+import { noisePng } from './fixtures/solidPng.mjs';interface AssetManifest {version: string;@@ -207,7 +208,8 @@ describe('cookAssets (A4)', () => {const SC = '88888888-8888-4888-8888-888888888888';// 64x64: a block-compressed texture must be whole 4x4 blocks, so a source// that is not (logo.png is 70x70) is shipped raw by design — see below.- const png = solidPng(64, 64, [200, 60, 40, 255]);+ // Noise: a build keeps whichever came out smaller, and PNG wins on flat art.+ const png = noisePng(64, 64);const wa = (rel: string, type: string, uuid: string, body: Buffer | string): void => {const abs = path.join(r, rel);mkdirSync(path.dirname(abs), { recursive: true });@@ -326,7 +328,9 @@ describe('cookAssets (A4)', () => {try {const TEX = '77777777-7777-4777-8777-777777777773';const SC = '88888888-8888-4888-8888-888888888883';- const png = solidPng(64, 64, [200, 60, 40, 255]);+ // Noise: the platform override is the subject, so the default side has to+ // be a texture a build would really compress.+ const png = noisePng(64, 64);const abs = path.join(r, 't/logo.png');mkdirSync(path.dirname(abs), { recursive: true });writeFileSync(abs, png);diff --git a/pipeline/tests/fixtures/solidPng.d.mts b/pipeline/tests/fixtures/solidPng.d.mtsindex d8699e3c5..b79a10a62 100644--- a/pipeline/tests/fixtures/solidPng.d.mts+++ b/pipeline/tests/fixtures/solidPng.d.mts@@ -7,3 +7,4 @@ export function solidPng(height: number,rgba?: readonly [number, number, number, number],): Buffer;+export function noisePng(width: number, height: number, seed?: number): Buffer;diff --git a/pipeline/tests/fixtures/solidPng.mjs b/pipeline/tests/fixtures/solidPng.mjsindex 87e1c752d..5c7fc0742 100644--- a/pipeline/tests/fixtures/solidPng.mjs+++ b/pipeline/tests/fixtures/solidPng.mjs@@ -52,3 +52,31 @@ export function solidPng(width, height, [r, g, b, a] = [0, 0, 0, 255]) {const idat = zlib.deflateSync(raw);return Buffer.concat([sig, chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', Buffer.alloc(0))]);}++/**+ * A `width`×`height` image of deterministic noise. PNG cannot compress it, so+ * this is content a block encoder actually beats — what a fixture needs to say+ * "compression happened" now that a build keeps whichever came out smaller.+ */+export function noisePng(width, height, seed = 1) {+ const sig = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);+ const ihdr = Buffer.alloc(13);+ ihdr.writeUInt32BE(width, 0);+ ihdr.writeUInt32BE(height, 4);+ ihdr[8] = 8;+ ihdr[9] = 6;+ const rowLen = width * 4;+ const raw = Buffer.alloc((rowLen + 1) * height);+ let s = seed >>> 0;+ const next = () => { s = (s * 1664525 + 1013904223) >>> 0; return (s >>> 24) & 255; };+ for (let y = 0; y < height; y++) {+ const off = y * (rowLen + 1);+ raw[off] = 0;+ for (let x = 0; x < width; x++) {+ const p = off + 1 + x * 4;+ raw[p] = next(); raw[p + 1] = next(); raw[p + 2] = next(); raw[p + 3] = 255;+ }+ }+ return Buffer.concat([sig, chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw)),+ chunk('IEND', Buffer.alloc(0))]);+}diff --git a/pipeline/tests/texture-cook-decision.test.ts b/pipeline/tests/texture-cook-decision.test.tsindex 180d37129..afd7cb1ee 100644--- a/pipeline/tests/texture-cook-decision.test.ts+++ b/pipeline/tests/texture-cook-decision.test.ts@@ -9,7 +9,7 @@*/import { describe, it, expect } from 'vitest';import {- decideTextureCook, cookIntentDefeated, explainTextureCook,+ decideTextureCook, cookIntentDefeated, explainTextureCook, keepSmaller,type TextureCookInputs,} from '../src/assets/textureCookDecision';@@ -101,3 +101,33 @@ describe('decideTextureCook', () => {expect(said.size).toBe(6);});});++/**+ * Flat art encodes LARGER: the space-shooter background was 2,515 bytes as a PNG+ * and 87,792 as UASTC, and the transcoder the package then has to carry is a+ * megabyte more. The audio path has always kept the smaller of the two.+ */+describe('keepSmaller', () => {+ const compressed = decideTextureCook(base);++ it('keeps the encoding when it is smaller', () => {+ expect(keepSmaller(compressed, 1000, 4000)).toEqual(compressed);+ });++ it('throws the encoding away when it is not, and says so', () => {+ const d = keepSmaller(compressed, 87_792, 2_515);+ expect(d).toEqual({ requested: 'uastc', selected: 'raw', reason: 'bigger-than-raw' });+ // Not a defeat: the build chose this, the way it chooses for audio.+ expect(cookIntentDefeated(d)).toBe(false);+ expect(explainTextureCook(d)).toMatch(/larger than the image/);+ });++ it('is a no-op on a decision that was never going to encode', () => {+ const raw = decideTextureCook({ ...base, compress: false });+ expect(keepSmaller(raw, 1, 999_999)).toEqual(raw);+ });++ it('keeps raw on a tie — equal bytes buy nothing and cost a transcoder', () => {+ expect(keepSmaller(compressed, 4000, 4000).selected).toBe('raw');+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 4b9046312..57d1f2bf6 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -686,6 +686,8 @@ export const NOTED = {{ note: 'A WeChat mini-game boots again.' },'fix(sdk): the lean WeChat entry is an entry, so it declares its side effects':{ internal: 'a declaration about the package, read by bundlers rather than people' },+ 'fix(assets): a texture ships in whichever form is smaller':+ { note: 'A texture that encodes larger than its source now ships as the source.' },'fix(cli): the temp build dir is swept however the run ends':{ internal: 'a working directory of the repo\'s own tooling' },'feat(ui): a HUD can clear the host\'s own menu, not just the notch':