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(editor): asset cook — reachability + manifest + staging (REARCH_ASSETS A4)

esenginebec7b74ffc20
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.ts
new file mode 100644
index 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.ts
index 4af8c021b..0e0d463dc 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -15,6 +15,7 @@ import { listRecents, addRecent, listTemplates, createFromTemplate } from './lau
import { 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.ts
index cad4f8861..14b72ab46 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -3,6 +3,7 @@ import type { OpenedProject, WorkspaceState, DirEntry, RecentEntry, TemplateEntr
import 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.ts
new file mode 100644
index 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([]);
+ });
+});