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
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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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: strinconst 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.tsindex 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 projectdiff --git a/desktop/electron/projectWatcher.ts b/desktop/electron/projectWatcher.tsindex 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.mjsindex 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.mjsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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 === rawEngineHost.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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 | undefinedreturn 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.tsnew file mode 100644index 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);+ });+});