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.

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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') {