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): hide .meta sidecars via a single content-visibility policy

esengine1da68f426092
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.ts
index 710fe8765..7bc9ed401 100644
--- a/desktop/electron/assetDb.ts
+++ b/desktop/electron/assetDb.ts
@@ -18,14 +18,11 @@
*/
import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
import path from 'node:path';
+import { META_EXT, isContentDir } from './contentPolicy';
/** Local, gitignored cache inside the project (next to workspace.json). */
const CACHE_DIR = '.esengine/cache';
const OUTPUT = 'assets.json';
-/** Dirs never scanned for assets — code/build/vcs, not content. */
-const SKIP_DIRS = new Set([
- 'node_modules', '.git', '.esengine', 'dist', 'dist-electron', 'build', '.vscode', '.cache',
-]);
const UUID_PREFIX = '@uuid:';
const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -67,9 +64,9 @@ async function* walkMeta(root: string, rel = ''): AsyncGenerator<string> {
}
for (const e of entries) {
if (e.isDirectory()) {
- if (SKIP_DIRS.has(e.name)) continue;
+ if (!isContentDir(e.name)) continue;
yield* walkMeta(root, rel ? `${rel}/${e.name}` : e.name);
- } else if (e.name.endsWith('.meta')) {
+ } else if (e.name.endsWith(META_EXT)) {
yield rel ? `${rel}/${e.name}` : e.name;
}
}
diff --git a/desktop/electron/contentPolicy.ts b/desktop/electron/contentPolicy.ts
new file mode 100644
index 000000000..6cbbeff0e
--- /dev/null
+++ b/desktop/electron/contentPolicy.ts
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Single authority on what counts as browsable project CONTENT.
+ *
+ * Four enumerators walk the project — the Content Browser's readDir, its
+ * subtree search, the AssetDatabase scan, and the fs watcher — and must agree
+ * on what is visible: `.meta` sidecars are asset-pipeline internals (identity
+ * travels with its asset through rename/duplicate/trash, never shown as its
+ * own entry), dot entries are editor/VCS plumbing, and code/build output dirs
+ * are not content. Any divergence is a user-visible bug (e.g. `.meta` files
+ * appearing in the Content Browser). Pure (no I/O) → unit-testable.
+ */
+
+/** Sidecar suffix carrying an asset's uuid/type/importer (see assetDb). */
+export const META_EXT = '.meta';
+
+/** Non-dot dirs that are never content (code deps / build output); dot dirs
+ * (`.esengine`, `.git`, …) are excluded by the dot rule. */
+const NON_CONTENT_DIRS = new Set(['node_modules', 'dist', 'dist-electron', 'build']);
+
+export const isContentDir = (name: string): boolean =>
+ !name.startsWith('.') && !NON_CONTENT_DIRS.has(name);
+
+export const isContentFile = (name: string): boolean =>
+ !name.startsWith('.') && !name.endsWith(META_EXT);
+
+/**
+ * True when any segment of a project-relative path leaves content space —
+ * the watcher's noise filter. Note `.meta` files themselves ARE watched:
+ * an external sidecar edit (git pull) must re-scan the asset registry.
+ */
+export function isNonContentPath(rel: string): boolean {
+ return rel
+ .replace(/\\/g, '/')
+ .split('/')
+ .some((seg) => seg.startsWith('.') || NON_CONTENT_DIRS.has(seg));
+}
diff --git a/desktop/electron/projectFs.ts b/desktop/electron/projectFs.ts
index d86b7e1a5..660448455 100644
--- a/desktop/electron/projectFs.ts
+++ b/desktop/electron/projectFs.ts
@@ -22,6 +22,9 @@ import {
type WorkspaceState,
type DirEntry,
} from '../src/project/format';
+import { META_EXT, isContentDir, isContentFile } from './contentPolicy';
+
+export { META_EXT };
/**
* Resolve a project-relative path, refusing anything that escapes `root`.
@@ -72,14 +75,14 @@ export async function writeInRoot(root: string, relPath: string, contents: strin
await writeFile(abs, contents, 'utf8');
}
+/** Browsable entries only (contentPolicy) — the Content Browser's folder view. */
export async function readDirInRoot(root: string, relPath: string): Promise<DirEntry[]> {
const entries = await readdir(resolveInRoot(root, relPath), { withFileTypes: true });
- return entries.map((e) => ({ name: e.name, isDir: e.isDirectory() }));
+ return entries
+ .filter((e) => (e.isDirectory() ? isContentDir(e.name) : isContentFile(e.name)))
+ .map((e) => ({ name: e.name, isDir: e.isDirectory() }));
}
-/** Sidecar suffix carrying an asset's uuid/type/importer (see assetDb). */
-export const META_EXT = '.meta';
-
/** Project-relative, forward-slashed form of an absolute path under `root`. */
const toRel = (root: string, abs: string): string => path.relative(root, abs).split(path.sep).join('/');
@@ -92,14 +95,15 @@ async function* walkFiles(absDir: string): AsyncGenerator<string> {
}
}
-// Recursively yield project-relative paths of visible files (skips dot dirs/files —
-// `.esengine`, `.meta` sidecars — that aren't browsable assets).
+// Recursively yield project-relative paths of browsable files (contentPolicy).
async function* walkVisible(absDir: string, root: string): AsyncGenerator<string> {
for (const e of await readdir(absDir, { withFileTypes: true })) {
- if (e.name.startsWith('.')) continue;
const p = path.join(absDir, e.name);
- if (e.isDirectory()) yield* walkVisible(p, root);
- else if (!e.name.endsWith(META_EXT)) yield toRel(root, p);
+ if (e.isDirectory()) {
+ if (isContentDir(e.name)) yield* walkVisible(p, root);
+ } else if (isContentFile(e.name)) {
+ yield toRel(root, p);
+ }
}
}
diff --git a/desktop/electron/projectWatcher.ts b/desktop/electron/projectWatcher.ts
index 6a2730deb..32a4bd64e 100644
--- a/desktop/electron/projectWatcher.ts
+++ b/desktop/electron/projectWatcher.ts
@@ -16,17 +16,13 @@
*/
import { watch, type FSWatcher } from 'node:fs';
import type { WebContents } from 'electron';
+import { isNonContentPath } from './contentPolicy';
// Our own cache writes (assets.json / schemas.json / scripts.mjs under
-// `.esengine`) MUST be ignored — refreshing on them would loop. Plus the usual
-// heavy/irrelevant noise dirs.
-const IGNORED = ['.esengine', 'node_modules', '.git', 'dist', 'build'];
-
-/** True if a project-relative path is watcher noise (an ignored dir or its tree). */
-export function isIgnoredPath(rel: string): boolean {
- const norm = rel.replace(/\\/g, '/');
- return IGNORED.some((d) => norm === d || norm.startsWith(`${d}/`));
-}
+// `.esengine`) MUST be ignored — refreshing on them would loop; contentPolicy's
+// dot rule covers that plus the usual heavy noise dirs.
+/** True if a project-relative path is watcher noise (outside content space). */
+export const isIgnoredPath = isNonContentPath;
const DEBOUNCE_MS = 180;
diff --git a/desktop/tests/project-fs.test.ts b/desktop/tests/project-fs.test.ts
index 14f35a211..4ac915ac0 100644
--- a/desktop/tests/project-fs.test.ts
+++ b/desktop/tests/project-fs.test.ts
@@ -12,6 +12,8 @@ import { tmpdir } from 'node:os';
import path from 'node:path';
import {
resolveInRoot,
+ readDirInRoot,
+ listFilesInRoot,
renameInRoot,
mkdirInRoot,
duplicateInRoot,
@@ -65,6 +67,25 @@ describe('importAssets', () => {
});
});
+describe('content visibility (contentPolicy)', () => {
+ beforeEach(() => {
+ // Pipeline internals + non-content dirs that must never surface as entries.
+ writeFileSync(path.join(root, 'assets', '.DS_Store'), '');
+ mkdirSync(path.join(root, '.esengine'));
+ mkdirSync(path.join(root, 'node_modules', 'pkg'), { recursive: true });
+ writeFileSync(path.join(root, 'node_modules', 'pkg', 'icon.png'), 'PNG');
+ });
+
+ it('readDir hides .meta sidecars, dot entries and non-content dirs', async () => {
+ expect((await readDirInRoot(root, '')).map((e) => e.name)).toEqual(['assets']);
+ expect((await readDirInRoot(root, 'assets')).map((e) => e.name)).toEqual(['hero.png']);
+ });
+
+ it('subtree search agrees with readDir (same policy)', async () => {
+ expect(await listFilesInRoot(root, '')).toEqual(['assets/hero.png']);
+ });
+});
+
describe('isIgnoredPath (watcher noise filter)', () => {
it('ignores the editor cache + heavy dirs (no refresh loop)', () => {
// `.esengine` is where we write assets.json — refreshing on it would loop.