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(cache): repair legacy entries and verify release artifacts
yhh585d7a6607cc
diff --git a/build-tools/tasks/wasm.js b/build-tools/tasks/wasm.jsindex aa50a328a..fe377dd66 100644--- a/build-tools/tasks/wasm.js+++ b/build-tools/tasks/wasm.js@@ -1,8 +1,10 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport path from 'path';-import { mkdir, cp, rm, stat, readFile } from 'fs/promises';+import { mkdir, cp, rm, stat, readFile, rename } from 'fs/promises';import { existsSync } from 'fs';+import { fileURLToPath } from 'node:url';+import { randomUUID } from 'node:crypto';import config from '../build.config.js';import * as logger from '../utils/logger.js';import { runCommand, getCpuCount } from '../utils/emscripten.js';@@ -51,12 +53,17 @@ async function computeWasmHash(target, targetConfig, debug) {// changed — which is a wasm that does not match the flags it was asked for.const toolchainHash = await hashDirectory(path.join(rootDir, 'cmake'), /\.cmake$/);const configHash = await hashFiles([cmakeLists]);+ // The post-link optimizer is part of what a cached build promises. A change+ // to its transaction or optimization level must not reuse yesterday's output.+ const builderHash = await hashFiles([fileURLToPath(import.meta.url)]);const { createHash } = await import('crypto');return createHash('md5').update(sourceHash).update(configHash).update(toolchainHash)+ .update(builderHash)+ .update(JSON.stringify(config.optimization[target] ?? {})).update(flagsKey).digest('hex');}@@ -205,31 +212,33 @@ async function executeWasmBuild(target, targetConfig, { debug, clean, buildDir,await copyOutputs(buildDir, outputDir, targetConfig.outputs);}-async function optimizeWasmFiles(buildDir, outputs, optLevel = '-O2', env = undefined) {+export async function optimizeWasmFiles(buildDir, outputs, optLevel = '-O2', env = undefined) {const wasmFiles = Object.keys(outputs).filter(src => src.endsWith('.wasm'));if (wasmFiles.length === 0) return;- const warnings = [];for (const src of wasmFiles) {const wasmPath = path.join(buildDir, src);if (!existsSync(wasmPath)) continue;+ const optimizedPath = `${wasmPath}.opt-${randomUUID()}.wasm`;try {const before = (await stat(wasmPath)).size;- await runCommand('wasm-opt', [optLevel, '--enable-bulk-memory', '--enable-nontrapping-float-to-int', '--enable-simd', '-o', wasmPath, wasmPath], { silent: true, env });- const after = (await stat(wasmPath)).size;+ await runCommand('wasm-opt', [optLevel, '--enable-bulk-memory', '--enable-nontrapping-float-to-int', '--enable-simd', '-o', optimizedPath, wasmPath], { silent: true, env });+ const bytes = await readFile(optimizedPath);+ if (!WebAssembly.validate(bytes)) throw new Error('optimizer produced invalid WASM');+ const after = bytes.byteLength;+ await rename(optimizedPath, wasmPath);const reduction = ((1 - after / before) * 100).toFixed(1);logger.debug(`wasm-opt ${optLevel}: ${src} ${(before / 1024).toFixed(0)}KB → ${(after / 1024).toFixed(0)}KB (-${reduction}%)`);- } catch {- const msg = `wasm-opt failed for ${src}, skipping optimization`;- logger.warn(msg);- warnings.push(msg);+ } catch (error) {+ // Keep the original artifact intact; never label a failed release+ // stage successful or copy a partially overwritten file to the SDK.+ throw new Error(`wasm-opt ${optLevel} failed for ${src}: ${error.stderr?.trim() || error.message}`, { cause: error });+ } finally {+ await rm(optimizedPath, { force: true, maxRetries: 10, retryDelay: 50 });}}- if (warnings.length > 0) {- logger.warn(`wasm-opt completed with ${warnings.length} warning(s)`);- }}async function copyOutputs(buildDir, outputDir, outputs) {diff --git a/docs/CACHE_BUDGET_REVIEW_2026-10-13.md b/docs/CACHE_BUDGET_REVIEW_2026-10-13.mdindex 15cffaa08..497b5a6cc 100644--- a/docs/CACHE_BUDGET_REVIEW_2026-10-13.md+++ b/docs/CACHE_BUDGET_REVIEW_2026-10-13.md@@ -139,3 +139,47 @@ shared-owner case; the final rerun is recorded with the PR validation.`adb devices -l` returned no attached devices. Physical-device acceptance remainsan explicit gap; neither rendered simulation nor an eventual merged PR closes it.++## Final branch validation and draft review++The work was rebased onto engine `19f7ec25279717b874afcae87d2c5e047b458f7b`+and editor `ba95cde5127b5a6c8c24f2860f365397b20a0071` after fetching another+12 engine commits and one editor commit. Editor draft review is+[#20](https://github.com/esengine/estella-editor/pull/20); it is not merged.++Both current runtime targets were rebuilt with Emscripten 5.0.7, unchanged release+optimization flags, `BINARYEN_CORES=1`, `EMCC_DEBUG=1` (intermediate-file diagnostics)+and independent `EMCC_TEMP_DIR` directories. Earlier normal-link optimization+assertions also occurred on 5.0.7; upgrading alone is not claimed to fix them.+Standalone replay with the same optimizer flags succeeded. The final post-link+optimization is now mandatory, uses a separate temporary output, validates it and+commits it atomically instead of warning and copying an unoptimized/partial file.+Build fingerprints include this transaction and the optimization level.++The transactional optimizer has three passing regression cases: a crash after+writing output preserves the original, successful-but-invalid output is rejected,+and valid output commits without using the input file as the output destination.+Final Web and WeChat build logs are local in `output/cache-budget/build-web-latest.log`+and `build-wechat-latest.log`, with no skipped post-link optimization.++The final targeted SDK run passed **168 tests across 14 files**. Editor interaction+tests passed **3/3**, and optimizer tests passed **3/3**. The Web export/renderer+verification passed again against the rebased current runtime. Optional side+modules remain outside this targeted run; no full-engine suite pass is claimed.++Rescan now recovers a referenced legacy resource's URL/hash from its manifest+identity while retaining saves, orphan files and interrupted temporaries. A+regression proves that a repaired legacy version can later be reclaimed. Cache+writes also return unsupported when a host has adapter methods but no usable+cache storage, preventing a false stored/cached result.++The rendered verifier owns an isolated Electron user-data directory and exports+packages in an asynchronous child, keeping Electron's service startup responsive.+Profile isolation alone still failed with `ERR_FAILED (-2)`; the following run+with asynchronous export passed. The synchronous export was a possible source of+startup starvation, not a proven Electron root cause. Failed runs remain in+`minigame-final.log` and `minigame-recheck.log`; the successful current run is in+`minigame-async.log` and `output/cache-budget/render/verification.json`.+It rendered green/red/blue, released 209 B while preserving 418 B of current and+rollback resources, kept pixels identical, and restarted offline without a CDN+request. This is contract-host evidence, not physical-device acceptance.diff --git a/sdk/src/platform/base.ts b/sdk/src/platform/base.tsindex 2dab556a0..3bb2e6912 100644--- a/sdk/src/platform/base.ts+++ b/sdk/src/platform/base.ts@@ -221,7 +221,7 @@ export async function platformReadCacheFile(key: string): Promise<ArrayBuffer |export async function platformWriteCacheFile(key: string, bytes: ArrayBuffer): Promise<'stored' | 'failed' | 'unsupported'> {if (!isPlatformInitialized()) return 'unsupported';const p = getPlatform();- if (!p.writeCacheFile) return 'unsupported';+ if (!p.writeCacheFile || p.hasCacheStorage?.() === false) return 'unsupported';try {await contentCacheFor(p).write(key, bytes);return 'stored';diff --git a/sdk/src/platform/contentCache.ts b/sdk/src/platform/contentCache.tsindex c60e61ad8..d642b0cfa 100644--- a/sdk/src/platform/contentCache.ts+++ b/sdk/src/platform/contentCache.ts@@ -156,13 +156,30 @@ export class ContentCache {});}- private async scan_(): Promise<void> {+ private async scan_(repair = false): Promise<void> {const index = await this.load_();const files = await this.platform_.listCacheFiles!();const known = new Map(index.entries.map(e => [e.name, e]));index.entries = files.filter(f => f.name !== INDEX_NAME).map(f => ({ ...known.get(f.name), ...f,lastAccess: Math.max(known.get(f.name)?.lastAccess ?? 0, f.lastAccess) }));this.indexBytes_ = files.find(f => f.name === INDEX_NAME)?.size ?? 0;+ if (repair) {+ // A surviving manifest gives an old file a resource identity even+ // when its index was lost. Infer only exact URL-name matches; saves,+ // orphan files and interrupted temporaries remain unindexed/pinned.+ const referenced = new Map<string, string>();+ for (const versions of Object.values(index.owners)) for (const version of versions)+ for (const key of version.keys) referenced.set(cacheEntryName(key), key);+ for (const entry of index.entries) {+ const key = referenced.get(entry.name);+ if (entry.key || !key) continue;+ const bytes = await this.platform_.readCacheFile!(key).catch(() => null);+ if (!bytes) continue;+ entry.key = key;+ entry.hash = contentHashHex(new Uint8Array(bytes));+ entry.size = bytes.byteLength;+ }+ }}/** Explicit retention lives under its own owner, so advancing the automatic@@ -228,7 +245,7 @@ export class ContentCache {async report(rescan = false): Promise<ContentCacheReport> {if (this.capability() !== 'managed') return this.report_();return this.run_(async () => {- await this.scan_();+ await this.scan_(rescan);if (rescan) await this.save_();return this.report_();});diff --git a/sdk/tests/content-cache-budget.test.ts b/sdk/tests/content-cache-budget.test.tsindex efec4695c..cf4ca180c 100644--- a/sdk/tests/content-cache-budget.test.ts+++ b/sdk/tests/content-cache-budget.test.ts@@ -148,6 +148,17 @@ describe('disk cache budget and offline versions', () => {expect(await c.read(urls[0])).toEqual(bytes());});+ it('repairs a legacy resource from manifest references so retiring its version can reclaim it', async () => {+ const c = await cache();+ await nodeAdapter.writeCacheFile(urls[0], bytes()); // Pre-index build.+ await c.protect('game', [{ revision: 'v1', reason: 'current', keys: [urls[0]] }]);+ expect((await c.report()).entries[0].protection).toContain('unindexed');+ const repaired = await c.report(true);+ expect(repaired.entries[0]).toMatchObject({ key: urls[0], hash: expect.any(String), protection: ['game:current'] });+ await c.protect('game', [{ revision: 'v2', reason: 'current', keys: [urls[1]] }]);+ expect((await c.cleanup(0, true)).releaseBytes).toBe(8);+ });+it('distinguishes unsupported management from an empty cache', async () => {const noStorage = new ContentCache({} as PlatformAdapter);expect(await noStorage.report()).toMatchObject({ capability: 'unavailable', usedBytes: null });diff --git a/sdk/tests/content-cache.test.ts b/sdk/tests/content-cache.test.tsindex f7aa5f37b..0cb37fcb0 100644--- a/sdk/tests/content-cache.test.ts+++ b/sdk/tests/content-cache.test.ts@@ -149,6 +149,12 @@ describe('node adapter disk cache (real filesystem)', () => {});describe('cache wrappers degrade on a platform with no cache (web)', () => {+ it('does not claim storage when an adapter method exists but the host has no cache bindings', async () => {+ const write = vi.fn(async () => {});+ setPlatform(mockPlatform({ writeCacheFile: write, hasCacheStorage: () => false }));+ expect(await platformWriteCacheFile('k', new ArrayBuffer(2))).toBe('unsupported');+ expect(write).not.toHaveBeenCalled();+ });it('read returns null and write says unsupported when the adapter omits the methods', async () => {setPlatform(mockPlatform({})); // no readCacheFile / writeCacheFileexpect(await platformReadCacheFile('k')).toBeNull();diff --git a/sdk/tests/minigame-content-cache.test.ts b/sdk/tests/minigame-content-cache.test.tsindex f22260f94..9d5a927c9 100644--- a/sdk/tests/minigame-content-cache.test.ts+++ b/sdk/tests/minigame-content-cache.test.ts@@ -58,9 +58,9 @@ describe('a mini-game content cache', () => {expect(await platformWriteCacheFile(URL, new ArrayBuffer(4))).toBe('failed');});- it('reports a host with no user data directory as failed, not stored', async () => {+ it('reports a host with no user data directory as unsupported, not stored', async () => {host();- expect(await platformWriteCacheFile(URL, new ArrayBuffer(4))).toBe('failed');+ expect(await platformWriteCacheFile(URL, new ArrayBuffer(4))).toBe('unsupported');expect(await platformReadCacheFile(URL)).toBeNull();});diff --git a/tools/launchers/cache-budget-render-verify.mjs b/tools/launchers/cache-budget-render-verify.mjsindex f1bafe4ea..920077716 100644--- a/tools/launchers/cache-budget-render-verify.mjs+++ b/tools/launchers/cache-budget-render-verify.mjs@@ -5,9 +5,11 @@import { app, BrowserWindow } from 'electron';import http from 'node:http';import { mkdir, readFile, writeFile, readdir, stat, rename, unlink } from 'node:fs/promises';+import { mkdirSync } from 'node:fs';import path from 'node:path';import { createRequire } from 'node:module';-import { execFileSync } from 'node:child_process';+import { execFile } from 'node:child_process';+import { promisify } from 'node:util';import { randomUUID, createHash } from 'node:crypto';import { fileURLToPath } from 'node:url';import { HOST_PAGE } from './minigameHost.mjs';@@ -17,6 +19,11 @@ import { onRendererConsole } from '../lib/rendererConsole.mjs';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');const OUT = path.join(ROOT, 'output/cache-budget/render');const STORE = path.join(OUT, `cache-${randomUUID()}`);+// Other headless verifiers use Electron too. Sharing its default user-data+// profile can race their network-service shutdown; this run owns its profile.+const PROFILE = path.join(OUT, `profile-${randomUUID()}`);+mkdirSync(PROFILE, { recursive: true });+app.setPath('userData', PROFILE);const { WebSocketServer } = createRequire(path.join(ROOT, 'sdk/package.json'))('ws');app.commandLine.appendSwitch('enable-unsafe-swiftshader');app.commandLine.appendSwitch('disable-gpu-sandbox');@@ -65,8 +72,12 @@ app.whenReady().then(async () => {await mkdir(STORE, { recursive: true });channel = await createDebugChannelServer({ WebSocketServer, host: '127.0.0.1' });// Generate actual game packages using the current SDK and compiled wasm.- execFileSync('node', [path.join(ROOT, 'tools/cache-budget-render-fixture.mjs'), OUT, channel.urlFor('127.0.0.1')],- { cwd: ROOT, stdio: 'inherit', windowsHide: true });+ // Exporting can take seconds; keep Electron's main loop answering the+ // network/GPU service startup while the child builds these packages.+ const fixture = await promisify(execFile)('node', [path.join(ROOT, 'tools/cache-budget-render-fixture.mjs'), OUT, channel.urlFor('127.0.0.1')],+ { cwd: ROOT, windowsHide: true, maxBuffer: 8 * 1024 * 1024 });+ process.stdout.write(fixture.stdout);+ process.stderr.write(fixture.stderr);const cached = file => {const name = String(file ?? '').replace(/^\/__cache\//, '');if (!/^[A-Za-z0-9_.-]+$/.test(name) || name === '.' || name === '..') throw Error('invalid cache file');diff --git a/tools/tests/wasm-opt-atomic.test.ts b/tools/tests/wasm-opt-atomic.test.tsnew file mode 100644index 000000000..492778bfd--- /dev/null+++ b/tools/tests/wasm-opt-atomic.test.ts@@ -0,0 +1,48 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, beforeEach, expect, it, vi } from 'vitest';+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import path from 'node:path';+const mock = vi.hoisted(() => ({ run: vi.fn() }));+vi.mock('../../build-tools/utils/emscripten.js', () => ({ runCommand: mock.run, getCpuCount: () => 1 }));+import { optimizeWasmFiles } from '../../build-tools/tasks/wasm.js';+const valid = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0]);+let root: string, original: string;+beforeEach(async () => {+ root = await mkdtemp(path.join(tmpdir(), 'estella-wasm-opt-'));+ await mkdir(path.join(root, 'sdk'));+ original = path.join(root, 'sdk/engine.wasm');+ await writeFile(original, valid);+ mock.run.mockReset();+});+afterEach(async () => { await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });+const outputs = { 'sdk/engine.wasm': 'wasm/web/engine.wasm' };++it('leaves a valid linked artifact intact and fails the build when optimization crashes after writing output', async () => {+ mock.run.mockImplementation(async (_cmd, args: string[]) => {+ await writeFile(args[args.indexOf('-o') + 1], 'partial output');+ throw Error('optimizer crashed');+ });+ await expect(optimizeWasmFiles(root, outputs)).rejects.toThrow('optimizer crashed');+ expect(new Uint8Array(await readFile(original))).toEqual(valid);+ expect(await readdir(path.join(root, 'sdk'))).toEqual(['engine.wasm']);+});++it('rejects invalid output even when the optimizer exits successfully', async () => {+ mock.run.mockImplementation(async (_cmd, args: string[]) => { await writeFile(args[args.indexOf('-o') + 1], 'invalid'); });+ await expect(optimizeWasmFiles(root, outputs)).rejects.toThrow('invalid WASM');+ expect(new Uint8Array(await readFile(original))).toEqual(valid);+});++it('commits a validated optimization without making input and output the same file', async () => {+ mock.run.mockImplementation(async (_cmd, args: string[]) => {+ const output = args[args.indexOf('-o') + 1];+ expect(output).not.toBe(original);+ expect(args.at(-1)).toBe(original);+ await writeFile(output, valid);+ });+ await optimizeWasmFiles(root, outputs);+ expect(new Uint8Array(await readFile(original))).toEqual(valid);+ expect(await readdir(path.join(root, 'sdk'))).toEqual(['engine.wasm']);+});