Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(editor): reading a project file answers, or says what is wrong

yhhb4d2fd115d23
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.ts
index c9334caaf..aa63556b0 100644
--- a/desktop/electron/assetDb.ts
+++ b/desktop/electron/assetDb.ts
@@ -19,6 +19,7 @@
import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import path from 'node:path';
+import { readTextInRoot } from './projectFs';
import { META_EXT, isContentDir, isContentFile, isNonContentPath } from './contentPolicy';
import { adoptOrphan } from './assetMeta';
// The runtime's tileset-path resolver (a dependency-free leaf) — shared so the dep scan
@@ -246,13 +247,13 @@ async function computeDeps(
try {
const refs = new Set<string>();
if (isSpineAtlas) {
- const content = await readFile(path.join(root, entry.path), 'utf8');
+ const content = await readTextInRoot(path.join(root, entry.path));
for (const page of parseSpineAtlasPages(content)) {
const dep = byPath.get(normalizeRefPath(resolveRelativePath(entry.path, page)));
if (dep) refs.add(dep.uuid);
}
} else {
- const json = JSON.parse(await readFile(path.join(root, entry.path), 'utf8'));
+ const json = JSON.parse(await readTextInRoot(path.join(root, entry.path)));
collectRefs(json, refs, (ref) => {
if (ref.includes('://')) return null;
const direct = byPath.get(normalizeRefPath(ref));
@@ -359,7 +360,7 @@ export async function scanAssetDatabase(
const walkResults = await mapLimit(metaRels, SCAN_IO_CONCURRENCY, async (metaRel): Promise<WalkResult> => {
let meta: { uuid?: unknown; type?: unknown; importer?: unknown };
try {
- meta = JSON.parse(await readFile(path.join(root, metaRel), 'utf8'));
+ meta = JSON.parse(await readTextInRoot(path.join(root, metaRel)));
} catch (err) {
return { warning: `${metaRel}: ${err instanceof Error ? err.message : String(err)}` };
}
@@ -488,7 +489,7 @@ export async function updateAssetIndex(
}
let meta: { uuid?: unknown; type?: unknown; importer?: unknown };
try {
- meta = JSON.parse(await readFile(abs + META_EXT, 'utf8'));
+ meta = JSON.parse(await readTextInRoot(abs + META_EXT));
} catch {
continue; // unreadable/partial .meta — a later event will settle it
}
diff --git a/desktop/electron/projectFs.ts b/desktop/electron/projectFs.ts
index d04f4ebc4..3cd677ede 100644
--- a/desktop/electron/projectFs.ts
+++ b/desktop/electron/projectFs.ts
@@ -41,13 +41,32 @@ export function resolveInRoot(root: string, relPath: string): string {
return resolved;
}
+/**
+ * Read a project file as text, without the byte-order mark.
+ *
+ * A BOM is an encoding hint, not content — but `JSON.parse` treats it as a
+ * syntax error, and every Windows tool that touches a file can leave one:
+ * Notepad, `Out-File`, a spreadsheet export, an editor with "UTF-8 with BOM"
+ * selected. Reading a project someone had edited that way failed with
+ * `Unexpected token ''` and nothing that named the file, which reads as
+ * "the editor cannot open my project".
+ *
+ * Stripped HERE — the one door every project read goes through, in both
+ * processes (the renderer's `fs.read` is this over IPC) — rather than at each
+ * JSON.parse, because the parses are many and the door is one.
+ */
+export async function readTextInRoot(abs: string): Promise<string> {
+ const text = await readFile(abs, 'utf8');
+ return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
/** Require + parse a project's `project.esproject` manifest (no workspace load). */
export async function readManifest(root: string): Promise<ProjectManifest> {
const manifestPath = path.join(root, PROJECT_MANIFEST_FILE);
if (!existsSync(manifestPath)) {
throw new Error(`not an Estella project (missing ${PROJECT_MANIFEST_FILE}): ${root}`);
}
- return parseManifest(JSON.parse(await readFile(manifestPath, 'utf8')));
+ return parseManifest(JSON.parse(await readTextInRoot(manifestPath)));
}
/** Open a project: require + parse `project.esproject`, load workspace if present. */
@@ -58,7 +77,7 @@ export async function openProject(root: string): Promise<OpenedProject> {
const wsPath = path.join(root, WORKSPACE_DIR, WORKSPACE_FILE);
if (existsSync(wsPath)) {
try {
- workspace = JSON.parse(await readFile(wsPath, 'utf8')) as WorkspaceState;
+ workspace = JSON.parse(await readTextInRoot(wsPath)) as WorkspaceState;
} catch {
// A corrupt workspace file is non-fatal — start clean.
}
@@ -67,7 +86,7 @@ export async function openProject(root: string): Promise<OpenedProject> {
}
export function readInRoot(root: string, relPath: string): Promise<string> {
- return readFile(resolveInRoot(root, relPath), 'utf8');
+ return readTextInRoot(resolveInRoot(root, relPath));
}
/**
@@ -82,7 +101,7 @@ export function readInRoot(root: string, relPath: string): Promise<string> {
*/
export async function readOptionalInRoot(root: string, relPath: string): Promise<string | null> {
try {
- return await readFile(resolveInRoot(root, relPath), 'utf8');
+ return await readTextInRoot(resolveInRoot(root, relPath));
} catch (e) {
if ((e as NodeJS.ErrnoException)?.code === 'ENOENT') return null;
throw e;
@@ -129,9 +148,18 @@ async function* walkVisible(absDir: string, root: string): AsyncGenerator<string
/** Project-relative paths of every browsable file under `relDir`, recursively —
* backs the Content Browser's project-wide (subtree) search. */
+/**
+ * Every visible file under a project directory. A directory that does not exist
+ * lists as EMPTY rather than throwing: "what is in src/?" is a question, and a
+ * project that has no src/ answers it with "nothing" — the raw
+ * `ENOENT ... scandir` that came back instead read as a broken tool to whoever
+ * asked, which is exactly how an agent's first orienting call failed.
+ */
export async function listFilesInRoot(root: string, relDir: string): Promise<string[]> {
+ const abs = resolveInRoot(root, relDir);
+ if (!existsSync(abs)) return [];
const out: string[] = [];
- for await (const rel of walkVisible(resolveInRoot(root, relDir), root)) out.push(rel);
+ for await (const rel of walkVisible(abs, root)) out.push(rel);
return out;
}
@@ -161,7 +189,7 @@ export async function mkdirInRoot(root: string, relPath: string): Promise<void>
/** Assign a fresh uuid to a `.meta` file (a duplicated asset must not share one). */
async function regenMetaUuid(metaAbs: string): Promise<void> {
try {
- const meta = JSON.parse(await readFile(metaAbs, 'utf8'));
+ const meta = JSON.parse(await readTextInRoot(metaAbs));
meta.uuid = randomUUID();
await writeFile(metaAbs, JSON.stringify(meta, null, 2) + '\n', 'utf8');
} catch {
diff --git a/desktop/tests/bom-project-files.test.ts b/desktop/tests/bom-project-files.test.ts
new file mode 100644
index 000000000..20a0ba899
--- /dev/null
+++ b/desktop/tests/bom-project-files.test.ts
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A byte-order mark is an encoding hint, not content.
+ *
+ * Every Windows tool that touches a file can leave one — Notepad, PowerShell's
+ * `Out-File`, an editor with "UTF-8 with BOM" selected — and `JSON.parse` calls
+ * it a syntax error. A project whose manifest had been edited that way failed to
+ * open with `Unexpected token ''` and nothing naming the file, which reads
+ * as "the editor cannot open my project". Caught by a dogfood run whose fixture
+ * PowerShell happened to write.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { readManifest, openProject, readInRoot, readOptionalInRoot } from '../electron/projectFs';
+
+const BOM = '';
+let root: string;
+
+beforeAll(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-bom-'));
+ mkdirSync(path.join(root, 'assets', 'scenes'), { recursive: true });
+ mkdirSync(path.join(root, '.esengine'), { recursive: true });
+ writeFileSync(path.join(root, 'project.esproject'),
+ BOM + JSON.stringify({ formatVersion: '1', name: 'Bommed', defaultScene: 'assets/scenes/main.esscene' }));
+ writeFileSync(path.join(root, '.esengine', 'workspace.json'),
+ BOM + JSON.stringify({ lastOpenedScene: 'assets/scenes/main.esscene' }));
+ writeFileSync(path.join(root, 'assets', 'scenes', 'main.esscene'),
+ BOM + JSON.stringify({ version: '1.0', name: 'Main', entities: [] }));
+});
+
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+describe('project files written with a BOM', () => {
+ it('opens a manifest that carries one', async () => {
+ const manifest = await readManifest(root);
+ expect(manifest.name).toBe('Bommed');
+ });
+
+ it('opens the project, workspace and all', async () => {
+ const opened = await openProject(root);
+ expect(opened.manifest.name).toBe('Bommed');
+ expect(opened.workspace.lastOpenedScene).toBe('assets/scenes/main.esscene');
+ });
+
+ // The renderer reads every scene, material and prefab through this door, so
+ // one strip here is what keeps a BOM out of every parse downstream.
+ it('hands a scene to the renderer without it', async () => {
+ const text = await readInRoot(root, 'assets/scenes/main.esscene');
+ expect(text.charCodeAt(0)).not.toBe(0xfeff);
+ expect(JSON.parse(text).name).toBe('Main');
+ const optional = await readOptionalInRoot(root, 'assets/scenes/main.esscene');
+ expect(optional?.charCodeAt(0)).not.toBe(0xfeff);
+ });
+
+ it('leaves a file that has no BOM exactly as it is', async () => {
+ writeFileSync(path.join(root, 'plain.txt'), 'no mark here');
+ expect(await readInRoot(root, 'plain.txt')).toBe('no mark here');
+ });
+});