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): compression that cannot pay for its decoder is skipped
esengineed08d0b44140
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 toKTX2 is a win on detailed art and a loss on flat art — Basis writes about a byte per pixelwhere PNG writes almost nothing, so the space-shooter example's 512px background came outdiff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.tsindex 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.tsindex 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<Setfor (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.tsindex 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.tsindex 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`. Scenesdiff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 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':