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
feat(editor): asset cook — reachability + manifest + staging (REARCH_ASSETS A4)
esenginebec7b74ffc20
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.tsnew file mode 100644index 000000000..6b950e6f4--- /dev/null+++ b/desktop/electron/cookAssets.ts@@ -0,0 +1,105 @@+/**+ * @file Asset cook (REARCH_ASSETS.md A4). Produce a shippable asset set: from+ * the entry scene(s), walk the AssetDatabase dependency graph to the+ * REACHABLE assets, copy those files into an output dir (project-relative+ * paths preserved), and emit the runtime `assets.manifest.json` (the+ * shape `AssetRegistry.loadManifest` consumes). Assets nothing references+ * are culled from the build.+ *+ * Reuses the A2 scanner (scanAssetDatabase) for the index + dep graph, so the+ * editor's resolution, the Content Browser, and the ship cook all read one+ * source of truth. Pure Node (fs), no Electron imports → unit-testable; IPC+ * wiring is in main.ts.+ *+ * Deferred (per-target work): transcode/compress per platform (web/wechat/+ * native), texture atlasing, and the full web-build (html + runtime + scripts).+ * This is the reachability + manifest + staging core they all build on.+ */+import { writeFile, mkdir, copyFile } from 'node:fs/promises';+import path from 'node:path';+import { scanAssetDatabase, type AssetEntry } from './assetDb';++const MANIFEST = 'assets.manifest.json';++export interface CookResult {+ ok: boolean;+ /** Absolute output dir the assets + manifest were staged into. */+ outDir: string;+ /** Absolute manifest path, or null if not written. */+ manifestPath: string | null;+ /** uuids included (reachable from the entry scenes). */+ included: string[];+ /** uuids present in the project but unreachable — culled from the build. */+ unused: string[];+ warnings: string[];+}++/**+ * Cook assets reachable from `entryScenes` (project-relative scene paths) into+ * `outDir` (project-relative or absolute). Returns what was included vs culled.+ */+export async function cookAssets(+ root: string,+ opts: { entryScenes: string[]; outDir: string },+): Promise<CookResult> {+ 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]));+ const warnings: string[] = [];++ // Seed reachability from the entry scenes (path → uuid)…+ const reachable = new Set<string>();+ const queue: string[] = [];+ const seed = (uuid: string): void => {+ if (!reachable.has(uuid)) {+ reachable.add(uuid);+ queue.push(uuid);+ }+ };+ for (const scenePath of opts.entryScenes) {+ const entry = byPath.get(scenePath);+ if (!entry) {+ warnings.push(`entry scene not in asset index: ${scenePath}`);+ continue;+ }+ seed(entry.uuid);+ }+ // …then take the transitive closure over the dependency graph.+ while (queue.length > 0) {+ const uuid = queue.shift()!;+ for (const dep of index.deps[uuid] ?? []) seed(dep);+ }++ const absOut = path.isAbsolute(opts.outDir) ? opts.outDir : path.join(root, opts.outDir);+ await mkdir(absOut, { recursive: true });++ // Stage each reachable asset's file + build the ship manifest.+ const manifestEntries: AssetEntry[] = [];+ for (const uuid of reachable) {+ const entry = byUuid.get(uuid);+ if (!entry) continue;+ const dst = path.join(absOut, entry.path);+ try {+ await mkdir(path.dirname(dst), { recursive: true });+ await copyFile(path.join(root, entry.path), dst);+ manifestEntries.push({+ uuid: entry.uuid,+ path: entry.path,+ type: entry.type,+ importer: entry.importer,+ });+ } catch (err) {+ warnings.push(`copy failed ${entry.path}: ${err instanceof Error ? err.message : String(err)}`);+ }+ }+ manifestEntries.sort((a, b) => a.path.localeCompare(b.path));++ const manifestPath = path.join(absOut, MANIFEST);+ await writeFile(+ manifestPath,+ JSON.stringify({ version: '1.0', entries: manifestEntries }, null, 2) + '\n',+ );++ const unused = index.entries.filter((e) => !reachable.has(e.uuid)).map((e) => e.uuid);+ return { ok: true, outDir: absOut, manifestPath, included: [...reachable], unused, warnings };+}diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 4af8c021b..0e0d463dc 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -15,6 +15,7 @@ import { listRecents, addRecent, listTemplates, createFromTemplate } from './lauimport { buildProjectScripts } from './buildScripts';import { extractProjectSchemas } from './extractSchemas';import { scanAssetDatabase } from './assetDb';+import { cookAssets } from './cookAssets';import { resolveScripts } from '../src/project/format';import type { WorkspaceState } from '../src/project/format';@@ -163,6 +164,16 @@ ipcMain.handle('project:extractSchemas', async () => {// Browser; the cook walks `deps` (REARCH_ASSETS.md A2).ipcMain.handle('project:scanAssets', async () => scanAssetDatabase(requireRoot()));+// Cook the project's assets for shipping: from the entry scene, walk the+// dependency graph to the reachable assets, stage them into `outDir`, and emit+// the runtime manifest — culling unreferenced assets (REARCH_ASSETS.md A4).+ipcMain.handle('project:cookAssets', async (_e, outDir?: string) => {+ const root = requireRoot();+ const manifest = await readManifest(root);+ const entry = manifest.defaultScene;+ return cookAssets(root, { entryScenes: entry ? [entry] : [], outDir: outDir ?? 'build' });+});+ipcMain.handle('recents:list', () => listRecents());ipcMain.handle('recents:add', (_e, root: string, name: string) => addRecent(root, name));diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.tsindex cad4f8861..14b72ab46 100644--- a/desktop/electron/preload.ts+++ b/desktop/electron/preload.ts@@ -3,6 +3,7 @@ import type { OpenedProject, WorkspaceState, DirEntry, RecentEntry, TemplateEntrimport type { BuildScriptsResult } from './buildScripts';import type { ExtractSchemasResult } from './extractSchemas';import type { ScanAssetsResult } from './assetDb';+import type { CookResult } from './cookAssets';// The privileged bridge the renderer is allowed to touch. Keep this surface small// and explicit — anything the editor needs from the OS or Node goes through here.@@ -33,6 +34,8 @@ const api = {extractSchemas: (): Promise<ExtractSchemasResult> => ipcRenderer.invoke('project:extractSchemas'),/** Scan the project's .meta sidecars → the asset index (registry + dep graph). */scanAssets: (): Promise<ScanAssetsResult> => ipcRenderer.invoke('project:scanAssets'),+ /** Cook reachable assets for shipping → staged files + runtime manifest in `outDir`. */+ cookAssets: (outDir?: string): Promise<CookResult> => ipcRenderer.invoke('project:cookAssets', outDir),},// New-project templates (launcher New tab).templates: {diff --git a/desktop/tests/cook-assets.test.ts b/desktop/tests/cook-assets.test.tsnew file mode 100644index 000000000..5a594b64a--- /dev/null+++ b/desktop/tests/cook-assets.test.ts@@ -0,0 +1,85 @@+/**+ * @file Asset cook (REARCH_ASSETS.md A4). From an entry scene, walk the+ * AssetDatabase dep graph to the reachable assets, stage them + emit the+ * runtime manifest, and cull anything unreferenced.+ */+import { describe, it, expect, beforeAll, afterAll } from 'vitest';+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { cookAssets } from '../electron/cookAssets';++interface AssetManifest {+ version: string;+ entries: Array<{ uuid: string; path: string; type: string }>;+}++let root: string;++const USED_TEX = '11111111-1111-4111-8111-111111111111';+const ORPHAN_TEX = '22222222-2222-4222-8222-222222222222';+const STRAY_TEX = '99999999-9999-4999-8999-999999999999';+const ENTRY_SCENE = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';+const ORPHAN_SCENE = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';++function writeAsset(rel: string, type: string, uuid: string, body = ''): void {+ const abs = path.join(root, rel);+ mkdirSync(path.dirname(abs), { recursive: true });+ writeFileSync(abs, body);+ writeFileSync(`${abs}.meta`, JSON.stringify({ uuid, version: '2.0', type, importer: {} }));+}++const sprite = (texUuid: string) =>+ JSON.stringify({+ version: '1.0',+ name: 's',+ entities: [+ { id: 1, name: 'S', parent: null, children: [], components: [{ type: 'Sprite', data: { texture: `@uuid:${texUuid}` } }] },+ ],+ });++beforeAll(() => {+ root = mkdtempSync(path.join(tmpdir(), 'estella-cook-'));+ writeAsset('assets/textures/used.png', 'texture', USED_TEX, 'USED');+ writeAsset('assets/textures/orphan.png', 'texture', ORPHAN_TEX, 'ORPHAN');+ writeAsset('assets/textures/stray.png', 'texture', STRAY_TEX, 'STRAY'); // referenced by nobody+ writeAsset('assets/scenes/main.esscene', 'scene', ENTRY_SCENE, sprite(USED_TEX));+ writeAsset('assets/scenes/orphan.esscene', 'scene', ORPHAN_SCENE, sprite(ORPHAN_TEX));+});++afterAll(() => {+ if (root) rmSync(root, { recursive: true, force: true });+});++describe('cookAssets (A4)', () => {+ it('includes assets reachable from the entry scene and culls the rest', async () => {+ const res = await cookAssets(root, { entryScenes: ['assets/scenes/main.esscene'], outDir: 'build' });+ expect(res.ok).toBe(true);++ // Reachable: the entry scene + its texture.+ expect(res.included.sort()).toEqual([ENTRY_SCENE, USED_TEX].sort());+ // Culled: the orphan scene, its texture, and the totally-unreferenced one.+ expect(res.unused.sort()).toEqual([ORPHAN_SCENE, ORPHAN_TEX, STRAY_TEX].sort());+ });++ it('stages reachable files + writes a runtime manifest; excludes culled files', async () => {+ const res = await cookAssets(root, { entryScenes: ['assets/scenes/main.esscene'], outDir: 'build' });++ expect(existsSync(path.join(res.outDir, 'assets/textures/used.png'))).toBe(true);+ expect(existsSync(path.join(res.outDir, 'assets/scenes/main.esscene'))).toBe(true);+ // Culled assets are not staged.+ expect(existsSync(path.join(res.outDir, 'assets/textures/orphan.png'))).toBe(false);+ expect(existsSync(path.join(res.outDir, 'assets/textures/stray.png'))).toBe(false);++ const manifest = JSON.parse(readFileSync(res.manifestPath!, 'utf8')) as AssetManifest;+ expect(manifest.version).toBe('1.0');+ const paths = manifest.entries.map((e) => e.path).sort();+ expect(paths).toEqual(['assets/scenes/main.esscene', 'assets/textures/used.png']);+ });++ it('warns when an entry scene is not a tracked asset', async () => {+ const res = await cookAssets(root, { entryScenes: ['assets/scenes/missing.esscene'], outDir: 'build' });+ expect(res.warnings.some((w) => w.includes('missing.esscene'))).toBe(true);+ expect(res.included).toEqual([]);+ });+});