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(assets): an asset named only inside another document is still shipped
esenginec778fe8a0262
diff --git a/desktop/tests/document-ref-cook-deps.test.ts b/desktop/tests/document-ref-cook-deps.test.tsnew file mode 100644index 000000000..868ed2c70--- /dev/null+++ b/desktop/tests/document-ref-cook-deps.test.ts@@ -0,0 +1,118 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Regression: an asset named ONLY from inside another asset's document is+ * still cooked. A baked environment names its reflection atlas and an+ * animator controller names the clips its states play; nothing in the scene+ * graph mentions either, so a type left out of the dep scan ships the+ * document and 404s what it needs — in the build only, since the editor+ * serves the whole project.+ *+ * Neither asset here is referenced by the scene as well. That is the point:+ * examples/sprite-animation happens to list its clips in the scene too, so+ * the missing controller → clip edge was invisible for as long as it existed.+ */+import { describe, it, expect, beforeAll, afterAll } from 'vitest';+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { scanAssetDatabase } from '../../pipeline/src/assets/assetDb';+import { cookAssets } from '../../pipeline/src/assets/cookAssets';++let root: string;++const SPECULAR = '11111111-1111-4111-8111-111111111111';+const ESENV = '22222222-2222-4222-8222-222222222222';+const CLIP = '33333333-3333-4333-8333-333333333333';+const CONTROLLER = '44444444-4444-4444-8444-444444444444';+const FRAME = '55555555-5555-4555-8555-555555555555';+const SCENE = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';++function writeAsset(rel: string, type: string, uuid: string, body: string | Uint8Array = ''): 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: {} }));+}++// The importer writes the atlas as a SIBLING file name, resolved against the+// document — not as a project path.+const esenv = JSON.stringify({+ version: 1, irradiance: new Array(27).fill(0), specular: 'sky_env.png',+ faceSize: 8, mipCount: 1, maxRange: 8,+});++const controller = JSON.stringify({+ parameters: [], initialState: 'Idle',+ states: [{ name: 'Idle', clip: 'assets/anim/idle.esanim', loop: true, transitions: [] }],+});++const clip = JSON.stringify({+ version: '1.2', name: 'idle', fps: 8,+ frames: [{ texture: 'assets/anim/frame0.png', duration: 1 }],+});++// The scene names the environment and the controller, and NOTHING else.+const scene = JSON.stringify({+ version: '1.0', name: 'm',+ entities: [+ {+ id: 1, name: 'Sky', parent: null, children: [],+ components: [{ type: 'Light2D', data: { type: 2, environment: 'assets/env/sky.esenv' } }],+ },+ {+ id: 2, name: 'Actor', parent: null, children: [],+ components: [{ type: 'UIController', data: { controller: 'assets/anim/player.esanimator' } }],+ },+ ],+});++beforeAll(() => {+ root = mkdtempSync(path.join(tmpdir(), 'estella-docrefs-'));+ writeAsset('assets/env/sky_env.png', 'texture', SPECULAR, 'PNG');+ writeAsset('assets/env/sky.esenv', 'environment', ESENV, esenv);+ writeAsset('assets/anim/frame0.png', 'texture', FRAME, 'PNG');+ writeAsset('assets/anim/idle.esanim', 'animclip', CLIP, clip);+ writeAsset('assets/anim/player.esanimator', 'animatorcontroller', CONTROLLER, controller);+ writeAsset('assets/scenes/main.esscene', 'scene', SCENE, scene);+});++afterAll(() => {+ if (root) rmSync(root, { recursive: true, force: true });+});++describe('assets named only inside another document are cooked', () => {+ it('links environment → its reflection atlas, resolved as a sibling', async () => {+ const { index } = await scanAssetDatabase(root, { write: false });+ expect(index.deps[ESENV]).toContain(SPECULAR);+ });++ it('links animator controller → the clip its state plays', async () => {+ const { index } = await scanAssetDatabase(root, { write: false });+ expect(index.deps[CONTROLLER]).toContain(CLIP);+ });++ it('ships both, and the clip\'s own frame through it', async () => {+ const res = await cookAssets(root, { entryScenes: ['assets/scenes/main.esscene'], outDir: 'build' });+ expect(res.ok).toBe(true);+ expect(res.included).toEqual(expect.arrayContaining([SCENE, ESENV, SPECULAR, CONTROLLER, CLIP, FRAME]));+ expect(res.unused).toEqual([]);+ });++ // Shipping the atlas is only half of it: content-addressed staging moves the+ // document away from its sibling, so a ref left as-authored resolves to nothing+ // and the reflection is silently lost. The staged copy must name the asset.+ it('rewrites the staged environment\'s sibling ref to a path the package has', async () => {+ const res = await cookAssets(root, {+ entryScenes: ['assets/scenes/main.esscene'], outDir: 'build-ca', contentAddressed: true,+ });+ expect(res.ok).toBe(true);+ const manifest = JSON.parse(readFileSync(res.manifestPath!, 'utf8')) as {+ entries: Array<{ uuid: string; path: string; sourcePath: string }>;+ };+ const env = manifest.entries.find((e) => e.uuid === ESENV)!;+ const staged = JSON.parse(readFileSync(path.join(res.outDir, env.path), 'utf8')) as { specular: string };+ expect(staged.specular).toBe('assets/env/sky_env.png');+ expect(manifest.entries.some((e) => e.sourcePath === staged.specular)).toBe(true);+ });+});diff --git a/pipeline/src/assets/assetDb.ts b/pipeline/src/assets/assetDb.tsindex 53da43234..1d2fc947d 100644--- a/pipeline/src/assets/assetDb.ts+++ b/pipeline/src/assets/assetDb.ts@@ -219,8 +219,12 @@ const SKELETAL_ATLAS_TYPES = new Set(['spine-atlas', 'dragonbones-atlas']);// refs is the ordinary way to do that — and an unscanned table means the cook// culls what only it points at, which surfaces as a missing asset in the build// and nowhere else.+// 'environment' names its reflection atlas and 'animatorcontroller' the clips its+// states play — both the skeletal-atlas shape, where the only reference lives+// inside a document, so an unscanned type 404s what the document needs.const JSON_REF_TYPES = new Set(['scene', 'prefab', 'material', 'tileset', 'tilemap', 'animclip', 'animation', 'statemachine', 'behaviortree',+ 'environment', 'animatorcontroller','json',]);diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.tsindex 4e4bac77e..c9dd3de3c 100644--- a/pipeline/src/assets/cookAssets.ts+++ b/pipeline/src/assets/cookAssets.ts@@ -166,18 +166,7 @@ function rewriteMaterialRefs(byPath: Map<string, AssetEntry>,): Uint8Array {const json = JSON.parse(Buffer.from(bytes).toString('utf8')) as Record<string, unknown>;- const dir = matPath.includes('/') ? matPath.slice(0, matPath.lastIndexOf('/')) : '';- const rewrite = (ref: unknown): unknown => {- // `builtin:<id>` shaders compile from in-code templates (no file); pass through like @uuid/URLs.- if (typeof ref !== 'string' || ref.startsWith('@uuid:') || ref.startsWith('builtin:') || ref.includes('://')) return ref;- const norm = ref.replace(/^\.\//, '').replace(/^\//, '');- if (byPath.has(norm)) return ref; // already a logical project path- const joined = dir ? `${dir}/${norm}` : norm;- if (!byPath.has(joined)) return ref; // not an asset ref (or missing) — leave it- // Passthrough-safe spelling: bare when the runtime treats it as absolute,- // "/"-rooted otherwise (both registered by the cooked host's maps).- return joined.startsWith('assets/') ? joined : `/${joined}`;- };+ const rewrite = (ref: unknown): unknown => logicalRef(ref, matPath, byPath);if (typeof json.shader === 'string') json.shader = rewrite(json.shader);if (typeof json.instanceOf === 'string') json.instanceOf = rewrite(json.instanceOf);if (json.properties && typeof json.properties === 'object') {@@ -187,6 +176,38 @@ function rewriteMaterialRefs(return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');}+/**+ * One document-relative ref as the logical project path a staged copy must carry:+ * staging is content-addressed, so the directory a relative ref resolves against+ * does not survive it. `@uuid:` / `builtin:` / URLs / already-logical refs and+ * anything naming no asset pass through.+ */+function logicalRef(ref: unknown, docPath: string, byPath: Map<string, AssetEntry>): unknown {+ if (typeof ref !== 'string' || ref.startsWith('@uuid:') || ref.startsWith('builtin:') || ref.includes('://')) return ref;+ const norm = ref.replace(/^\.\//, '').replace(/^\//, '');+ if (byPath.has(norm)) return ref;+ const proj = resolveRelativePath(docPath, ref); // collapses ./ and ../+ if (!byPath.has(proj)) return ref;+ // Passthrough-safe spelling: bare when the runtime treats it as absolute,+ // "/"-rooted otherwise (both registered by the cooked host's maps).+ return proj.startsWith('assets/') ? proj : `/${proj}`;+}++/**+ * A baked environment names its reflection atlas as a SIBLING file, which staging+ * moves out from under it — the runtime then asks for `assets/sky_env.png` and gets+ * a 404, and the frame silently loses every reflection the game was lit for.+ */+function rewriteEnvironmentRefs(+ bytes: Uint8Array,+ envPath: string,+ byPath: Map<string, AssetEntry>,+): Uint8Array {+ const json = JSON.parse(Buffer.from(bytes).toString('utf8')) as Record<string, unknown>;+ if (typeof json.specular === 'string') json.specular = logicalRef(json.specular, envPath, byPath);+ return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');+}+/*** Rewrite a Tiled map's tileset `image` (inline) and `source` (external `.tsj`) refs* from document-relative (`"../textures/tileset.png"`) to the referenced asset's logical@@ -202,12 +223,7 @@ function rewriteTilemapRefs(byPath: Map<string, AssetEntry>,): Uint8Array {const json = JSON.parse(Buffer.from(bytes).toString('utf8')) as Record<string, unknown>;- const rewrite = (ref: unknown): unknown => {- if (typeof ref !== 'string' || ref.startsWith('@uuid:') || ref.includes('://')) return ref;- const proj = resolveRelativePath(tmjPath, ref); // collapses ./ and ../- if (!byPath.has(proj)) return ref; // not an asset ref (or missing) — leave it- return proj.startsWith('assets/') ? proj : `/${proj}`;- };+ const rewrite = (ref: unknown): unknown => logicalRef(ref, tmjPath, byPath);const tilesets = Array.isArray(json.tilesets) ? (json.tilesets as Record<string, unknown>[]) : [];for (const ts of tilesets) {if (typeof ts.image === 'string') ts.image = rewrite(ts.image); // inline tileset image@@ -554,6 +570,14 @@ export async function cookAssets(warnings.push(`${entry.path}: material ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);}}+ // Environments: the sibling reflection atlas → its logical project path.+ if (ext.toLowerCase() === '.esenv') {+ try {+ data = rewriteEnvironmentRefs(data, entry.path, byPath);+ } catch (err) {+ warnings.push(`${entry.path}: environment ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);+ }+ }// Tilemaps: relative tileset image/source refs → logical project paths, so the// @uuid-loaded map resolves them to the embedded assets (see rewriteTilemapRefs).if (ext.toLowerCase() === '.tmj' || ext.toLowerCase() === '.tmx') {