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): compression that cannot pay for its decoder is skipped

esengineed08d0b44140
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e54b34703..ac9b09698 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,14 @@ published separately; it ships inside the editor.
### Fixed
+- **A project whose art weighs less than the transcoder no longer compresses any of it.**
+ Reading a KTX2 costs a package about a megabyte of Basis transcoder, and compressing can
+ never save more than the textures themselves weigh — so a project lighter than that is
+ answered before anything is encoded. The tilemap example was compressing one tileset to
+ save 6KB and carrying 1.09MB to read it back; its WeChat main package went from 4.70MB,
+ over the platform's cap, to 3.63MB. A project that authored a KTX2 itself pays for the
+ transcoder either way, and goes on compressing.
+
- **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
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index 159437335..2c63fd489 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -18,6 +18,7 @@
* This is the reachability + manifest + staging core they all build on.
*/
import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { statSync } from 'node:fs';
import { isInsideRoot } from '../fs/pathSandbox';
import path from 'node:path';
import { scanAssetDatabase, type AssetEntry } from './assetDb';
@@ -438,10 +439,15 @@ export async function cookAssets(
/** Target platform — selects each texture's per-platform Import Settings
* override (Default when absent). No effect on audio/video/atlas. */
platform?: string;
+ /**
+ * What the package would pay to READ a KTX2 — the transcoder's bytes. A
+ * project whose whole art weighs less than that cannot come out ahead by
+ * compressing any of it, and is answered before anything is encoded.
+ */
+ textureDecoderBytes?: number;
},
): Promise<CookResult> {
const contentAddressed = opts.contentAddressed ?? false;
- const compressTextures = opts.compressTextures ?? false;
const atlasTextures = opts.atlasTextures ?? false;
const compressAudio = opts.compressAudio ?? false;
const transcodeVideo = opts.transcodeVideo ?? false;
@@ -532,6 +538,26 @@ export async function cookAssets(
// Atlas pages compress as UASTC (they aggregate many textures — no single
// per-asset setting applies); standalone textures use `textureEnc` directly so
// each honors its own format / srgb / opt-out from the importer block.
+
+ // Compressing cannot save more than the art weighs, and one KTX2 obliges the
+ // package to carry the transcoder — so art lighter than it is answered before
+ // the encoder loads. A project that authored a KTX2 pays either way.
+ const textureSources = [...reachable]
+ .map((uuid) => byUuid.get(uuid))
+ .filter((e): e is AssetEntry => e !== undefined && e.type === 'texture');
+ const authoredKtx2 = textureSources.some((e) => e.path.toLowerCase().endsWith('.ktx2'));
+ const artBytes = textureSources.reduce((n, e) => {
+ try { return n + statSync(path.join(root, e.path)).size; } catch { return n; }
+ }, 0);
+ const decoderBytes = opts.textureDecoderBytes;
+ const decoderCanPay = decoderBytes === undefined || authoredKtx2 || artBytes > decoderBytes;
+ const compressTextures = (opts.compressTextures ?? false) && decoderCanPay;
+ if ((opts.compressTextures ?? false) && !decoderCanPay) {
+ const kb = (n: number) => `${Math.round(n / 1024)}KB`;
+ warnings.push(`textures ship raw: compressing every one of them could save at most `
+ + `${kb(artBytes)}, and a package that holds a KTX2 carries a ${kb(decoderBytes!)} transcoder`);
+ }
+
let encodePng: ((png: Uint8Array) => Promise<Uint8Array>) | null = null;
let textureEnc: BasisEncoderModule | null = null;
if (compressTextures) {
diff --git a/pipeline/src/bundle/sideModuleScan.ts b/pipeline/src/bundle/sideModuleScan.ts
index 4d44f5cb6..29a78abb4 100644
--- a/pipeline/src/bundle/sideModuleScan.ts
+++ b/pipeline/src/bundle/sideModuleScan.ts
@@ -7,6 +7,7 @@
*/
import { readFile } from 'node:fs/promises';
import path from 'node:path';
+import { statSync } from 'node:fs';
import {
SIDE_MODULES, spineModuleId, getEditorType,
sceneUsesPhysics, sceneUses3DPhysics,
@@ -16,10 +17,13 @@ import {
export type { SpineVersion };
export { SIDE_MODULES, spineModuleId };
+/** The module that reads a KTX2 — named once, because two things ask about it. */
+const BASIS = 'basis';
+
/** id → the `build-tools/cli.js build -t <target>` producing its WeChat artifacts. */
export const WECHAT_MODULE_BUILD_TARGET: Record<string, string> = {
physics: 'physics-wechat',
- basis: 'basis-wechat',
+ [BASIS]: 'basis-wechat',
videodec: 'videodec-wechat',
dragonbones: 'dragonbones-wechat',
'spine:2.1': 'spine-wechat',
@@ -139,7 +143,7 @@ export async function scanSideModuleIds(input: SideModuleScanInput): Promise<Set
for (const e of input.cookEntries) {
const lower = e.path.toLowerCase();
- if (/\.ktx2(\.bin)?$/.test(lower)) ids.add('basis');
+ if (/\.ktx2(\.bin)?$/.test(lower)) ids.add(BASIS);
// Script-driven playback references cooked videos no component names.
if (/\.esv(\.bin)?$/.test(lower)) ids.add('videodec');
const editorType = getEditorType(e.sourcePath ?? e.path);
@@ -198,3 +202,19 @@ export function sideModuleFiles(
}
return { files, unknown };
}
+
+/**
+ * What a package pays to READ a KTX2 here: the transcoder's bytes, or undefined
+ * where the wasm dir has none to weigh. The cook asks whether the art it is
+ * about to encode could ever be worth that much — compressing cannot save more
+ * than the art weighs, and one KTX2 obliges the package to carry this.
+ */
+export function textureDecoderBytes(wasmDir: string): number | undefined {
+ const descriptor = SIDE_MODULES[BASIS as keyof typeof SIDE_MODULES];
+ if (!descriptor) return undefined;
+ try {
+ return statSync(path.join(wasmDir, `${descriptor.file}.wasm`)).size;
+ } catch {
+ return undefined;
+ }
+}
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 18b79446f..ab113c1df 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -67,8 +67,10 @@ import type { SizeBudget } from '../project/sizeBudget';
import { measureBuild, type BuildSizeReport } from './sizeReport';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../project/targetSupport';
-import { scanSideModuleIds, sideModuleFiles, shipsSideModule } from '../bundle/sideModuleScan';
+import { scanSideModuleIds, sideModuleFiles, shipsSideModule, textureDecoderBytes } from '../bundle/sideModuleScan';
import { MODULES, NATIVE_MODULE_REGISTRY } from '../../../tools/nativeScriptModules.js';
+
+
export type { ExportPlatform };
/**
@@ -752,7 +754,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
// for this target before anything is staged — their ids ride game.config.json, so
// the runtime can acquire them exactly like the engine's own.
const projectModules = await loadProjectModules(opts.root, platform);
- const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: payloadDir, contentAddressed: opts.contentAddressed ?? true, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo, platform });
+ const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: payloadDir, contentAddressed: opts.contentAddressed ?? true, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo, platform, textureDecoderBytes: textureDecoderBytes(opts.wasmDir) });
warnings.push(...cook.warnings);
// An asset the game reaches and the cook could not produce is a hole, not a
// note: the scene still references it and the runtime 404s at boot.
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index 59c1231c0..3d111eb92 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -45,13 +45,15 @@ import { runtimeHostEntry } from '../bundle/runtimeHosts';
import { breakdownOf, type ModuleBytes } from './bundleBreakdown';
import { esengineAlias } from '../bundle/esengineResolve';
import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';
-import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';
+import { scanSideModuleIds, sideModuleFiles, textureDecoderBytes } from '../bundle/sideModuleScan';
import { OPEN_DATA_DIR } from './miniGameExportProfile';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSystems';
import { resolveEmcc, runEmcc } from '../bundle/emccPath';
import type { MiniGameExportProfile, MiniGameVendor } from './miniGameExportProfile';
+
+
export interface ExportMiniGameResult {
ok: boolean;
platform: MiniGameVendor;
@@ -309,7 +311,7 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
progress({ phase: 'Cooking assets' });
// `platform: profile.id` — the cook reads each texture's per-platform Import
// Settings under this key, so a vendor must cook against ITS OWN overrides.
- const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo: true, platform: profile.id });
+ const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo: true, platform: profile.id, textureDecoderBytes: textureDecoderBytes(opts.wasmDir) });
warnings.push(...cook.warnings);
// 1a. Anything the packer will not upload ships as `<name>.<ext>.bin`. Scenes
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index be3706e35..dc346d536 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -690,6 +690,8 @@ export const NOTED = {
{ internal: 'the wording of a message the export already printed' },
'fix(details): the Inspector names the new reason a texture ships raw':
{ note: 'A texture that encodes larger than its source now ships as the source.' },
+ 'fix(assets): compression that cannot pay for its decoder is skipped':
+ { note: 'A project whose art weighs less than the transcoder no longer compresses any of it.' },
'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':