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(cook): embed + rewrite a tilemap's tileset images for playables

yhh7d2ab744b651
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.ts
index 6961b323f..b19ba3bcb 100644
--- a/desktop/electron/assetDb.ts
+++ b/desktop/electron/assetDb.ts
@@ -19,6 +19,9 @@
import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
import path from 'node:path';
import { META_EXT, isContentDir } from './contentPolicy';
+// The runtime's tileset-path resolver (a dependency-free leaf) — shared so the dep scan
+// discovers a tilemap's tileset images the same way the loader will later request them.
+import { resolveRelativePath } from '../../sdk/src/tilemap/tiledPath';
/** Local, gitignored cache inside the project (next to workspace.json). */
const CACHE_DIR = '.esengine/cache';
@@ -75,10 +78,11 @@ async function* walkMeta(root: string, rel = ''): AsyncGenerator<string> {
/**
* Asset types whose JSON documents can reference other assets — these are
* dependency-scanned so the cook's reachability closure includes what they
- * pull in (a material's shader + textures, a tileset's atlas, …).
+ * pull in (a material's shader + textures, a tileset's atlas, a tilemap's tileset
+ * images, …).
*/
const JSON_REF_TYPES = new Set([
- 'scene', 'prefab', 'material', 'tileset', 'animclip', 'statemachine', 'behaviortree',
+ 'scene', 'prefab', 'material', 'tileset', 'tilemap', 'animclip', 'statemachine', 'behaviortree',
]);
/**
@@ -173,15 +177,19 @@ export async function scanAssetDatabase(
if (!JSON_REF_TYPES.has(entry.type)) continue;
try {
const json = JSON.parse(await readFile(path.join(root, entry.path), 'utf8'));
- const dir = entry.path.includes('/') ? entry.path.slice(0, entry.path.lastIndexOf('/')) : '';
const refs = new Set<string>();
collectRefs(json, refs, (ref) => {
if (ref.includes('://')) return null;
- const norm = normalizeRefPath(ref);
- const direct = byPath.get(norm);
+ const direct = byPath.get(normalizeRefPath(ref));
if (direct) return direct.uuid;
- const relative = dir ? byPath.get(normalizeRefPath(`${dir}/${norm}`)) : undefined;
- return relative?.uuid ?? null;
+ // Fall back to a path RELATIVE to the referencing document, resolved the way
+ // the runtime loads it (collapsing ./ and ../) — so a Tiled tileset image
+ // "../textures/tileset.png" or a material's sibling "x.esshader" resolves to
+ // the same asset the loader will request. (The old join left "../" uncollapsed,
+ // so tilemap tileset images never linked and the cook culled them → the
+ // single-file playable 404'd them.)
+ const rel = byPath.get(normalizeRefPath(resolveRelativePath(entry.path, ref)));
+ return rel?.uuid ?? null;
}, (id) => uuids.has(id));
refs.delete(entry.uuid);
if (refs.size > 0) deps[entry.uuid] = [...refs].sort();
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.ts
index 2c105f49f..bec4667c4 100644
--- a/desktop/electron/cookAssets.ts
+++ b/desktop/electron/cookAssets.ts
@@ -24,6 +24,7 @@ import { packAtlas, decodePngImage, encodePagePng, type AtlasInputImage } from '
// Single-source content hash (sdk/src/asset/contentHash.ts). Imported as source —
// no hand-mirrored copy — so the cook and the runtime agree by construction.
import { contentHashHex } from '../../sdk/src/asset/contentHash';
+import { resolveRelativePath } from '../../sdk/src/tilemap/tiledPath';
const MANIFEST = 'assets.manifest.json';
@@ -139,6 +140,35 @@ function rewriteMaterialRefs(
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
+ * project path — the same shape rewriteMaterialRefs produces. The playable loads a map by
+ * its `@uuid` (which carries no directory), so the runtime's `resolveRelativePath(@uuid,
+ * "../textures/x.png")` yields a WRONG root-relative path that matches no embedded asset;
+ * a directory-free logical ref (`assets/textures/x.png`) resolves to the same inlined
+ * asset in every realm. `@uuid:`/URL/already-logical refs pass through unchanged.
+ */
+function rewriteTilemapRefs(
+ bytes: Uint8Array,
+ tmjPath: string,
+ 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 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
+ if (typeof ts.source === 'string') ts.source = rewrite(ts.source); // external .tsj tileset
+ }
+ return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');
+}
+
export interface CookResult {
ok: boolean;
/** Absolute output dir the assets + manifest were staged into. */
@@ -334,6 +364,15 @@ export async function cookAssets(
warnings.push(`${entry.path}: material 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') {
+ try {
+ data = rewriteTilemapRefs(data, entry.path, byPath);
+ } catch (err) {
+ warnings.push(`${entry.path}: tilemap ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);
+ }
+ }
// Shaders ship as-authored; a WGSL twin is what makes one run on the
// WebGPU backend, so a twin-less shader is worth a cook-time warning
// (generation is a dev-time step — tools/gen-shader-twins.mjs writes the
diff --git a/desktop/tests/tilemap-cook-deps.test.ts b/desktop/tests/tilemap-cook-deps.test.ts
new file mode 100644
index 000000000..a5012c07d
--- /dev/null
+++ b/desktop/tests/tilemap-cook-deps.test.ts
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Regression: a Tiled map's tileset images are dependencies. The dep scan must
+ * follow tilemap → tileset image (collapsing the Tiled-relative `../`), and the
+ * cook must rewrite that image ref to a logical project path — otherwise the
+ * single-file playable never embeds the tileset and 404s it as an external file.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { cookAssets } from '../electron/cookAssets';
+
+let root: string;
+
+const TILES_TEX = '11111111-1111-4111-8111-111111111111';
+const PROPS_TEX = '22222222-2222-4222-8222-222222222222';
+const TILEMAP = '33333333-3333-4333-8333-333333333333';
+const SCENE = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+
+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: {} }));
+}
+
+// A .tmj at assets/maps/ whose tilesets reference images in ../textures/ (the Tiled
+// convention: relative to the map file, so it climbs out of maps/ into textures/).
+const tmj = JSON.stringify({
+ type: 'map', version: '1.10', orientation: 'orthogonal', renderorder: 'right-down',
+ width: 2, height: 2, tilewidth: 16, tileheight: 16, infinite: false,
+ nextlayerid: 2, nextobjectid: 1,
+ tilesets: [
+ { firstgid: 1, name: 'tiles', image: '../textures/tiles.png', imagewidth: 32, imageheight: 32, tilewidth: 16, tileheight: 16, columns: 2, tilecount: 4, margin: 0, spacing: 0 },
+ { firstgid: 5, name: 'props', image: '../textures/props.png', imagewidth: 16, imageheight: 16, tilewidth: 16, tileheight: 16, columns: 1, tilecount: 1, margin: 0, spacing: 0 },
+ ],
+ layers: [{ type: 'tilelayer', name: 'L', width: 2, height: 2, x: 0, y: 0, opacity: 1, visible: true, data: [1, 2, 5, 4] }],
+});
+
+const scene = JSON.stringify({
+ version: '1.0', name: 'm',
+ entities: [{ id: 1, name: 'T', parent: null, children: [], components: [{ type: 'Tilemap', data: { source: `@uuid:${TILEMAP}` } }] }],
+});
+
+beforeAll(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-tmcook-'));
+ writeAsset('assets/textures/tiles.png', 'texture', TILES_TEX, 'TILES');
+ writeAsset('assets/textures/props.png', 'texture', PROPS_TEX, 'PROPS');
+ writeAsset('assets/maps/level.tmj', 'tilemap', TILEMAP, tmj);
+ writeAsset('assets/scenes/main.esscene', 'scene', SCENE, scene);
+});
+
+afterAll(() => {
+ if (root) rmSync(root, { recursive: true, force: true });
+});
+
+describe('tilemap tileset images are cooked dependencies', () => {
+ it('embeds a tilemap\'s tileset images (dep scan follows the ../ relative image)', async () => {
+ const res = await cookAssets(root, { entryScenes: ['assets/scenes/main.esscene'], outDir: 'build' });
+ expect(res.ok).toBe(true);
+ // Both tileset images are reachable through the tilemap — not culled.
+ expect(res.included).toEqual(expect.arrayContaining([SCENE, TILEMAP, TILES_TEX, PROPS_TEX]));
+ expect(res.unused).not.toEqual(expect.arrayContaining([TILES_TEX, PROPS_TEX]));
+ });
+
+ it('rewrites the cooked .tmj tileset image refs to logical project paths', async () => {
+ await cookAssets(root, { entryScenes: ['assets/scenes/main.esscene'], outDir: 'build' });
+ const cooked = JSON.parse(readFileSync(path.join(root, 'build', 'assets/maps/level.tmj'), 'utf8'));
+ // "../textures/tiles.png" (map-relative) → "assets/textures/tiles.png" (project-relative),
+ // so the @uuid-loaded map resolves it to the embedded asset in the single-file playable.
+ expect(cooked.tilesets[0].image).toBe('assets/textures/tiles.png');
+ expect(cooked.tilesets[1].image).toBe('assets/textures/props.png');
+ });
+});
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index 53046c508..2bbfb72a2 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -42,6 +42,7 @@ import { mergeCollisionTiles } from './collisionMerge';
import { CHUNK_SIZE } from './chunkCodec';
import { tileIdOf, tileFlagsOf } from './tileBits';
import { log } from '../logger';
+import { resolveRelativePath } from './tiledPath';
export interface TiledChunkData {
x: number;
@@ -464,30 +465,10 @@ export async function parseTmjWithExternals(
return parseTmjJson(json);
}
-export function resolveRelativePath(basePath: string, relativePath: string): string {
- // Preserve a URL scheme+authority (e.g. "estella://project", "http://host")
- // before normalizing: the "//" after the scheme must survive, but the segment
- // walk below drops empty parts — which would collapse "estella://" to
- // "estella:/" and break the fetch. The editor Play realm resolves assets to
- // absolute estella:// URLs, so a Tiled map's relative tileset image ("../x.png")
- // is joined against such a base.
- const schemeMatch = /^([a-z][a-z0-9+.-]*:\/\/[^/]*)(\/.*|)$/i.exec(basePath);
- const prefix = schemeMatch ? schemeMatch[1] : '';
- const pathPart = schemeMatch ? schemeMatch[2] : basePath;
-
- const lastSlash = pathPart.lastIndexOf('/');
- const baseDir = lastSlash >= 0 ? pathPart.substring(0, lastSlash + 1) : '';
- const parts = (baseDir + relativePath).split('/');
- const resolved: string[] = [];
- for (const part of parts) {
- if (part === '..') {
- resolved.pop();
- } else if (part !== '.' && part !== '') {
- resolved.push(part);
- }
- }
- return prefix ? `${prefix}/${resolved.join('/')}` : resolved.join('/');
-}
+// resolveRelativePath now lives in ./tiledPath (a dependency-free leaf) so the editor's
+// asset-dependency scan / cook can share the exact resolution the runtime loads with,
+// without pulling the loader's engine deps. Re-exported here for existing importers.
+export { resolveRelativePath };
export interface TilemapLoadOptions {
generateObjectCollision?: boolean;
diff --git a/sdk/src/tilemap/tiledPath.ts b/sdk/src/tilemap/tiledPath.ts
new file mode 100644
index 000000000..4a33fab46
--- /dev/null
+++ b/sdk/src/tilemap/tiledPath.ts
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+
+/**
+ * Resolve a document-relative path against the referencing file's path — a Tiled
+ * tileset image (`"../textures/tileset.png"`), an external `.tsj` source, a material's
+ * sibling shader — collapsing `./` and `../` and preserving a URL scheme+authority.
+ *
+ * This is a dependency-free leaf so it can be shared by BOTH the runtime tilemap loader
+ * AND the editor's asset-dependency scan / cook: a tilemap's tileset dependencies must
+ * resolve identically wherever they're walked (discover-what-to-ship vs load-it), or the
+ * cook embeds one path and the runtime asks for another (the single-file playable then
+ * 404s a tileset it did ship, or never shipped it at all).
+ */
+export function resolveRelativePath(basePath: string, relativePath: string): string {
+ // Preserve a URL scheme+authority (e.g. "estella://project", "http://host")
+ // before normalizing: the "//" after the scheme must survive, but the segment
+ // walk below drops empty parts — which would collapse "estella://" to
+ // "estella:/" and break the fetch. The editor Play realm resolves assets to
+ // absolute estella:// URLs, so a Tiled map's relative tileset image ("../x.png")
+ // is joined against such a base.
+ const schemeMatch = /^([a-z][a-z0-9+.-]*:\/\/[^/]*)(\/.*|)$/i.exec(basePath);
+ const prefix = schemeMatch ? schemeMatch[1] : '';
+ const pathPart = schemeMatch ? schemeMatch[2] : basePath;
+
+ const lastSlash = pathPart.lastIndexOf('/');
+ const baseDir = lastSlash >= 0 ? pathPart.substring(0, lastSlash + 1) : '';
+ const parts = (baseDir + relativePath).split('/');
+ const resolved: string[] = [];
+ for (const part of parts) {
+ if (part === '..') {
+ resolved.pop();
+ } else if (part !== '.' && part !== '') {
+ resolved.push(part);
+ }
+ }
+ return prefix ? `${prefix}/${resolved.join('/')}` : resolved.join('/');
+}