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(cook): embed + rewrite a tilemap's tileset images for playables
yhh7d2ab744b651
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.tsindex 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.tsindex 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 thediff --git a/desktop/tests/tilemap-cook-deps.test.ts b/desktop/tests/tilemap-cook-deps.test.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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('/');+}