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): the registry goes live - adopt, hot-load, re-project as one chain

yhhb6be2c445c90
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.ts
index 8be6b4837..f51a98e75 100644
--- a/desktop/electron/assetDb.ts
+++ b/desktop/electron/assetDb.ts
@@ -18,7 +18,8 @@
*/
import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
import path from 'node:path';
-import { META_EXT, isContentDir } from './contentPolicy';
+import { META_EXT, isContentDir, isContentFile } from './contentPolicy';
+import { adoptOrphan } from './assetMeta';
// 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';
@@ -58,6 +59,8 @@ export interface ScanAssetsResult {
outputPath: string | null;
index: AssetIndex;
warnings: string[];
+ /** Orphan content files the scan adopted (minted a `.meta` for) this pass. */
+ adopted: string[];
}
/** Recursively yield every `<file>.meta` path (project-relative, forward-slashed). */
@@ -79,6 +82,34 @@ async function* walkMeta(root: string, rel = ''): AsyncGenerator<string> {
}
}
+/**
+ * Adopt orphan content files: any content file of a known asset type with no
+ * `.meta` sidecar gets one minted, so it enters the index THIS scan. "I dropped
+ * my asset folder into the project and opened it" is the first thing every new
+ * user does — files arriving outside the import door (git, Finder, an agent's
+ * bulk copy) must not stay invisible to the registry. Unknown extensions
+ * (docs, source files) are left alone.
+ */
+async function adoptOrphans(root: string, rel = '', adopted: string[] = []): Promise<string[]> {
+ const abs = rel ? path.join(root, rel) : root;
+ let entries;
+ try {
+ entries = await readdir(abs, { withFileTypes: true });
+ } catch {
+ return adopted; // unreadable dir
+ }
+ for (const e of entries) {
+ const relPath = rel ? `${rel}/${e.name}` : e.name;
+ if (e.isDirectory()) {
+ if (!isContentDir(e.name)) continue;
+ await adoptOrphans(root, relPath, adopted);
+ } else if (isContentFile(e.name)) {
+ if ((await adoptOrphan(path.join(abs, e.name))) === 'adopted') adopted.push(relPath);
+ }
+ }
+ return adopted;
+}
+
/**
* Asset types whose JSON documents can reference other assets — these are
* dependency-scanned so the cook's reachability closure includes what they
@@ -144,11 +175,15 @@ function normalizeRefPath(ref: string): string {
*/
export async function scanAssetDatabase(
root: string,
- opts?: { write?: boolean },
+ opts?: { write?: boolean; adopt?: boolean },
): Promise<ScanAssetsResult> {
const entries: AssetEntry[] = [];
const warnings: string[] = [];
+ // Adopt-before-index: orphans minted here are picked up by the meta walk below,
+ // so a single scan both registers and indexes them (no second pass needed).
+ const adopted = opts?.adopt === false ? [] : await adoptOrphans(root);
+
for await (const metaRel of walkMeta(root)) {
let meta: { uuid?: unknown; type?: unknown; importer?: unknown };
try {
@@ -222,9 +257,21 @@ export async function scanAssetDatabase(
let outputPath: string | null = null;
if (opts?.write !== false) {
outputPath = path.join(root, CACHE_DIR, OUTPUT);
- await mkdir(path.dirname(outputPath), { recursive: true });
- await writeFile(outputPath, JSON.stringify(index, null, 2) + '\n');
+ const text = JSON.stringify(index, null, 2) + '\n';
+ // Write-if-changed: the watcher can't tell our cache write from a real
+ // change, so an unconditional write would make every refresh re-trigger
+ // itself (scan → write → fsChanged → scan …). Unchanged index ⇒ no write.
+ let previous: string | null = null;
+ try {
+ previous = await readFile(outputPath, 'utf8');
+ } catch {
+ previous = null;
+ }
+ if (previous !== text) {
+ await mkdir(path.dirname(outputPath), { recursive: true });
+ await writeFile(outputPath, text);
+ }
}
- return { ok: true, outputPath, index, warnings };
+ return { ok: true, outputPath, index, warnings, adopted };
}
diff --git a/desktop/electron/assetMeta.ts b/desktop/electron/assetMeta.ts
new file mode 100644
index 000000000..44f0ed543
--- /dev/null
+++ b/desktop/electron/assetMeta.ts
@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The ONE `.meta` minter. Every path that turns a plain file into a
+ * registered asset — the import door, the create door, and the scan's
+ * orphan-adoption pass — mints through here, so the uuid/version/type/
+ * importer shape can never diverge between doors.
+ *
+ * The ext→type table mirrors the canonical CLI `tools/asset-meta.js`
+ * (meta `type` vocabulary, NOT the SDK's EditorAssetType spellings);
+ * kept in sync by hand — a stable lookup table, and keeping this
+ * desktop-contained avoids reaching into the root tools/.
+ */
+import { writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { META_EXT } from './contentPolicy';
+import { importerDefaults } from '../src/project/assetImporter';
+
+export const META_VERSION = '2.0';
+
+/** Import/adoption ext → `.meta` type (the meta vocabulary the scan reads). */
+export const EXT_TO_TYPE: Record<string, string> = {
+ '.png': 'texture', '.jpg': 'texture', '.jpeg': 'texture', '.webp': 'texture', '.bmp': 'texture',
+ '.ktx2': 'texture',
+ '.wav': 'audio', '.mp3': 'audio', '.ogg': 'audio', '.aac': 'audio', '.flac': 'audio', '.m4a': 'audio', '.webm': 'audio',
+ '.esprefab': 'prefab', '.esscene': 'scene', '.esshader': 'shader', '.esmaterial': 'material', '.esmat': 'material',
+ '.esanim': 'animclip', '.esanimclip': 'animclip', '.estimeline': 'animation',
+ '.estileset': 'tileset', '.esfsm': 'statemachine', '.esbt': 'behaviortree', '.eslocale': 'locale',
+ '.fnt': 'bitmapFont', '.bmfont': 'bitmapFont', '.ttf': 'font', '.otf': 'font', '.woff': 'font', '.woff2': 'font',
+ '.tmx': 'tilemap', '.tmj': 'tilemap',
+ '.skel': 'spine', '.atlas': 'spine',
+ '.inputmap': 'inputmap',
+};
+
+/** The meta `type` for a file name/path, or null for unknown extensions. */
+export function metaTypeFor(file: string): string | null {
+ return EXT_TO_TYPE[path.extname(file).toLowerCase()] ?? null;
+}
+
+/** A fresh `.meta` document for an asset of `type`. */
+export function mintMeta(type: string): Record<string, unknown> {
+ return { uuid: randomUUID(), version: META_VERSION, type, importer: importerDefaults(type) };
+}
+
+/** Write `<absFile>.meta` for @p absFile. Pass `type` to override the
+ * extension-derived one (the create door knows its type explicitly). */
+export async function writeMeta(absFile: string, type: string): Promise<void> {
+ await writeFile(absFile + META_EXT, JSON.stringify(mintMeta(type), null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Adopt an orphan: mint `<absFile>.meta` iff the file has none and its
+ * extension names a known asset type. Returns what happened, so callers can
+ * count adoptions / skip unknowns without re-deriving the checks.
+ */
+export async function adoptOrphan(absFile: string): Promise<'adopted' | 'has-meta' | 'unknown-type'> {
+ if (existsSync(absFile + META_EXT)) return 'has-meta';
+ const type = metaTypeFor(absFile);
+ if (!type) return 'unknown-type';
+ await writeMeta(absFile, type);
+ return 'adopted';
+}
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.ts
index f59b2fa26..b369a9924 100644
--- a/desktop/electron/cookAssets.ts
+++ b/desktop/electron/cookAssets.ts
@@ -204,7 +204,7 @@ export async function cookAssets(
const compressTextures = opts.compressTextures ?? false;
const atlasTextures = opts.atlasTextures ?? false;
const compressAudio = opts.compressAudio ?? false;
- const { index } = await scanAssetDatabase(root, { write: false });
+ const { index } = await scanAssetDatabase(root, { write: false, adopt: false });
const byUuid = new Map(index.entries.map((e) => [e.uuid, e]));
const byPath = new Map(index.entries.map((e) => [e.path, e]));
const warnings: string[] = [];
diff --git a/desktop/electron/importAssets.ts b/desktop/electron/importAssets.ts
index cd45ef0d4..f8997ede3 100644
--- a/desktop/electron/importAssets.ts
+++ b/desktop/electron/importAssets.ts
@@ -1,34 +1,17 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file Asset import (Content Browser C4). Copies external files into the open
- * project and writes a `.meta` sidecar (fresh uuid + type + importer
- * defaults) so the AssetDatabase scan indexes them immediately — the scan
- * only sees files that HAVE a `.meta`.
- *
- * The ext→type table + importer defaults mirror the canonical CLI
- * `tools/asset-meta.js`; kept in sync by hand (a stable lookup table, and
- * keeping this desktop-contained avoids reaching into the root tools/).
+ * @file Asset import (Content Browser C4). Brings files into the project's
+ * asset registry: external files are copied into the project + given a
+ * `.meta` sidecar; files ALREADY inside the project are registered in
+ * place (meta minted iff missing) — never duplicated. The scan only
+ * sees files that HAVE a `.meta`, so this is the registration door.
*/
import { copyFile, mkdir, writeFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
import path from 'node:path';
import { resolveInRoot, META_EXT } from './projectFs';
-import { importerDefaults } from '../src/project/assetImporter';
-
-const META_VERSION = '2.0';
-
-const EXT_TO_TYPE: Record<string, string> = {
- '.png': 'texture', '.jpg': 'texture', '.jpeg': 'texture', '.webp': 'texture', '.bmp': 'texture',
- '.wav': 'audio', '.mp3': 'audio', '.ogg': 'audio', '.aac': 'audio', '.flac': 'audio', '.m4a': 'audio', '.webm': 'audio',
- '.esprefab': 'prefab', '.esscene': 'scene', '.esshader': 'shader', '.esmaterial': 'material', '.esmat': 'material',
- '.esanim': 'animclip', '.esanimclip': 'animclip', '.estimeline': 'animation',
- '.fnt': 'bitmapFont', '.bmfont': 'bitmapFont', '.ttf': 'font', '.otf': 'font', '.woff': 'font', '.woff2': 'font',
- '.tmx': 'tilemap', '.tmj': 'tilemap',
- '.skel': 'spine', '.atlas': 'spine',
- '.inputmap': 'inputmap',
-};
+import { EXT_TO_TYPE, metaTypeFor, mintMeta, writeMeta, adoptOrphan } from './assetMeta';
/** The supported import extensions (no leading dot) — used by the file dialog filter. */
export const IMPORT_EXTENSIONS = Object.keys(EXT_TO_TYPE).map((e) => e.slice(1));
@@ -42,6 +25,14 @@ function uniqueName(absDir: string, name: string): string {
return candidate;
}
+/** The project-relative (forward-slashed) path of `abs` under `root`, or null
+ * when `abs` lives outside the project. */
+function relInRoot(root: string, abs: string): string | null {
+ const rel = path.relative(path.resolve(root), path.resolve(abs));
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+ return rel.replace(/\\/g, '/');
+}
+
/**
* Create a new asset file in `destDir` with `content` + a fresh `.meta` (uuid + the
* given type), deduping the name so it never clobbers. Returns the new project-
@@ -59,22 +50,25 @@ export async function createAsset(
const name = uniqueName(absDir, baseName);
const abs = path.join(absDir, name);
await writeFile(abs, content, 'utf8');
- const meta = { uuid: randomUUID(), version: META_VERSION, type, importer: importerDefaults(type) };
- await writeFile(abs + META_EXT, JSON.stringify(meta, null, 2) + '\n', 'utf8');
+ await writeFile(abs + META_EXT, JSON.stringify(mintMeta(type), null, 2) + '\n', 'utf8');
return destDir ? `${destDir}/${name}` : name;
}
export interface ImportResult {
- /** New project-relative paths of the imported files. */
+ /** Project-relative paths of the imported (or adopted-in-place) files. */
imported: string[];
/** Base names skipped (unknown / unsupported extension). */
skipped: string[];
}
/**
- * Copy `sources` (absolute, user-picked) into project-relative `destDir`, writing
- * a `.meta` (fresh uuid + extension-derived type) for each. Existing names are
- * deduped, never clobbered; unknown extensions are skipped.
+ * Bring `sources` (absolute paths) into the registry:
+ * - external files are copied into project-relative `destDir` + given a `.meta`
+ * (existing names deduped, never clobbered);
+ * - files already inside the project are REGISTERED IN PLACE (meta minted iff
+ * missing, existing uuid preserved) — importing a project file must never
+ * spawn a "name 2" copy with a different identity.
+ * Unknown extensions are skipped.
*/
export async function importAssets(root: string, destDir: string, sources: string[]): Promise<ImportResult> {
const absDir = resolveInRoot(root, destDir);
@@ -82,16 +76,21 @@ export async function importAssets(root: string, destDir: string, sources: strin
const imported: string[] = [];
const skipped: string[] = [];
for (const src of sources) {
- const type = EXT_TO_TYPE[path.extname(src).toLowerCase()];
+ const type = metaTypeFor(src);
if (!type) {
skipped.push(path.basename(src));
continue;
}
+ const inside = relInRoot(root, src);
+ if (inside) {
+ await adoptOrphan(path.resolve(root, inside)); // 'has-meta' = already registered, keep its uuid
+ imported.push(inside);
+ continue;
+ }
const name = uniqueName(absDir, path.basename(src));
const absDest = path.join(absDir, name);
await copyFile(src, absDest);
- const meta = { uuid: randomUUID(), version: META_VERSION, type, importer: importerDefaults(type) };
- await writeFile(absDest + META_EXT, JSON.stringify(meta, null, 2) + '\n', 'utf8');
+ await writeMeta(absDest, type);
imported.push(destDir ? `${destDir}/${name}` : name);
}
return { imported, skipped };
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 945c8c2cf..bb7831ece 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -472,18 +472,32 @@ ipcMain.handle('project:importAssets', async (_e, destDir: string) => {
],
});
if (res.canceled || res.filePaths.length === 0) return null;
- return importAssets(requireRoot(), destDir, res.filePaths);
+ const picked = await importAssets(requireRoot(), destDir, res.filePaths);
+ notifyFsChanged(picked.imported);
+ return picked;
});
+// The write doors PUSH their own change notification once the disk write lands:
+// the fs watcher is best-effort (debounced, events can arrive with no filename),
+// but "the door returned" must mean "the registry can see it" — the renderer's
+// refresh must never depend on the watcher racing our own writes.
+function notifyFsChanged(paths: string[]): void {
+ if (win && !win.isDestroyed()) win.webContents.send('project:fsChanged', { paths });
+}
+
// Import already-resolved absolute paths (OS drag-drop onto the Content Browser).
-ipcMain.handle('project:importFiles', (_e, destDir: string, sources: string[]) =>
- importAssets(requireRoot(), destDir, sources),
-);
+ipcMain.handle('project:importFiles', async (_e, destDir: string, sources: string[]) => {
+ const result = await importAssets(requireRoot(), destDir, sources);
+ notifyFsChanged(result.imported);
+ return result;
+});
// Create a new asset file (+ .meta) from renderer-supplied content (e.g. New Scene).
-ipcMain.handle('project:createAsset', (_e, destDir: string, baseName: string, content: string, type: string) =>
- createAsset(requireRoot(), destDir, baseName, content, type),
-);
+ipcMain.handle('project:createAsset', async (_e, destDir: string, baseName: string, content: string, type: string) => {
+ const rel = await createAsset(requireRoot(), destDir, baseName, content, type);
+ notifyFsChanged([rel]);
+ return rel;
+});
// The project's launcher cover: capture the composited page region the renderer
// passes (its viewport canvas, center-cropped to 16:9) and write it to the project
diff --git a/desktop/electron/projectWatcher.ts b/desktop/electron/projectWatcher.ts
index 32a4bd64e..93ef7587d 100644
--- a/desktop/electron/projectWatcher.ts
+++ b/desktop/electron/projectWatcher.ts
@@ -52,10 +52,15 @@ export function startProjectWatch(root: string, wc: WebContents): void {
stopProjectWatch();
try {
watcher = watch(root, { recursive: true }, (_event, filename) => {
- if (!filename) return; // no path → can't filter safely (would risk the cache loop)
- const rel = filename.toString().replace(/\\/g, '/');
- if (isIgnoredPath(rel)) return;
- pending.add(rel);
+ // A null filename (rapid writes / platform quirks) means "something under
+ // root changed, path unknown". Dropping it left the registry stale until
+ // reopen; push it as an anonymous change instead — the refresh path is
+ // loop-safe now (assets.json is write-if-changed, `.esengine` is dot-ruled).
+ if (filename) {
+ const rel = filename.toString().replace(/\\/g, '/');
+ if (isIgnoredPath(rel)) return;
+ pending.add(rel);
+ }
if (timer) clearTimeout(timer);
timer = setTimeout(() => {
const paths = [...pending];
diff --git a/desktop/scripts/editor-mcp-editor-e2e.mjs b/desktop/scripts/editor-mcp-editor-e2e.mjs
index b50363e77..6fb9f2274 100644
--- a/desktop/scripts/editor-mcp-editor-e2e.mjs
+++ b/desktop/scripts/editor-mcp-editor-e2e.mjs
@@ -11,7 +11,7 @@
* (ESTELLA_E2E_EXPORT=1 additionally runs a web export to the temp dir.)
*/
import { spawn } from 'node:child_process';
-import { cp, mkdtemp, rm, stat } from 'node:fs/promises';
+import { cp, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -28,6 +28,17 @@ await cp(EXAMPLE, project, {
filter: (src) => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(src),
});
+// An ORPHAN texture (no `.meta`) staged before open — "I dropped my art into
+// the project folder and opened it" — the open scan must adopt it into the
+// registry, and a cold assignment to it must light up live (guards below).
+const ORPHAN_REL = 'assets/textures/orphan-e2e.png';
+const ORPHAN_PNG = Buffer.from(
+ 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+ 'base64',
+);
+await mkdir(path.join(project, 'assets', 'textures'), { recursive: true });
+await writeFile(path.join(project, ORPHAN_REL), ORPHAN_PNG);
+
// ESTELLA_E2E_FRONT points at an alternate front (e.g. the shipped bundle,
// dist-electron/mcp/editor-mcp.mjs) to prove distribution artifacts end to end.
const front = process.env.ESTELLA_E2E_FRONT ?? 'scripts/editor-mcp.mjs';
@@ -115,6 +126,30 @@ try {
await fail(`get_diagnostics missed the fresh Sprite's empty texture (${JSON.stringify(diags).slice(0, 200)})`);
console.log(`get_diagnostics OK — flagged Sprite.texture on the new entity`);
+ // — Hot-asset chain guards (the white-box family) —
+ // The orphan staged before open had no `.meta`: the open scan must have
+ // adopted it, and a COLD texture assignment must light up the live World with
+ // NO project reopen (set_field → touch → async load → re-project). Polling is
+ // the contract here: the load is async, but it must CONVERGE.
+ await call('set_field', { entity: created, component: 'Sprite', key: 'texture', type: 'asset', value: ORPHAN_REL });
+ let handle = 0;
+ for (let i = 0; i < 50 && handle === 0; i++) {
+ const sprite = JSON.parse((await call('world_component', { id: created, component: 'Sprite' })).text);
+ handle = sprite?.texture ?? 0;
+ if (handle === 0) await new Promise((r) => setTimeout(r, 100));
+ }
+ if (handle === 0) await fail('cold Sprite.texture never resolved to a live handle — hot-load chain broken');
+ console.log(`hot texture OK — orphan adopted at open + cold set_field lit up (handle ${handle})`);
+
+ // A ref to a file that does NOT exist must surface as a queryable diagnostic:
+ // the model value looks healthy — only the registry knows the ref is dead.
+ await call('set_field', { entity: created, component: 'Sprite', key: 'texture', type: 'asset', value: 'assets/textures/does-not-exist.png' });
+ const deadDiags = JSON.parse((await call('get_diagnostics')).text);
+ if (!deadDiags.some((d) => d.entity === created && d.problem === 'asset-unresolved'))
+ await fail(`get_diagnostics missed the dead texture ref (${JSON.stringify(deadDiags).slice(0, 200)})`);
+ await call('set_field', { entity: created, component: 'Sprite', key: 'texture', type: 'asset', value: ORPHAN_REL });
+ console.log('asset-unresolved diagnostic OK — a dead ref is queryable, not just a white box');
+
await call('set_field', { entity: created, component: 'Transform', key: 'position', type: 'vec3', value: [64, 96, 0] });
const live = JSON.parse((await call('world_component', { id: created, component: 'Transform' })).text);
if (!live) await fail('world_component returned null — edit did not reach the World');
diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/scripts/editor-mcp-tools.mjs
index fc1f5ede9..58101c802 100644
--- a/desktop/scripts/editor-mcp-tools.mjs
+++ b/desktop/scripts/editor-mcp-tools.mjs
@@ -165,21 +165,24 @@ export const TOOLS = [
description: 'Save the open scene to disk (the toolbar Save).',
schema: obj({}), method: 'save', args: () => [], root: 'editor' },
{ name: 'create_scene_file', write: true,
- description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path.',
+ description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path, immediately referenceable (the registry refresh happens before this resolves).',
schema: obj({ destDir: { type: 'string' } }, ['destDir']),
- method: 'createSceneFile', args: (i) => [i.destDir], root: 'editor' },
+ js: (i) => `window.__estellaEditor.createSceneFile(${JSON.stringify(i.destDir)})
+ .then((p) => window.__estellaEditor.refreshAssets().then(() => p))` },
{ name: 'create_asset', write: true,
- description: 'Create a text asset file under a project-relative directory with the given content (types the editor knows: scene, inputmap, locale, fsm, bt, timeline, animclip, tileset, material, shader, prefab...). Returns its project-relative path.',
+ description: 'Create a text asset file under a project-relative directory with the given content (types the editor knows: scene, inputmap, locale, fsm, bt, timeline, animclip, tileset, material, shader, prefab...). Returns its project-relative path, immediately referenceable (the registry refresh happens before this resolves).',
schema: obj({
destDir: { type: 'string' }, baseName: { type: 'string' },
content: { type: 'string' }, type: { type: 'string' },
}, ['destDir', 'baseName', 'content', 'type']),
- js: (i) => `window.estella.project.createAsset(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.baseName)}, ${JSON.stringify(i.content)}, ${JSON.stringify(i.type)})` },
+ js: (i) => `window.estella.project.createAsset(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.baseName)}, ${JSON.stringify(i.content)}, ${JSON.stringify(i.type)})
+ .then((p) => window.__estellaEditor.refreshAssets().then(() => p))` },
{ name: 'import_assets', write: true,
- description: 'Import external files (absolute paths: textures, audio, fonts, spine, tilemaps...) into a project-relative directory. Returns { imported, skipped }.',
+ description: 'Import files into the asset registry (textures, audio, fonts, spine, tilemaps...). External absolute paths are copied into project-relative destDir; paths already INSIDE the project are registered in place (no copy, no rename). Returns { imported, skipped }; imported paths are immediately referenceable (the registry refresh happens before this resolves).',
schema: obj({ destDir: { type: 'string' }, sources: { type: 'object', description: 'array of absolute file paths' } },
['destDir', 'sources']),
- js: (i) => `window.estella.project.importFiles(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.sources)})` },
+ js: (i) => `window.estella.project.importFiles(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.sources)})
+ .then((r) => window.__estellaEditor.refreshAssets().then(() => r))` },
{ name: 'set_project_physics', write: true,
description: 'Patch the project physics feature (Project Settings → Physics), e.g. { "enabled": true }. Persists to the manifest; Play and exports boot it.',
schema: obj({ patch: { type: 'object' } }, ['patch']),
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 44c3d47dd..13e0dc992 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -49,10 +49,20 @@ export interface SceneDiagnostic {
entityName: string;
component: string;
field?: string;
- problem: 'required-empty' | 'notice';
+ problem: 'required-empty' | 'asset-unresolved' | 'notice';
detail: string;
}
+/** Why a MODEL-healthy asset ref still yields no live asset (unknown to the
+ * registry / its load failed), or null when it's fine. Installed by
+ * ProjectStore — the surface itself is project-agnostic (headless hosts run
+ * without a registry, where every ref is presumed fine). */
+type AssetRefProblemResolver = (ref: string) => string | null;
+let assetRefProblem: AssetRefProblemResolver | null = null;
+export function setAssetRefProblemResolver(fn: AssetRefProblemResolver | null): void {
+ assetRefProblem = fn;
+}
+
/** The session parts the surface needs (the EditorSession satisfies this). */
export interface SurfaceSession {
model: SceneModelImpl;
@@ -284,6 +294,18 @@ export class EditorControlSurfaceImpl {
problem: 'required-empty',
detail: `${comp.name}.${f.key} is required but empty`,
});
+ } else if (f.type === 'asset' && typeof f.value === 'string' && f.value !== '') {
+ // The model value LOOKS healthy — only the registry/loader knows
+ // whether it names a real, loadable asset (a dead ref draws the
+ // same white box an empty one does, in silence).
+ const why = assetRefProblem?.(f.value);
+ if (why) {
+ issues.push({
+ entity: node.id, entityName: node.name, component: comp.name, field: f.key,
+ problem: 'asset-unresolved',
+ detail: `${comp.name}.${f.key}: ${why}`,
+ });
+ }
}
}
if (comp.notice) {
diff --git a/desktop/src/engine/Reconciler.ts b/desktop/src/engine/Reconciler.ts
index 252355377..f10629ba5 100644
--- a/desktop/src/engine/Reconciler.ts
+++ b/desktop/src/engine/Reconciler.ts
@@ -83,10 +83,15 @@ const UNRESOLVED: AssetResolver = () => 0;
type RefPathResolver = (ref: string) => string | null;
const UNRESOLVED_PATH: RefPathResolver = () => null;
+/** A projected asset ref that is NOT live yet (cold handle / data cache miss).
+ * The installed listener owns making it live (async load, then re-project). */
+type AssetTouchListener = (ref: string, fieldType: string) => void;
+
export class ReconcilerImpl {
private unsubscribe: (() => void) | null = null;
private resolveAsset: AssetResolver = UNRESOLVED;
private resolveRefPath: RefPathResolver = UNRESOLVED_PATH;
+ private touchAsset: AssetTouchListener | null = null;
constructor(private readonly model: SceneModelImpl) {}
@@ -122,6 +127,36 @@ export class ReconcilerImpl {
this.resolveRefPath = fn ?? UNRESOLVED_PATH;
}
+ /**
+ * Install the cold-asset listener. The resolver contract above is synchronous
+ * (a projection can't await a fetch), so an edited ref whose asset was never
+ * loaded resolves to a dead value — historically it stayed dead forever, in
+ * silence (the white-box family: set a texture via the surface or the picker
+ * popover and the handle is 0 until the project is reopened). The listener is
+ * the async half: ProjectStore loads the asset through the engine's own
+ * loaders and re-projects the referencing components when it lands.
+ */
+ setAssetTouchListener(fn: AssetTouchListener | null): void {
+ this.touchAsset = fn;
+ }
+
+ /**
+ * Re-project every spawned component holding a string field that `matches`
+ * (asset refs live in the model as strings — `@uuid:` or project paths).
+ * The async half of the touch listener calls this when a load lands, so the
+ * exact components that referenced the cold asset re-resolve to live values.
+ */
+ reprojectRefs(matches: (ref: string) => boolean): void {
+ for (const entity of this.model.allSourceEntities()) {
+ if (this.model.runtimeFor(entity.id) == null) continue;
+ for (const comp of entity.components) {
+ const data = comp.data as Record<string, unknown>;
+ const hit = Object.values(data).some((v) => typeof v === 'string' && v !== '' && matches(v));
+ if (hit) this.projectComponent(entity.id, comp.type);
+ }
+ }
+ }
+
/**
* Bulk path (boot / project load / play-stop): build the World from a resolved
* scene and adopt the raw scene as the model. `resetWorldTo` returns source-id
@@ -361,8 +396,16 @@ export class ReconcilerImpl {
const at = assetFieldType(type, key);
if (at) {
// Path-valued slots keep a project path (the runtime loader fetches the
- // file); handle-valued slots resolve to a live GL/native handle.
- return PATH_VALUED_ASSET_TYPES.has(at) ? (this.resolveRefPath(v) ?? v) : this.resolveAsset(v);
+ // file); handle-valued slots resolve to a live GL/native handle. Either
+ // way a projected ref may be COLD (never loaded in this realm) — hand it
+ // to the touch listener, whose async load + re-project makes it live.
+ if (PATH_VALUED_ASSET_TYPES.has(at)) {
+ if (v !== '') this.touchAsset?.(v, at);
+ return this.resolveRefPath(v) ?? v;
+ }
+ const handle = this.resolveAsset(v);
+ if (handle === 0 && v !== '') this.touchAsset?.(v, at);
+ return handle;
}
}
return this.resolveRefs(v);
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 7310f03b5..e2a72d7b9 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -104,6 +104,10 @@ if (new URLSearchParams(location.search).has('automation')) {
return EditorControlSurface.getSceneTree().length > 0;
},
selectAsset: (path: string | null) => useSelection.getState().selectAsset(path),
+ /** Re-scan the asset registry NOW (awaitable). The write doors' contract is
+ * "returned ⇒ resolvable": programmatic create/import chain this so a
+ * follow-up `@uuid:`/path ref never races the debounced watcher refresh. */
+ refreshAssets: () => ProjectStore.refreshAssets(),
play: () => useEditorStore.getState().togglePlay(),
playState: () => PlayRealm.getSnapshot(),
/** Player count for the next Play (1 = single, 2-4 = listen server + clients). */
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index bfba39b79..dcb653a8d 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -3,7 +3,7 @@
import { createStore } from 'zustand/vanilla';
import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, diffAgainstSource, applyOverridesToSource, setTextureParams, TextureFilter, TextureWrap, Renderer } from 'esengine';
import { readTextureImportSettings } from './assetImporter';
-import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig } from 'esengine';
+import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData } from 'esengine';
import { EngineHost } from '@/engine/EngineHost';
import { SceneModel } from '@/engine/SceneModel';
import { Reconciler } from '@/engine/Reconciler';
@@ -15,7 +15,9 @@ import { Boxes } from 'lucide-react';
import { spritePrefab, setCanvasDesignSeed, type EntitySource } from '@/engine/entitySources';
import { setPrefabBaseResolver } from '@/engine/SceneQuery';
import { setUserSchemas, userSchema, setBitmaskSource, setEnumSource, type UserComponentSchema } from '@/engine/schema';
+import { setAssetRefProblemResolver } from '@/engine/EditorControlSurface';
import { installSpineSync, type SpineTransport } from '@/engine/spineSync';
+import { SceneStore } from '@/engine/SceneStore';
import { useSelection } from '@/store/selectionStore';
import { Toasts } from '@/store/Toasts';
import { confirmDiscard } from './discardGuard';
@@ -93,6 +95,25 @@ interface PreloadResult {
fontHandles: Map<string, number>;
}
+/** `.meta` type vocabulary → component asset-slot type (what the hot loader
+ * dispatches on). Null for types no component slot references (scene, shader,
+ * spine — spine has its own live sync; prefabs expand at load). */
+function metaTypeToSlot(metaType: string | undefined): string | null {
+ switch (metaType) {
+ case 'texture': return 'texture';
+ case 'material': return 'material';
+ case 'font': case 'bitmapFont': return 'font';
+ case 'audio': return 'audio';
+ case 'animclip': return 'anim-clip';
+ case 'animation': return 'timeline';
+ case 'tilemap': return 'tilemap';
+ case 'tileset': return 'tileset';
+ case 'statemachine': return 'statemachine';
+ case 'behaviortree': return 'behaviortree';
+ default: return null;
+ }
+}
+
interface ProjectState {
root: string;
name: string;
@@ -139,8 +160,17 @@ class ProjectStoreImpl {
* same texture filter/wrap the runtime does (edit == play), and the asset
* inspector's Save can push a live sampler update. */
private readonly uuidToImporter = new Map<string, Record<string, unknown>>();
+ /** uuid → the asset's `.meta` type — the hot-sync path picks a loader by it. */
+ private readonly uuidToType = new Map<string, string>();
/** ref → loaded `.esprefab` (PrefabData), for scene load-expand / save-collapse. */
private readonly prefabCache = new Map<string, PrefabData>();
+ /** Cold refs already handed to a live load this registry generation — the touch
+ * listener fires on every projection of a still-cold ref, so without this a
+ * failing asset would re-fetch forever (and a slow one would double-load). */
+ private readonly hotLoadStarted = new Set<string>();
+ /** Resolved path → error message for live loads that FAILED — diagnostics
+ * surfaces these (the model looks fine; only the load knows it's broken). */
+ private readonly assetLoadFailures = new Map<string, string>();
/** The latest scene preload result; the Reconciler resolver reads handles from
* it for entities recreated incrementally (duplicate / undo / play-stop). */
private lastAssetResult: PreloadResult | null = null;
@@ -163,6 +193,9 @@ class ProjectStoreImpl {
setEnumSource('sortingLayers', () => this.sortingLayerOptions());
// New Canvas entities seed their design resolution from the project setting.
setCanvasDesignSeed(() => this.designResolution());
+ // Diagnostics ask the registry whether a model-healthy asset ref actually
+ // names a real, loadable asset (dead refs draw white boxes in silence).
+ setAssetRefProblemResolver((ref) => this.assetRefProblem(ref));
}
/** Read accessor so existing `this.state` reads stay unchanged after the move. */
@@ -335,6 +368,9 @@ class ProjectStoreImpl {
// slots resolve to project paths instead (they stay strings in the World).
Reconciler.setAssetResolver((ref) => this.handleForRef(ref));
Reconciler.setRefPathResolver((ref) => this.resolveRef(ref));
+ // A projection that resolves COLD (assigned after the scene-open preload)
+ // hands its ref here: async load through the engine loaders, re-project.
+ Reconciler.setAssetTouchListener((ref, slot) => this.hotLoadAsset(ref, slot));
// Spine bindings (skeleton/atlas/pages → SpineManager) are a live projection
// of the model, driven by model events: adopt's `reset` performs the initial
// bind, and later ref/field edits keep the viewport true (see spineSync).
@@ -385,6 +421,7 @@ class ProjectStoreImpl {
useSelection.getState().select(null);
Reconciler.setAssetResolver((ref) => this.handleForRef(ref));
Reconciler.setRefPathResolver((ref) => this.resolveRef(ref));
+ Reconciler.setAssetTouchListener((ref, slot) => this.hotLoadAsset(ref, slot));
installSpineSync(this.spineTransport());
Reconciler.adopt(blank, blank); // no @uuid: refs → resolved === raw
EngineHost.syncEditorViewToScene();
@@ -423,22 +460,35 @@ class ProjectStoreImpl {
*/
private async buildAssetRegistry(): Promise<void> {
if (!this.state) return;
- let entries: { uuid: string; path: string; importer?: Record<string, unknown> }[];
+ let entries: { uuid: string; path: string; type?: string; importer?: Record<string, unknown> }[];
+ let adopted: string[] = [];
try {
- ({ entries } = (await window.estella.project.scanAssets()).index);
+ const scan = await window.estella.project.scanAssets();
+ ({ entries } = scan.index);
+ adopted = scan.adopted ?? [];
} catch (err) {
console.warn('[project] asset scan failed', err);
return;
}
+ if (adopted.length > 0) {
+ console.info(
+ `[assets] adopted ${adopted.length} file(s) that had no .meta — they are now registered assets`,
+ adopted,
+ );
+ }
this.uuidToPath.clear();
this.pathToUuid.clear();
this.uuidToImporter.clear();
+ this.uuidToType.clear();
this.prefabCache.clear();
+ this.hotLoadStarted.clear();
+ this.assetLoadFailures.clear();
for (const e of entries) {
const uuid = e.uuid.toLowerCase();
this.uuidToPath.set(uuid, e.path);
this.pathToUuid.set(e.path, uuid);
if (e.importer) this.uuidToImporter.set(uuid, e.importer);
+ if (e.type) this.uuidToType.set(uuid, e.type);
}
const assets = EngineHost.getResource(Assets);
@@ -506,6 +556,120 @@ class ProjectStoreImpl {
return r.materialHandles.get(path) ?? r.fontHandles.get(path) ?? 0;
}
+ /**
+ * The async half of live asset resolution (the Reconciler's touch listener).
+ * A projection just resolved `ref` COLD — the scene-open preload never saw it
+ * (assigned after load: surface setField, the picker popover, a hot-created
+ * asset). Load it through the engine's own loader for its slot type, then
+ * re-project the components that reference it; failures are LOUD and recorded
+ * for diagnostics. Deduped per registry generation so a broken ref can't
+ * re-fetch forever.
+ */
+ private hotLoadAsset(ref: string, fieldType: string): void {
+ const path = this.resolveRef(ref);
+ if (path === null) return; // unknown uuid — diagnostics reports it; nothing to load
+ const key = `${fieldType}:${path}`;
+ if (this.hotLoadStarted.has(key)) return;
+ this.hotLoadStarted.add(key);
+ const assets = EngineHost.getResource(Assets);
+ if (!assets) return;
+ void this.loadForSlot(assets, fieldType, ref, path)
+ .then(() => {
+ this.assetLoadFailures.delete(path);
+ Reconciler.reprojectRefs((r) => this.resolveRef(r) === path);
+ SceneStore.poke();
+ })
+ .catch((err) => {
+ const msg = err instanceof Error ? err.message : String(err);
+ this.assetLoadFailures.set(path, msg);
+ console.error(`[assets] live load of ${fieldType} "${path}" failed: ${msg}`);
+ });
+ }
+
+ /** Load `ref` with the loader its slot type names — the same loaders the
+ * scene-open preload dispatches to (one loading truth, two trigger times). */
+ private loadForSlot(assets: AssetsData, fieldType: string, ref: string, path: string): Promise<unknown> {
+ switch (fieldType) {
+ case 'texture':
+ return assets.loadTexture(ref); // ref, not path: importer settings key off the original ref
+ case 'material':
+ return assets.loadMaterial(ref).then((r) => this.recordHandle('material', path, r.handle));
+ case 'font':
+ return assets.loadFont(ref).then((r) => this.recordHandle('font', path, r.handle));
+ case 'audio':
+ return assets.loadAudio(ref);
+ case 'anim-clip':
+ return assets.loadAnimClip(ref); // raw ref: the loader aliases it for component lookups
+ case 'tilemap':
+ return assets.loadTilemap(path);
+ case 'tileset':
+ return assets.loadTileset(path);
+ case 'timeline':
+ return assets.loadTimeline(path);
+ case 'statemachine':
+ return assets.loadStateMachine(path);
+ case 'behaviortree':
+ return assets.loadBehaviorTree(path);
+ default:
+ return Promise.reject(new Error(`no live loader for asset slot type "${fieldType}"`));
+ }
+ }
+
+ /** Record a hot-loaded material/font handle where the incremental resolver
+ * looks them up (they have no live engine-side cache getter like textures). */
+ private recordHandle(kind: 'material' | 'font', path: string, handle: number): void {
+ if (!this.lastAssetResult) {
+ this.lastAssetResult = { textureHandles: new Map(), materialHandles: new Map(), fontHandles: new Map() };
+ }
+ const maps = this.lastAssetResult;
+ (kind === 'material' ? maps.materialHandles : maps.fontHandles).set(path, handle);
+ }
+
+ /**
+ * Content changed ON DISK (fs watcher) — keep the live realm coherent: drop
+ * every stale cache entry for the changed assets and, when something in the
+ * open scene still references them, reload + re-project. This is the missing
+ * half of hot reload that made a re-imported/re-written asset render stale
+ * (or as fragments of whatever texture inherited its handle).
+ */
+ hotSyncChangedPaths(paths: readonly string[]): void {
+ const assets = EngineHost.getResource(Assets);
+ if (!assets) return;
+ const seen = new Set<string>();
+ for (const raw of paths) {
+ const rel = raw.replace(/\\/g, '/').replace(/\.meta$/, '');
+ if (rel === '' || seen.has(rel)) continue;
+ seen.add(rel);
+ const uuid = this.pathToUuid.get(rel);
+ if (!uuid) continue; // not a registered asset (or deleted — registry refresh handles it)
+ if (!assets.invalidate(rel)) continue; // nothing was cached → nothing is stale
+ // The asset WAS live: clear the dedup so the reload can start, then reload
+ // through the same slot-typed path a cold projection uses.
+ for (const key of [...this.hotLoadStarted]) {
+ if (key.endsWith(`:${rel}`)) this.hotLoadStarted.delete(key);
+ }
+ const slot = metaTypeToSlot(this.uuidToType.get(uuid));
+ if (slot) this.hotLoadAsset(UUID_PREFIX + uuid, slot);
+ }
+ }
+
+ /**
+ * Why an asset REFERENCE would not produce a live asset, or null when it's
+ * fine: `unresolved` (the registry knows no such uuid/path) or a recorded
+ * live-load failure. Diagnostics adds these on top of required-empty — the
+ * model value looks perfectly healthy in both cases.
+ */
+ assetRefProblem(ref: string): string | null {
+ const uuid = refUuid(ref);
+ const path = uuid !== null ? (this.uuidToPath.get(uuid) ?? null) : ref;
+ if (path === null) return 'unresolved: no asset with this uuid in the registry';
+ if (uuid === null && !this.pathToUuid.has(path)) {
+ return `unresolved: "${path}" is not a registered asset`;
+ }
+ const failure = this.assetLoadFailures.get(path);
+ return failure ? `load failed: ${failure}` : null;
+ }
+
/** The live material handle a scene's sprites use for @p path (from the last scene
* preload), or 0 if the material isn't loaded in the current scene. The Material Editor
* uses it to push live edits onto the running material so the viewport reflects them. */
diff --git a/desktop/src/project/fsWatch.ts b/desktop/src/project/fsWatch.ts
index 79c2dcf64..4a34005c6 100644
--- a/desktop/src/project/fsWatch.ts
+++ b/desktop/src/project/fsWatch.ts
@@ -65,7 +65,13 @@ export function initFsWatch(): void {
// Coalesce back-to-back bursts; one scan + one bump per quiet window.
if (debounce) clearTimeout(debounce);
debounce = setTimeout(() => {
- void ProjectStore.refreshAssets();
+ void ProjectStore.refreshAssets().then(() => {
+ // With the registry fresh, drop stale caches for the changed files and
+ // reload + re-project whatever the open scene still references — an
+ // externally rewritten texture/tilemap must not keep rendering old bytes
+ // (or fragments of whichever texture inherited its evicted handle).
+ ProjectStore.hotSyncChangedPaths(paths);
+ });
fsRefresh.bump();
}, 60);
diff --git a/desktop/tests/asset-db.test.ts b/desktop/tests/asset-db.test.ts
index a520f4256..12104b4f7 100644
--- a/desktop/tests/asset-db.test.ts
+++ b/desktop/tests/asset-db.test.ts
@@ -8,7 +8,7 @@
* `type` each `.meta` already declares (no extension table).
*/
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { scanAssetDatabase, type AssetIndex } from '../electron/assetDb';
@@ -92,4 +92,49 @@ describe('scanAssetDatabase (A2)', () => {
expect(index.entries.some((e) => e.path.includes('node_modules'))).toBe(false);
expect(index.entries.length).toBe(3); // texture + font + scene, nothing from node_modules
});
+
+ it('write-if-changed: an unchanged index does not rewrite assets.json', async () => {
+ const first = await scanAssetDatabase(root);
+ const mtime = statSync(first.outputPath!).mtimeMs;
+ const second = await scanAssetDatabase(root);
+ expect(statSync(second.outputPath!).mtimeMs).toBe(mtime); // untouched → no watcher echo
+ });
+});
+
+describe('scanAssetDatabase — orphan adoption', () => {
+ it('adopts a content file with no .meta: mints one and indexes it this scan', async () => {
+ const abs = path.join(root, 'assets/textures/orphan.png');
+ writeFileSync(abs, 'PNGDATA');
+ const res = await scanAssetDatabase(root, { write: false });
+ expect(res.adopted).toEqual(['assets/textures/orphan.png']);
+ expect(existsSync(`${abs}.meta`)).toBe(true);
+ const meta = JSON.parse(readFileSync(`${abs}.meta`, 'utf8'));
+ expect(meta.type).toBe('texture');
+ const entry = res.index.entries.find((e) => e.path === 'assets/textures/orphan.png');
+ expect(entry?.uuid).toBe(meta.uuid.toLowerCase());
+ // Second scan: nothing left to adopt, identity stable.
+ const again = await scanAssetDatabase(root, { write: false });
+ expect(again.adopted).toEqual([]);
+ expect(again.index.entries.find((e) => e.path === 'assets/textures/orphan.png')?.uuid)
+ .toBe(entry?.uuid);
+ rmSync(abs); rmSync(`${abs}.meta`);
+ });
+
+ it('leaves unknown extensions alone (docs and source files are not assets)', async () => {
+ const abs = path.join(root, 'assets/README.txt');
+ writeFileSync(abs, 'hello');
+ const res = await scanAssetDatabase(root, { write: false });
+ expect(res.adopted).toEqual([]);
+ expect(existsSync(`${abs}.meta`)).toBe(false);
+ rmSync(abs);
+ });
+
+ it('adopt: false is a pure read (cook path) — orphans stay untouched', async () => {
+ const abs = path.join(root, 'assets/pure.png');
+ writeFileSync(abs, 'PNGDATA');
+ const res = await scanAssetDatabase(root, { write: false, adopt: false });
+ expect(res.adopted).toEqual([]);
+ expect(existsSync(`${abs}.meta`)).toBe(false);
+ rmSync(abs);
+ });
});
diff --git a/desktop/tests/import-assets.test.ts b/desktop/tests/import-assets.test.ts
new file mode 100644
index 000000000..8c3738ad1
--- /dev/null
+++ b/desktop/tests/import-assets.test.ts
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The import door (importAssets/createAsset): external files copy in +
+ * mint a `.meta`; files ALREADY inside the project register in place —
+ * never a "name 2" duplicate with a fresh identity (the bulk-art dogfood
+ * friction). Unknown extensions skip.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { importAssets, createAsset } from '../electron/importAssets';
+
+let root: string;
+let outside: string;
+
+beforeEach(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-import-'));
+ outside = mkdtempSync(path.join(tmpdir(), 'estella-src-'));
+});
+
+afterEach(() => {
+ rmSync(root, { recursive: true, force: true });
+ rmSync(outside, { recursive: true, force: true });
+});
+
+const meta = (abs: string): { uuid: string; type: string } =>
+ JSON.parse(readFileSync(`${abs}.meta`, 'utf8'));
+
+describe('importAssets', () => {
+ it('copies an external file into destDir and mints a .meta', async () => {
+ const src = path.join(outside, 'hero.png');
+ writeFileSync(src, 'PNG');
+ const res = await importAssets(root, 'assets/art', [src]);
+ expect(res.imported).toEqual(['assets/art/hero.png']);
+ const abs = path.join(root, 'assets/art/hero.png');
+ expect(existsSync(abs)).toBe(true);
+ expect(meta(abs).type).toBe('texture');
+ });
+
+ it('registers an in-project file IN PLACE: no copy, no rename, meta minted beside it', async () => {
+ const abs = path.join(root, 'assets/sky/night.png');
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, 'PNG');
+ const res = await importAssets(root, 'assets/sky', [abs]);
+ expect(res.imported).toEqual(['assets/sky/night.png']);
+ // In place: exactly the file + its meta, no "night 2.png".
+ expect(readdirSync(path.dirname(abs)).sort()).toEqual(['night.png', 'night.png.meta']);
+ expect(meta(abs).type).toBe('texture');
+ });
+
+ it('an in-project file that ALREADY has a .meta keeps its uuid (idempotent re-import)', async () => {
+ const abs = path.join(root, 'assets/tiles.png');
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, 'PNG');
+ writeFileSync(`${abs}.meta`, JSON.stringify({ uuid: 'keep-me', version: '2.0', type: 'texture', importer: {} }));
+ const res = await importAssets(root, 'assets', [abs]);
+ expect(res.imported).toEqual(['assets/tiles.png']);
+ expect(meta(abs).uuid).toBe('keep-me');
+ });
+
+ it('destDir is ignored for in-project sources (registration, not relocation)', async () => {
+ const abs = path.join(root, 'assets/deep/rock.png');
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, 'PNG');
+ const res = await importAssets(root, 'somewhere/else', [abs]);
+ expect(res.imported).toEqual(['assets/deep/rock.png']);
+ expect(existsSync(path.join(root, 'somewhere/else/rock.png'))).toBe(false);
+ });
+
+ it('still dedups the name for EXTERNAL collisions ("hero 2.png")', async () => {
+ const src = path.join(outside, 'hero.png');
+ writeFileSync(src, 'PNG2');
+ mkdirSync(path.join(root, 'assets'), { recursive: true });
+ writeFileSync(path.join(root, 'assets/hero.png'), 'PNG1');
+ const res = await importAssets(root, 'assets', [src]);
+ expect(res.imported).toEqual(['assets/hero 2.png']);
+ });
+
+ it('skips unknown extensions', async () => {
+ const src = path.join(outside, 'notes.txt');
+ writeFileSync(src, 'hi');
+ const res = await importAssets(root, 'assets', [src]);
+ expect(res.imported).toEqual([]);
+ expect(res.skipped).toEqual(['notes.txt']);
+ });
+});
+
+describe('createAsset', () => {
+ it('writes content + meta with the explicit type', async () => {
+ const rel = await createAsset(root, 'assets/ai', 'patrol.esfsm', '{"states":[]}', 'statemachine');
+ expect(rel).toBe('assets/ai/patrol.esfsm');
+ expect(meta(path.join(root, rel)).type).toBe('statemachine');
+ });
+});
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 8149b9a50..843d2751a 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -8,7 +8,7 @@ import type {
AssetLoader, LoadContext, TextureResult, SpineResult,
MaterialResult, FontResult, AudioResult, AnimClipResult,
TilemapResult, TilesetResult, TimelineResult, PrefabResult,
- LocaleResult,
+ LocaleResult, FsmResult, BtResult,
} from './AssetLoader';
import { AsyncCache } from './AsyncCache';
import type { ESEngineModule } from '../wasm';
@@ -337,6 +337,18 @@ export class Assets {
return this.loadTyped('locale', ref);
}
+ /** Load a `.esfsm` state machine into the shared AI store, keyed by its
+ * asset path — the ref a StateMachineAgent's `fsm` field resolves. */
+ async loadStateMachine(ref: string): Promise<FsmResult> {
+ return this.loadTyped('statemachine', ref);
+ }
+
+ /** Load a `.esbt` behavior tree into the shared AI store, keyed by its
+ * asset path — the ref a BehaviorTreeAgent's `bt` field resolves. */
+ async loadBehaviorTree(ref: string): Promise<BtResult> {
+ return this.loadTyped('behaviortree', ref);
+ }
+
async loadPrefab(ref: string): Promise<PrefabResult> {
return this.loadTyped('prefab', ref);
}
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
index 33aaf753b..567d38d63 100644
--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -5,7 +5,7 @@ import {
packCollectionGrid, parseTmjWithExternals, resolveRelativePath,
type TiledMapData, type TiledTilesetData,
} from '../../tilemap/tiledLoader';
-import { registerTilemapSource, type LoadedTilemapTileset } from '../../tilemap/tilesetCache';
+import { registerTilemapSource, unregisterTilemapSource, type LoadedTilemapTileset } from '../../tilemap/tilesetCache';
import { log } from '../../logger';
export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
@@ -122,4 +122,10 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
unload(_asset: TilemapResult): void {
// Tilemap sources registered globally
}
+
+ /** Hot reload: sever the global source registration too — the Assets-level
+ * cache drop alone would leave the tilemap sync rendering the stale parse. */
+ invalidate(path: string): boolean {
+ return unregisterTilemapSource(path);
+ }
}
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index 871ca8b15..4d9a49be2 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -9,7 +9,7 @@ import { initTilemapAPI, shutdownTilemapAPI, TilemapAPI } from './tilemapAPI';
import { TilemapLiveSync } from './tilemapLiveSync';
import { Tilemap } from './components';
import { registerSceneComponentCodec } from '../scene';
-import { getTilemapSource, getResolvedTileset } from './tilesetCache';
+import { getTilemapSource, getResolvedTileset, type LoadedTilemapSource } from './tilesetCache';
import { resolveTilesetModel } from './tilesetResolve';
import {
generateLayerCollision, generateChunkCollision, generateChunkPolygonCollision,
@@ -43,6 +43,12 @@ export class TilemapPlugin implements Plugin {
private animatedLayers_ = new Set<number>();
/** Tilemap(source) entity → the RuntimeOnly child layer entities derived from its `.tmj`. */
private sourceLayerEntities_ = new Map<number, Entity[]>();
+ /** Tilemap(source) entity → the cached source OBJECT its children were derived
+ * from. Identity is the change detector: a `source` field edit resolves to a
+ * different object, a hot reload re-registers a fresh one, an invalidation
+ * leaves none — all must tear down + re-derive (the old sync derived once
+ * and rendered the stale parse forever). */
+ private sourceDerivedFrom_ = new Map<number, LoadedTilemapSource>();
/** tilemap entity → the static collider entities derived from its collidable tiles (play-mode only). */
private collisionEntities_ = new Map<number, Entity[]>();
/** TilemapLayer entity → its baked collidable tile ids (out-of-band scene data; drives native collision). */
@@ -283,12 +289,21 @@ export class TilemapPlugin implements Plugin {
if (world.tryGet(entity, TilemapLayer)) continue;
const tilemap = world.tryGet(entity, Tilemap) as { source: string } | null;
- if (!tilemap?.source) continue;
// The loader keys the source cache by the RESOLVED path and
// `resolveSceneAssetPaths` leaves `source` as the authored ref, so
// resolve at lookup (see resolveAssetKey), falling back to the raw ref.
- const cached = getTilemapSource(resolveAssetKey(assets, tilemap.source)) ?? getTilemapSource(tilemap.source);
+ const cached = tilemap?.source
+ ? getTilemapSource(resolveAssetKey(assets, tilemap.source)) ?? getTilemapSource(tilemap.source)
+ : undefined;
+
+ // Derived children must mirror the CURRENT source. A cleared field,
+ // an invalidated cache entry (hot reload), or different source data
+ // (live `source` edit / fresh registration) all tear down here; the
+ // derive below rebuilds from whatever is cached now.
+ if (sourceLayerEntities.has(entity) && this.sourceDerivedFrom_.get(entity) !== cached) {
+ this.teardownDerived_(world, entity);
+ }
if (!cached) continue;
if (!sourceLayerEntities.has(entity)) {
@@ -444,6 +459,7 @@ export class TilemapPlugin implements Plugin {
}
}
sourceLayerEntities.set(entity, children);
+ this.sourceDerivedFrom_.set(entity, cached);
}
const hasTileCollision = !!(cached.collisionTileIds && cached.collisionTileIds.length > 0);
@@ -485,26 +501,8 @@ export class TilemapPlugin implements Plugin {
}
const currentTilemapSet = new Set(tilemapEntities);
- for (const [entity, children] of sourceLayerEntities) {
- if (!currentTilemapSet.has(entity)) {
- for (const child of children) {
- if (initializedLayers.has(child)) {
- TilemapAPI.destroyLayer(child);
- initializedLayers.delete(child);
- }
- animatedLayers.delete(child);
- // An owner despawn cascades to its children; only a
- // component removal leaves them alive to clean up here.
- if (world.valid(child)) world.despawn(child);
- }
- sourceLayerEntities.delete(entity);
-
- const colliders = collisionEntities.get(entity);
- if (colliders) {
- for (const e of colliders) world.despawn(e);
- collisionEntities.delete(entity);
- }
- }
+ for (const entity of [...sourceLayerEntities.keys()]) {
+ if (!currentTilemapSet.has(entity)) this.teardownDerived_(world, entity);
}
if (animatedLayers.size > 0) {
@@ -519,6 +517,34 @@ export class TilemapPlugin implements Plugin {
app.addSystemToSchedule(Schedule.PreUpdate, tilemapSyncSystem);
}
+ /** Drop ONE tilemap entity's derived artifacts (child layer entities +
+ * play-mode colliders + bookkeeping) so the sync can re-derive — or not,
+ * if its source is gone. Fires when the Tilemap component disappears AND
+ * when the source it derived from stops being current. */
+ private teardownDerived_(
+ world: { valid(e: Entity): boolean; despawn(e: Entity): void },
+ entity: number,
+ ): void {
+ for (const child of this.sourceLayerEntities_.get(entity) ?? []) {
+ if (this.initializedLayers_.has(child)) {
+ TilemapAPI.destroyLayer(child);
+ this.initializedLayers_.delete(child);
+ }
+ this.animatedLayers_.delete(child);
+ // An owner despawn cascades to its children; only a component
+ // removal leaves them alive to clean up here.
+ if (world.valid(child)) world.despawn(child);
+ }
+ this.sourceLayerEntities_.delete(entity);
+ this.sourceDerivedFrom_.delete(entity);
+
+ const colliders = this.collisionEntities_.get(entity);
+ if (colliders) {
+ for (const e of colliders) if (world.valid(e)) world.despawn(e);
+ this.collisionEntities_.delete(entity);
+ }
+ }
+
resetLayers(): void {
for (const entity of this.initializedLayers_) {
TilemapAPI.destroyLayer(entity);
@@ -527,6 +553,7 @@ export class TilemapPlugin implements Plugin {
this.appliedCellSize_.clear();
this.animatedLayers_.clear();
this.sourceLayerEntities_.clear();
+ this.sourceDerivedFrom_.clear();
// Collider entities die with the world on reset/teardown; just drop our bookkeeping.
this.collisionEntities_.clear();
this.nativeCollisionIds_.clear();
diff --git a/sdk/src/tilemap/tilesetCache.ts b/sdk/src/tilemap/tilesetCache.ts
index ce8e202b5..a0159a259 100644
--- a/sdk/src/tilemap/tilesetCache.ts
+++ b/sdk/src/tilemap/tilesetCache.ts
@@ -61,6 +61,13 @@ export function getTilemapSource(path: string): LoadedTilemapSource | undefined
return tilemapCache_.get(path);
}
+/** Drop one source (hot reload: the `.tmj` changed on disk). The tilemap sync
+ * notices the entry vanish and tears the derived layers down; the reload
+ * registers fresh data and they re-derive. Returns true if the path was held. */
+export function unregisterTilemapSource(path: string): boolean {
+ return tilemapCache_.delete(path);
+}
+
export function clearTilemapSourceCache(): void {
tilemapCache_.clear();
}
diff --git a/sdk/tests/tilemap-source-invalidate.test.ts b/sdk/tests/tilemap-source-invalidate.test.ts
new file mode 100644
index 000000000..363f46a43
--- /dev/null
+++ b/sdk/tests/tilemap-source-invalidate.test.ts
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Tilemap source hot-reload contract: `Assets.invalidate` reaches the
+ * loader's `invalidate`, which must sever the GLOBAL source registration
+ * (tilesetCache) too — dropping only the Assets-level cache would leave
+ * the tilemap sync rendering the stale parse forever. The sync detects
+ * the vanished/replaced entry by object identity and re-derives.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+ registerTilemapSource, getTilemapSource, unregisterTilemapSource,
+ clearTilemapSourceCache, type LoadedTilemapSource,
+} from '../src/tilemap/tilesetCache';
+import { TilemapAssetLoader } from '../src/asset/loaders/TilemapAssetLoader';
+
+const SRC: LoadedTilemapSource = {
+ tileWidth: 16, tileHeight: 16, layers: [], tilesets: [],
+};
+
+afterEach(() => clearTilemapSourceCache());
+
+describe('tilemap source invalidation', () => {
+ it('unregisterTilemapSource drops the entry and reports whether it was held', () => {
+ registerTilemapSource('assets/maps/level.tmj', SRC);
+ expect(getTilemapSource('assets/maps/level.tmj')).toBe(SRC);
+ expect(unregisterTilemapSource('assets/maps/level.tmj')).toBe(true);
+ expect(getTilemapSource('assets/maps/level.tmj')).toBeUndefined();
+ expect(unregisterTilemapSource('assets/maps/level.tmj')).toBe(false);
+ });
+
+ it('TilemapAssetLoader.invalidate severs the global registration', () => {
+ const loader = new TilemapAssetLoader();
+ registerTilemapSource('assets/maps/level.tmj', SRC);
+ expect(loader.invalidate('assets/maps/level.tmj')).toBe(true);
+ expect(getTilemapSource('assets/maps/level.tmj')).toBeUndefined();
+ expect(loader.invalidate('assets/maps/level.tmj')).toBe(false);
+ });
+
+ it('a re-registered source is a NEW object — the identity the sync re-derives on', () => {
+ registerTilemapSource('assets/maps/level.tmj', SRC);
+ const before = getTilemapSource('assets/maps/level.tmj');
+ const fresh: LoadedTilemapSource = { ...SRC };
+ registerTilemapSource('assets/maps/level.tmj', fresh);
+ expect(getTilemapSource('assets/maps/level.tmj')).toBe(fresh);
+ expect(getTilemapSource('assets/maps/level.tmj')).not.toBe(before);
+ });
+});