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.

perf(export): the cook reads back a texture encode it already did

esengine0e86cf74742e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a97077931..1182efaa9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,8 @@ published separately; it ships inside the editor.
- A connected development build says which graphics API it draws through — WebGL2, EmscriptenGLX or WebGPU — once its game has started: the Profiler shows it beside the device's controls, the Output Log notes it, and `device_targets` returns it as `graphics`. A WeChat build set to EmscriptenGLX reports WebGL2 on a host that does not offer it.
- A connected development build can be asked for the whole frame it composited — every camera and the UI over them — as the player sees it: `device_screenshot` returns it as a PNG, read back by the device's own engine. The frame debugger's replay shows one pass of a captured frame.
- Web and mini-game packages decode KTX2 textures under Zstandard supercompression, as the native host already did. UASTC textures made outside Estella usually are, and every one failed to decode; the transcoder module grows by about 21KB compressed, in packages that carry KTX2.
+- A KTX2 texture made outside Estella with a single level ships with a mip chain: the cook encodes the levels below it and keeps the file's own level 0 byte for byte, so it no longer shimmers into the distance. Bistro's 2048² textures each took about 0.3 s; the package grows by the chain's third.
+- Exporting again is fast when the art has not changed: the cook keeps what it encoded under `.esengine/cache/cook/`, keyed by the source, the settings and the encoder. Re-exporting Bistro took 24 s against 131 s the first time.
- **Export profiles.** A project can name several exports of one target in `packaging.profiles` — a test and a production WeChat build, each with its own AppID, CDN root and development or shipping configuration, writing only what differs from the project's settings. The Build dialog creates, edits and deletes them per target, marking each setting a profile overrides with a reset that hands it back to the project; `estella export --profile <name>` and the agent's `export_game` build the same one, and the size history records which profile a build used.
### Changed
@@ -29,7 +31,7 @@ published separately; it ships inside the editor.
### Fixed
-- Compressed (KTX2) textures on web and mini-games are sampled with their mip chain. The cook has always written one into every texture it compresses, and only level 0 reached the GPU: a compressed texture shimmered as it shrank into the distance, and the rest of its bytes shipped for nothing. A texture whose import settings turn mipmaps off keeps level 0 alone, and one decoded to RGBA on a device with no compressed format gets its chain generated.
+- Compressed (KTX2) textures on web and mini-games are sampled with their mip chain. The cook has always written one into every texture it compresses, and only level 0 reached the GPU: a compressed texture shimmered as it shrank into the distance, and the rest of its bytes shipped for nothing. A texture decoded to RGBA on a device with no compressed format gets its chain generated.
- The package size report on Windows attributes the SDK's bytes to the directories they come from again: every module read as "project", since the source map's paths were spelled with backslashes.
- A WeChat package registers every engine component and the built-in AI names again. The WeChat entries lost their start-up calls to the bundler, so a scene using a component with no typed definition — a rigged model's MeshSkin among them — loaded without it ("Unknown component type") and its character was never skinned.
- Reading a component whose field is a list of entities — a node's Children, a skin's joints — returns an array from every read path and frees the engine's copy. `world.tryGet` and query iteration handed back the engine's vector: an animated rig leaked one per joint per frame, and on the WeChat EmscriptenGLX engine, whose vectors cannot be iterated, the animator threw every frame.
diff --git a/build-tools/basis/encoder.d.mts b/build-tools/basis/encoder.d.mts
index 481c63fdf..bf4df632b 100644
--- a/build-tools/basis/encoder.d.mts
+++ b/build-tools/basis/encoder.d.mts
@@ -25,8 +25,14 @@ export interface EncodeOptions {
/** Flip rows before encoding (default true — the engine samples bottom-up
* memory, and compressed blocks cannot be flipped at upload). */
yFlip?: boolean;
+ /** zstd over UASTC levels (default false; the runtime reads either). */
+ supercompress?: boolean;
+ /** UASTC effort, 0 (fastest) … 4 (slowest); the encoder's default when absent. */
+ uastcLevel?: number;
}
+export const ENCODER_WASM: string;
+
export interface RgbaResult {
width: number;
height: number;
diff --git a/build-tools/basis/encoder.mjs b/build-tools/basis/encoder.mjs
index 968c67ac7..6203c82a5 100644
--- a/build-tools/basis/encoder.mjs
+++ b/build-tools/basis/encoder.mjs
@@ -13,6 +13,9 @@ import path from 'node:path';
const require = createRequire(import.meta.url);
const DIR = path.dirname(fileURLToPath(import.meta.url));
+/** The encoder binary; what an encode cache keys "which encoder" by. */
+export const ENCODER_WASM = path.join(DIR, 'basis_encoder.wasm');
+
/** The wasm module is heavy to instantiate (~MBs); load + init it once. */
let modulePromise = null;
function loadModule() {
@@ -35,23 +38,15 @@ function pngDimensions(png) {
export const ImageType = { PNG: 'png', JPG: 'jpg', RGBA: 'rgba' };
/**
- * Encode a source image to a KTX2 container.
- * source: { type: ImageType, data: Uint8Array, width?, height? }
- * width/height are read from the PNG header when omitted; required for RGBA.
- * opts: { mode: 'uastc'|'etc1s', mipmaps, srgb, perceptual, quality, normalMap, yFlip }
- * Returns the KTX2 bytes (Uint8Array).
- *
- * yFlip defaults ON because the engine samples bottom-up memory: every
- * uncompressed upload is row-flipped at load (GL UNPACK_FLIP_Y, and the WebGPU
- * device's CPU flip that emulates it), but compressed blocks cannot be — a 4x4
- * block has no valid row order to swap at upload. So the orientation must be
- * baked here, before encoding, or the texture renders vertically mirrored on
- * every backend.
+ * Encode a source image to KTX2 bytes; `source` and `opts` are typed in encoder.d.mts.
+ * yFlip defaults on: uncompressed uploads are row-flipped at load, compressed
+ * blocks cannot be, so the orientation is baked in here or the texture mirrors.
*/
export async function encodeToKtx2(source, opts = {}) {
const {
mode = 'uastc', mipmaps = true, srgb = true,
- perceptual = true, quality = 128, normalMap = false, yFlip = true,
+ perceptual = true, quality = 128, normalMap = false, yFlip = true, supercompress = false,
+ uastcLevel,
} = opts;
const m = await loadModule();
@@ -72,13 +67,14 @@ export async function encodeToKtx2(source, opts = {}) {
const enc = new m.BasisEncoder();
try {
enc.setCreateKTX2File(true);
- enc.setKTX2UASTCSupercompression(false); // runtime transcoder is zstd=0
+ enc.setKTX2UASTCSupercompression(supercompress);
enc.setKTX2AndBasisSRGBTransferFunc(srgb);
if (!enc.setSliceSourceImage(0, source.data, width, height, imgType)) {
throw new Error('encodeToKtx2: setSliceSourceImage failed (corrupt/unsupported source)');
}
if (mode === 'uastc') {
enc.setUASTC(true);
+ if (uastcLevel !== undefined) enc.setPackUASTCFlags(uastcLevel);
} else {
enc.setUASTC(false);
enc.setQualityLevel(quality);
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index 9738c93dd..21ae0c6ba 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -44,6 +44,7 @@ import { isBuiltinAssetRef, resolveRelativePath, resolveDocumentRef } from '../.
// realm (sdk/src/asset/assetGroups.ts) so cook and editor never disagree.
import { resolveAssetGroup, resolveAtlas, type AssetGroupsConfig } from '../../../sdk/src/asset/assetGroups';
import type { BundleMode } from '../../../sdk/src/asset/AddressableManifest';
+import { cookCached, encoderIdentity } from './cookCache';
const MANIFEST = 'assets.manifest.json';
@@ -211,11 +212,17 @@ interface BasisEncoderModule {
encodePngToKtx2(png: Uint8Array, opts?: { mode?: string; srgb?: boolean }): Promise<Uint8Array>;
encodeToKtx2(
source: { type: string; data: Uint8Array; width?: number; height?: number },
- opts?: { mode?: string; srgb?: boolean },
+ opts?: {
+ mode?: string; srgb?: boolean; mipmaps?: boolean; yFlip?: boolean;
+ supercompress?: boolean; uastcLevel?: number;
+ },
): Promise<Uint8Array>;
+ transcodeKtx2ToRgba(ktx2: Uint8Array): Promise<{ width: number; height: number; pixels: Uint8Array }>;
ImageType: { PNG: string; JPG: string; RGBA: string };
+ ENCODER_WASM: string;
}
+
/** 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);
@@ -563,9 +570,11 @@ export async function cookAssets(
let encodePng: ((png: Uint8Array) => Promise<Uint8Array>) | null = null;
let textureEnc: BasisEncoderModule | null = null;
+ let encoderId = '';
if (compressTextures) {
textureEnc = await import('../../../build-tools/basis/encoder.mjs') as unknown as BasisEncoderModule;
encodePng = (png) => textureEnc!.encodePngToKtx2(png, { mode: 'uastc' });
+ encoderId = encoderIdentity(textureEnc.ENCODER_WASM);
}
// WAV → MP3 (LAME wasm) rides the same lazy pattern; per-asset importer
// settings can opt a clip out (seamless loops) or pick a bitrate.
@@ -754,9 +763,14 @@ 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!;
- 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 });
+ const mode = cook.selected;
+ const source = data;
+ const encoded = (await cookCached(root,
+ [source, JSON.stringify({ mode, srgb: tex.srgb, maxSize: tex.maxSize, scaled: rgba ? [tw, th] : null }), encoderId],
+ () => (rgba
+ ? enc.encodeToKtx2({ type: enc.ImageType.RGBA, data: rgba, width: tw, height: th }, { mode, srgb: tex.srgb })
+ : enc.encodeToKtx2({ type: enc.ImageType.PNG, data: source }, { mode, srgb: tex.srgb })),
+ )).bytes;
cook = keepSmaller(cook, encoded.byteLength, data.byteLength);
if (cook.selected !== 'raw') {
data = encoded;
diff --git a/pipeline/src/assets/cookCache.ts b/pipeline/src/assets/cookCache.ts
new file mode 100644
index 000000000..8eef0b009
--- /dev/null
+++ b/pipeline/src/assets/cookCache.ts
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cookCache.ts — an encode the cook already did, read back instead of redone.
+ *
+ * Texture encoding is the cook's dearest step (seconds per large texture), and
+ * its output depends only on the source bytes, the settings and the encoder.
+ * So the output is kept under `.esengine/cache/cook/`, named by a hash of those,
+ * and a later export of unchanged art costs a file read.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const CACHE_DIR = '.esengine/cache/cook';
+
+/** Part of every key: an encode by a different encoder is a different result. */
+export function encoderIdentity(encoderFile: string): string {
+ try {
+ const st = statSync(encoderFile);
+ return createHash('sha256').update(readFileSync(encoderFile)).digest('hex').slice(0, 16) + `:${st.size}`;
+ } catch {
+ return 'unknown-encoder';
+ }
+}
+
+/**
+ * The bytes `produce` makes for these inputs, from the cache when an earlier
+ * cook made them. A cache that cannot be written is only slower, never wrong.
+ */
+export async function cookCached(
+ root: string, inputs: ReadonlyArray<Uint8Array | string>, produce: () => Promise<Uint8Array>,
+): Promise<{ bytes: Uint8Array; hit: boolean }> {
+ const h = createHash('sha256');
+ for (const part of inputs) {
+ h.update(typeof part === 'string' ? `s${part.length}:${part}` : `b${part.byteLength}:`);
+ if (typeof part !== 'string') h.update(part);
+ }
+ const file = path.join(root, CACHE_DIR, `${h.digest('hex')}.bin`);
+ if (existsSync(file)) return { bytes: new Uint8Array(await readFile(file)), hit: true };
+ const bytes = await produce();
+ try {
+ await mkdir(path.dirname(file), { recursive: true });
+ const tmp = `${file}.${process.pid}.tmp`;
+ await writeFile(tmp, bytes);
+ await rename(tmp, file);
+ } catch { /* a read-only project cooks every time */ }
+ return { bytes, hit: false };
+}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index ae78965a4..04c1680a1 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1213,5 +1213,9 @@ export const NOTED = {
'test(launch): the launchers print every warning and error, and count a logged error':
{ internal: 'Repository launchers; no creator runs them.' },
'fix(render): a compressed texture is sampled with the mip chain it carries':
- { note: 'Compressed (KTX2) textures on web and mini-games are sampled with their mip chain. The cook has always written one into every texture it compresses, and only level 0 reached the GPU: a compressed texture shimmered as it shrank into the distance, and the rest of its bytes shipped for nothing. A texture whose import settings turn mipmaps off keeps level 0 alone, and one decoded to RGBA on a device with no compressed format gets its chain generated.' },
+ { note: 'Compressed (KTX2) textures on web and mini-games are sampled with their mip chain. The cook has always written one into every texture it compresses, and only level 0 reached the GPU: a compressed texture shimmered as it shrank into the distance, and the rest of its bytes shipped for nothing. A texture decoded to RGBA on a device with no compressed format gets its chain generated.' },
+ 'feat(export): an authored single-level KTX2 ships with a mip chain':
+ { note: 'A KTX2 texture made outside Estella with a single level ships with a mip chain: the cook encodes the levels below it and keeps the file\'s own level 0 byte for byte, so it no longer shimmers into the distance. Bistro\'s 2048² textures each took about 0.3 s; the package grows by the chain\'s third.' },
+ 'perf(export): the cook reads back a texture encode it already did':
+ { note: 'Exporting again is fast when the art has not changed: the cook keeps what it encoded under `.esengine/cache/cook/`, keyed by the source, the settings and the encoder. Re-exporting Bistro took 24 s against 131 s the first time.' },
};