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): a texture ships in whichever form is smaller

esenginea93f425da9cd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 entry
installed one as a module side effect, and the lean entry added for smaller packages is
pure re-exports — so the install sat in a shared chunk the bundler was free to drop, and
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index 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.ts
index 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): TextureCookDecision
return { 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.ts
index 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.mts
index 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.mjs
index 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.ts
index 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.mjs
index 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':