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.

feat(assets): cook auto-encodes PNG → KTX2 (opt-in) — completes the compressed pipeline

yhhfb1eac26d105
diff --git a/build-tools/basis/encoder.d.mts b/build-tools/basis/encoder.d.mts
new file mode 100644
index 000000000..d109f5533
--- /dev/null
+++ b/build-tools/basis/encoder.d.mts
@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+// Types for encoder.mjs so TS consumers (the asset cook) import it with full typing.
+
+export type ImageTypeValue = 'png' | 'jpg' | 'rgba';
+export const ImageType: { readonly PNG: 'png'; readonly JPG: 'jpg'; readonly RGBA: 'rgba' };
+
+export interface EncodeSource {
+ type: ImageTypeValue;
+ data: Uint8Array;
+ /** Required for RGBA sources; read from the header for PNG. */
+ width?: number;
+ height?: number;
+}
+
+export interface EncodeOptions {
+ /** 'uastc' = high quality / universal (default); 'etc1s' = smaller. */
+ mode?: 'uastc' | 'etc1s';
+ mipmaps?: boolean;
+ srgb?: boolean;
+ perceptual?: boolean;
+ /** ETC1S quality 1..255. */
+ quality?: number;
+ normalMap?: boolean;
+}
+
+export interface RgbaResult {
+ width: number;
+ height: number;
+ pixels: Uint8Array;
+}
+
+export function encodeToKtx2(source: EncodeSource, opts?: EncodeOptions): Promise<Uint8Array>;
+export function encodePngToKtx2(png: Uint8Array, opts?: EncodeOptions): Promise<Uint8Array>;
+export function transcodeKtx2ToRgba(ktx2: Uint8Array): Promise<RgbaResult>;
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.ts
index 679212af3..2892c3516 100644
--- a/desktop/electron/cookAssets.ts
+++ b/desktop/electron/cookAssets.ts
@@ -38,6 +38,17 @@ export interface CookManifestEntry extends AssetEntry {
contentHash: string;
/** Staged byte length. */
size: number;
+ /** GPU formats the staged KTX2 can transcode to, when the asset was compressed. */
+ compressedFormats?: string[];
+}
+
+/** Targets the UASTC KTX2 the cook emits can transcode to at runtime. */
+const COMPRESSED_TARGETS = ['astc-4x4', 'etc2-rgba8', 's3tc-dxt5'];
+
+/** Replace a path's extension (e.g. .png → .ktx2); appends if it had none. */
+function swapExt(p: string, ext: string): string {
+ const cur = path.extname(p);
+ return (cur ? p.slice(0, p.length - cur.length) : p) + ext;
}
export interface CookResult {
@@ -59,9 +70,10 @@ export interface CookResult {
*/
export async function cookAssets(
root: string,
- opts: { entryScenes: string[]; outDir: string; contentAddressed?: boolean },
+ opts: { entryScenes: string[]; outDir: string; contentAddressed?: boolean; compressTextures?: boolean },
): Promise<CookResult> {
const contentAddressed = opts.contentAddressed ?? false;
+ const compressTextures = opts.compressTextures ?? false;
const { index } = await scanAssetDatabase(root, { write: false });
const byUuid = new Map(index.entries.map((e) => [e.uuid, e]));
const byPath = new Map(index.entries.map((e) => [e.path, e]));
@@ -97,13 +109,32 @@ export async function cookAssets(
// bytes (rather than copyFile) so we can content-hash exactly what ships — the
// asset's physical identity. Once textures are encoded this naturally hashes the
// ENCODED artifact (e.g. the .ktx2), since it hashes whatever bytes we stage.
+ // Load the KTX2 encoder lazily (only when compressing — it pulls a ~MB wasm) and
+ // by dynamic import, so the Electron-main bundle keeps it external rather than
+ // inlining a module that resolves its wasm via import.meta.url.
+ let encodePng: ((png: Uint8Array) => Promise<Uint8Array>) | null = null;
+ if (compressTextures) {
+ const enc = await import('../../build-tools/basis/encoder.mjs');
+ encodePng = (png) => enc.encodePngToKtx2(png, { mode: 'uastc' });
+ }
+
const manifestEntries: CookManifestEntry[] = [];
const staged = new Set<string>(); // staged output paths, for content-addressed dedup
for (const uuid of reachable) {
const entry = byUuid.get(uuid);
if (!entry) continue;
try {
- const data = await readFile(path.join(root, entry.path));
+ let data: Uint8Array = await readFile(path.join(root, entry.path));
+ let ext = path.extname(entry.path);
+ let compressedFormats: string[] | undefined;
+ // Encode raster textures (PNG) to GPU-compressed KTX2 — they stay compressed
+ // in VRAM, the runtime transcodes per device. Hash + name reflect the ENCODED
+ // bytes, so this composes with content-addressing below.
+ if (encodePng && entry.type !== 'scene' && ext.toLowerCase() === '.png') {
+ data = await encodePng(data);
+ ext = '.ktx2';
+ compressedFormats = COMPRESSED_TARGETS;
+ }
const hash = contentHashHex(data);
// Content-addressed naming: leaf assets ship as assets/<hash><ext>, so
// byte-identical assets collapse to one file (dedup) and the URL is immutable
@@ -111,7 +142,7 @@ export async function cookAssets(
// keep their logical path: they're loaded by name and the exporters read +
// transform them in place. Refs are by uuid, so renaming leaves is transparent.
const useCA = contentAddressed && entry.type !== 'scene';
- const outRel = useCA ? `assets/${hash}${path.extname(entry.path)}` : entry.path;
+ const outRel = useCA ? `assets/${hash}${ext}` : swapExt(entry.path, ext);
const dst = path.join(absOut, outRel);
if (!staged.has(outRel)) {
await mkdir(path.dirname(dst), { recursive: true });
@@ -125,6 +156,7 @@ export async function cookAssets(
importer: entry.importer,
contentHash: hash,
size: data.byteLength,
+ ...(compressedFormats ? { compressedFormats } : {}),
});
} catch (err) {
warnings.push(`copy failed ${entry.path}: ${err instanceof Error ? err.message : String(err)}`);
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index c03e75125..3657fe452 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -206,6 +206,8 @@ export async function exportGame(opts: {
outDir: string;
/** Emit content-addressed asset filenames (<hash><ext>) for dedup + immutable caching. */
contentAddressed?: boolean;
+ /** Encode raster textures to GPU-compressed KTX2 at cook time. */
+ compressTextures?: boolean;
title?: string;
platform?: ExportPlatform;
/** Playable host source (src/playableHost.ts). */
@@ -280,7 +282,7 @@ export async function exportGame(opts: {
// 1. Cook reachable assets + manifest (the entry scene file is staged too).
progress({ phase: 'Cooking assets' });
- const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: payloadDir, contentAddressed: opts.contentAddressed });
+ const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: payloadDir, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures });
warnings.push(...cook.warnings);
progress({ phase: 'Cooking assets', detail: `${cook.included.length} reachable` });
diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.ts
index 03eb7579a..4dc090d30 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -173,6 +173,8 @@ export async function exportWeChat(opts: {
minify?: boolean;
/** Emit content-addressed asset filenames (<hash><ext>) for dedup + immutable caching. */
contentAddressed?: boolean;
+ /** Encode raster textures to GPU-compressed KTX2 at cook time. */
+ compressTextures?: boolean;
onProgress?: OnExportProgress;
}): Promise<ExportWeChatResult> {
const title = opts.title ?? 'Game';
@@ -184,7 +186,7 @@ export async function exportWeChat(opts: {
// 1. Cook reachable assets (paths preserved) + the flat manifest.
progress({ phase: 'Cooking assets' });
- const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: absOut, contentAddressed: opts.contentAddressed });
+ const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures });
warnings.push(...cook.warnings);
// 1b. Scan the scene for the optional modules it needs (physics/spine), so the
diff --git a/desktop/tests/cook-assets.test.ts b/desktop/tests/cook-assets.test.ts
index 395a54f66..93190cdcf 100644
--- a/desktop/tests/cook-assets.test.ts
+++ b/desktop/tests/cook-assets.test.ts
@@ -14,7 +14,7 @@ import { contentHashHex } from '../../sdk/src/asset/contentHash';
interface AssetManifest {
version: string;
- entries: Array<{ uuid: string; path: string; type: string; contentHash?: string; size?: number }>;
+ entries: Array<{ uuid: string; path: string; type: string; contentHash?: string; size?: number; compressedFormats?: string[] }>;
}
let root: string;
@@ -180,4 +180,37 @@ describe('cookAssets (A4)', () => {
rmSync(r, { recursive: true, force: true });
}
});
+
+ it('compresses raster textures to KTX2 (compressTextures) + records compressedFormats', async () => {
+ const r = mkdtempSync(path.join(tmpdir(), 'estella-cook-ktx2-'));
+ try {
+ const TEX = '77777777-7777-4777-8777-777777777777';
+ const SC = '88888888-8888-4888-8888-888888888888';
+ const png = readFileSync(path.resolve(__dirname, '../../examples/hello-world/assets/textures/logo.png'));
+ const wa = (rel: string, type: string, uuid: string, body: Buffer | string): void => {
+ const abs = path.join(r, rel);
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, body);
+ writeFileSync(`${abs}.meta`, JSON.stringify({ uuid, version: '2.0', type, importer: {} }));
+ };
+ wa('t/logo.png', 'texture', TEX, png);
+ wa('s/main.esscene', 'scene', SC, JSON.stringify({
+ version: '1.0', name: 's', entities: [
+ { id: 1, name: 'E', parent: null, children: [], components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] },
+ ],
+ }));
+ const res = await cookAssets(r, { entryScenes: ['s/main.esscene'], outDir: 'out', compressTextures: true });
+ const m = JSON.parse(readFileSync(res.manifestPath!, 'utf8')) as AssetManifest;
+ const tex = m.entries.find((e) => e.uuid === TEX)!;
+
+ // The PNG was encoded to KTX2: extension, compressedFormats, and a valid container.
+ expect(tex.path).toMatch(/\.ktx2$/);
+ expect(tex.compressedFormats).toEqual(['astc-4x4', 'etc2-rgba8', 's3tc-dxt5']);
+ const bytes = readFileSync(path.join(res.outDir, tex.path));
+ const magic = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];
+ expect(magic.every((b, i) => bytes[i] === b)).toBe(true);
+ } finally {
+ rmSync(r, { recursive: true, force: true });
+ }
+ }, 30_000);
});
diff --git a/desktop/vite.config.ts b/desktop/vite.config.ts
index 4b708944d..12682cf67 100644
--- a/desktop/vite.config.ts
+++ b/desktop/vite.config.ts
@@ -43,7 +43,10 @@ export default defineConfig({
// exportGame run it). Keep it external → required from node_modules at
// runtime where its binary resolution works. (Vite 8 = Rolldown, so the
// option is `rolldownOptions`, not `rollupOptions`.)
- vite: { build: { rolldownOptions: { external: ['esbuild'] } } },
+ // esbuild + the vendored Basis KTX2 encoder both resolve sibling binaries
+ // at runtime (native exe / wasm via import.meta.url), so bundling them
+ // breaks that — keep them external, loaded from disk by the cook.
+ vite: { build: { rolldownOptions: { external: ['esbuild', /[\\/]build-tools[\\/]basis[\\/]/] } } },
},
preload: {
input: 'electron/preload.ts',