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): content-addressed cook output — dedup + immutable caching (opt-in)

yhh46d5c627f8a2
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.ts
index 82d902720..679212af3 100644
--- a/desktop/electron/cookAssets.ts
+++ b/desktop/electron/cookAssets.ts
@@ -59,8 +59,9 @@ export interface CookResult {
*/
export async function cookAssets(
root: string,
- opts: { entryScenes: string[]; outDir: string },
+ opts: { entryScenes: string[]; outDir: string; contentAddressed?: boolean },
): Promise<CookResult> {
+ const contentAddressed = opts.contentAddressed ?? 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,20 +98,32 @@ export async function cookAssets(
// 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.
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;
- const dst = path.join(absOut, entry.path);
try {
const data = await readFile(path.join(root, entry.path));
- await mkdir(path.dirname(dst), { recursive: true });
- await writeFile(dst, data);
+ 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
+ // — content changes yield a new name, so it is permanently cacheable. Scenes
+ // 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 dst = path.join(absOut, outRel);
+ if (!staged.has(outRel)) {
+ await mkdir(path.dirname(dst), { recursive: true });
+ await writeFile(dst, data);
+ staged.add(outRel);
+ }
manifestEntries.push({
uuid: entry.uuid,
- path: entry.path,
+ path: outRel,
type: entry.type,
importer: entry.importer,
- contentHash: contentHashHex(data),
+ contentHash: hash,
size: data.byteLength,
});
} catch (err) {
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index 717310c89..c03e75125 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -204,6 +204,8 @@ export async function exportGame(opts: {
sdkDistDir: string;
wasmDir: string;
outDir: string;
+ /** Emit content-addressed asset filenames (<hash><ext>) for dedup + immutable caching. */
+ contentAddressed?: boolean;
title?: string;
platform?: ExportPlatform;
/** Playable host source (src/playableHost.ts). */
@@ -278,7 +280,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 });
+ const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: payloadDir, contentAddressed: opts.contentAddressed });
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 d309f90ea..03eb7579a 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -171,6 +171,8 @@ export async function exportWeChat(opts: {
/** Screen orientation (Project Settings) → game.json. */
orientation?: 'portrait' | 'landscape';
minify?: boolean;
+ /** Emit content-addressed asset filenames (<hash><ext>) for dedup + immutable caching. */
+ contentAddressed?: boolean;
onProgress?: OnExportProgress;
}): Promise<ExportWeChatResult> {
const title = opts.title ?? 'Game';
@@ -182,7 +184,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 });
+ const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: absOut, contentAddressed: opts.contentAddressed });
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 9257bfe9f..395a54f66 100644
--- a/desktop/tests/cook-assets.test.ts
+++ b/desktop/tests/cook-assets.test.ts
@@ -140,4 +140,44 @@ describe('cookAssets (A4)', () => {
rmSync(r, { recursive: true, force: true });
}
});
+
+ it('content-addresses leaf assets (<hash><ext>), dedups identical bytes, keeps scenes by name', async () => {
+ const r = mkdtempSync(path.join(tmpdir(), 'estella-cook-ca-'));
+ try {
+ const A = '33333333-3333-4333-8333-333333333333';
+ const B = '44444444-4444-4444-8444-444444444444';
+ const C = '55555555-5555-4555-8555-555555555555';
+ const SC = '66666666-6666-4666-8666-666666666666';
+ const wa = (rel: string, type: string, uuid: string, body: 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/a.png', 'texture', A, 'SAME-BYTES');
+ wa('t/b.png', 'texture', B, 'SAME-BYTES'); // byte-identical to a
+ wa('t/c.png', 'texture', C, 'OTHER-BYTES');
+ wa('s/main.esscene', 'scene', SC, JSON.stringify({
+ version: '1.0', name: 's', entities: [A, B, C].map((u, i) => ({
+ id: i + 1, name: `E${i}`, parent: null, children: [],
+ components: [{ type: 'Sprite', data: { texture: `@uuid:${u}` } }],
+ })),
+ }));
+ const res = await cookAssets(r, { entryScenes: ['s/main.esscene'], outDir: 'out', contentAddressed: true });
+ const m = JSON.parse(readFileSync(res.manifestPath!, 'utf8')) as AssetManifest;
+ const byUuid = (u: string) => m.entries.find((e) => e.uuid === u)!;
+
+ // Leaf textures are content-addressed; scene keeps its logical name.
+ expect(byUuid(A).path).toMatch(/^assets\/[0-9a-f]{16}\.png$/);
+ expect(byUuid(SC).path).toBe('s/main.esscene');
+
+ // Byte-identical leaves collapse to one path (and one staged file); distinct content does not.
+ expect(byUuid(A).path).toBe(byUuid(B).path);
+ expect(byUuid(A).path).not.toBe(byUuid(C).path);
+ expect(existsSync(path.join(res.outDir, byUuid(A).path))).toBe(true);
+ expect(existsSync(path.join(res.outDir, byUuid(C).path))).toBe(true);
+ } finally {
+ rmSync(r, { recursive: true, force: true });
+ }
+ });
});