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): a project names folders its asset database leaves alone

yhh582ee81edfd7
diff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdx
index 8edc9bcfc..8fe835733 100644
--- a/docs/astro/src/content/docs/assets/overview.mdx
+++ b/docs/astro/src/content/docs/assets/overview.mdx
@@ -11,6 +11,18 @@ runtime resolves references through a **manifest**, typed **loaders** turn a
reference into a usable handle, and **reference counting** frees what's no longer
used. This guide covers each piece.
+## Keeping a folder out of the asset database
+
+A project often holds more than content: a source-art repository, docs, a server. The editor gives every file under the project a `.meta` sidecar, so a
+folder of that kind fills with them. List such folders in the manifest and the asset database leaves them alone: it does not index them, does not write a
+`.meta` into them and does not watch them.
+
+```json
+{ "assetExclude": ["art", "docs", "server"] }
+```
+
+Entries are folders relative to the project root; everything under one is excluded. Content stays under the folders you do not list (normally `assets/`).
+
## Referencing assets
In code, reference an asset by its **project-relative path** — readable, and what
diff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
index f58a77b14..5ddb8c3ab 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
@@ -9,6 +9,17 @@ import { Aside } from '@astrojs/starlight/components';
(cook)游戏能触达的部分,运行时通过**清单(manifest)**解析引用,按类型的**加载器**
把引用变成可用句柄,**引用计数**再释放不再用的资源。本篇逐一讲清。
+## 把文件夹排除在资源库之外
+
+项目里往往不止有内容:还有美术源文件仓库、文档、服务端。编辑器会给项目下每个文件配一个 `.meta` 旁注文件,这类文件夹就会被塞满。把它们写进清单,资源库就不再理会:
+不索引、不往里写 `.meta`、也不监视。
+
+```json
+{ "assetExclude": ["art", "docs", "server"] }
+```
+
+条目是相对项目根的文件夹,其下一切都被排除。内容仍放在没列出的文件夹里(通常是 `assets/`)。
+
## 引用资源
在代码里,按资源的**项目相对路径**引用它——可读,也是你平常会写的。这个路径相对的是
diff --git a/pipeline/src/assets/assetDb.ts b/pipeline/src/assets/assetDb.ts
index 8697297f2..4f1394f8d 100644
--- a/pipeline/src/assets/assetDb.ts
+++ b/pipeline/src/assets/assetDb.ts
@@ -21,9 +21,9 @@ import type { Dirent } from 'node:fs';
import { existsSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import path from 'node:path';
-import { readTextInRoot } from '../project/readProject';
+import { readManifest, readTextInRoot } from '../project/readProject';
import { isInsideRoot } from '../fs/pathSandbox';
-import { META_EXT, isContentDir, isContentFile, isNonContentPath } from './contentPolicy';
+import { META_EXT, isContentDir, isContentFile, isExcludedByProject, isNonContentPath } 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.
@@ -141,7 +141,7 @@ function leavesProject(root: string, dirent: Dirent, abs: string): boolean {
}
/** Recursively yield every `<file>.meta` path (project-relative, forward-slashed). */
-async function* walkMeta(root: string, rel = ''): AsyncGenerator<string> {
+async function* walkMeta(root: string, rel = '', exclude?: readonly string[]): AsyncGenerator<string> {
const abs = rel ? path.join(root, rel) : root;
let entries;
try {
@@ -157,7 +157,8 @@ async function* walkMeta(root: string, rel = ''): AsyncGenerator<string> {
if (escaped.has(e.name)) continue;
if (e.isDirectory()) {
if (!isContentDir(e.name)) continue;
- yield* walkMeta(root, rel ? `${rel}/${e.name}` : e.name);
+ if (isExcludedByProject(rel ? `${rel}/${e.name}` : e.name, exclude)) continue;
+ yield* walkMeta(root, rel ? `${rel}/${e.name}` : e.name, exclude);
} else if (e.name.endsWith(META_EXT)) {
// A sidecar is an ordinary file even when the content beside it is a link
// out. Indexing it would put that link's path in the registry, and the cook
@@ -176,7 +177,7 @@ async function* walkMeta(root: string, rel = ''): AsyncGenerator<string> {
* 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[]> {
+async function adoptOrphans(root: string, rel = '', adopted: string[] = [], exclude?: readonly string[]): Promise<string[]> {
const abs = rel ? path.join(root, rel) : root;
let entries;
try {
@@ -189,7 +190,8 @@ async function adoptOrphans(root: string, rel = '', adopted: string[] = []): Pro
if (leavesProject(root, e, path.join(abs, e.name))) continue;
if (e.isDirectory()) {
if (!isContentDir(e.name)) continue;
- await adoptOrphans(root, relPath, adopted);
+ if (isExcludedByProject(relPath, exclude)) continue;
+ await adoptOrphans(root, relPath, adopted, exclude);
} else if (isContentFile(e.name)) {
// The project-root thumbnail.png is the editor-managed launcher cover
// (rewritten on every scene save), not an asset — adopting it would put
@@ -431,6 +433,15 @@ export async function readCachedAssetIndex(root: string): Promise<AssetIndex | n
return null;
}
+/** The folders the project's manifest takes out of content; none for a project with no manifest or one that cannot be read (the scan then sees everything, as before). */
+async function excludedFolders(root: string): Promise<readonly string[] | undefined> {
+ try {
+ return (await readManifest(root)).assetExclude;
+ } catch {
+ return undefined;
+ }
+}
+
/**
* Scan `root` for `.meta` sidecars → build the asset index (registry + dep
* graph) and (unless `write: false`) write `.esengine/cache/assets.json`.
@@ -450,14 +461,15 @@ export async function scanAssetDatabase(
// 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);
+ const exclude = await excludedFolders(root);
+ const adopted = opts?.adopt === false ? [] : await adoptOrphans(root, '', [], exclude);
t.adopt = performance.now() - tStart;
const tWalk = performance.now();
// The generator walk is just readdir (cheap); the readFile+parse per .meta is
// the cost — run those in parallel, then assemble deterministically in order.
const metaRels: string[] = [];
- for await (const metaRel of walkMeta(root)) metaRels.push(metaRel);
+ for await (const metaRel of walkMeta(root, '', exclude)) metaRels.push(metaRel);
type WalkResult = { entry?: AssetEntry; warning?: string };
const walkResults = await mapLimit(metaRels, SCAN_IO_CONCURRENCY, async (metaRel): Promise<WalkResult> => {
let meta: { uuid?: unknown; type?: unknown; importer?: unknown };
@@ -546,6 +558,7 @@ export async function updateAssetIndex(
reason,
});
+ const exclude = await excludedFolders(root);
if (changed.length === 0) return full('watcher overflow (no paths)');
if (changed.length > INCREMENTAL_PATH_LIMIT) return full(`bulk change (${changed.length} paths)`);
@@ -554,7 +567,7 @@ export async function updateAssetIndex(
const contentPaths = new Set<string>();
for (const raw of changed) {
const rel = raw.replace(/\\/g, '/');
- if (isNonContentPath(rel)) continue;
+ if (isNonContentPath(rel, exclude)) continue;
const abs = path.join(root, rel);
let st: Awaited<ReturnType<typeof stat>> | null;
try { st = await stat(abs); } catch { st = null; }
diff --git a/pipeline/src/assets/contentPolicy.ts b/pipeline/src/assets/contentPolicy.ts
index c03eeb0db..5c50729d4 100644
--- a/pipeline/src/assets/contentPolicy.ts
+++ b/pipeline/src/assets/contentPolicy.ts
@@ -29,12 +29,23 @@ const isBuildOutputDir = (name: string): boolean => name.startsWith('dist-');
export const isContentDir = (name: string): boolean =>
!name.startsWith('.') && !NON_CONTENT_DIRS.has(name) && !isBuildOutputDir(name);
+/**
+ * Whether a project-relative path is under a folder its manifest excludes from content (`assetExclude`): art sources, documents, tools. The excluded
+ * folder itself counts, so the walkers do not enter it.
+ */
+export function isExcludedByProject(rel: string, exclude: readonly string[] | undefined): boolean {
+ if (!exclude || exclude.length === 0) return false;
+ const p = rel.replace(/\\/g, '/');
+ return exclude.some((folder) => p === folder || p.startsWith(`${folder}/`));
+}
+
export const isContentFile = (name: string): boolean =>
!name.startsWith('.') && !name.endsWith(META_EXT);
/** True when any path segment leaves content space.
* `.meta` files themselves stay content — an external edit must re-scan. */
-export function isNonContentPath(rel: string): boolean {
+export function isNonContentPath(rel: string, exclude?: readonly string[]): boolean {
+ if (isExcludedByProject(rel, exclude)) return true;
return rel
.replace(/\\/g, '/')
.split('/')
diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.ts
index d5cb0afa1..d74d54582 100644
--- a/pipeline/src/project/format.ts
+++ b/pipeline/src/project/format.ts
@@ -513,6 +513,11 @@ export interface ProjectManifest {
spineVersion?: string;
/** Per-path overrides of {@link DEFAULT_LAYOUT}. */
layout?: Partial<ProjectLayout>;
+ /**
+ * Folders, relative to the project root and `/` separated, that are not the game's content: art sources, documents, tools. The asset database does
+ * not scan, adopt or watch what is under them, so the editor does not write a `.meta` beside every file there.
+ */
+ assetExclude?: string[];
/** Declaration/startup entry points (defaults in {@link DEFAULT_SCRIPTS}). */
scripts?: ProjectScripts;
/** One-line summary, shown when the project is used as a New-project template. */
@@ -735,6 +740,14 @@ export function parseManifest(raw: unknown): ProjectManifest {
if (o.layout && typeof o.layout === 'object') {
manifest.layout = o.layout as Partial<ProjectLayout>;
}
+ if (Array.isArray(o.assetExclude)) {
+ // Normalised to the one spelling the walkers compare with; an entry that names nothing is dropped, not an error.
+ const folders = (o.assetExclude as unknown[])
+ .filter((f): f is string => typeof f === 'string')
+ .map((f) => f.replace(/\\/g, '/').replace(/^\.?\/+|\/+$/g, ''))
+ .filter((f) => f.length > 0 && !f.split('/').includes('..'));
+ if (folders.length > 0) manifest.assetExclude = folders;
+ }
if (Array.isArray(o.acceptance)) {
// Dropped rather than failing the load, like the presets above: a
// hand-edited claim must not cost anyone their project. A claim that
diff --git a/pipeline/tests/asset-exclude.test.ts b/pipeline/tests/asset-exclude.test.ts
new file mode 100644
index 000000000..9ebefe078
--- /dev/null
+++ b/pipeline/tests/asset-exclude.test.ts
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file `assetExclude`: folders a project keeps beside its content that the asset database must not see — a source-art
+ * repository, docs, a server. Out of the scan, out of orphan adoption (no `.meta` is written into them), out of
+ * the watcher's set of content paths.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { scanAssetDatabase } from '../src/assets/assetDb';
+import { isExcludedByProject, isNonContentPath } from '../src/assets/contentPolicy';
+import { parseManifest } from '../src/project/format';
+
+let root: string;
+beforeEach(() => { root = mkdtempSync(path.join(tmpdir(), 'estella-exclude-')); });
+afterEach(() => { rmSync(root, { recursive: true, force: true }); });
+
+function put(rel: string, body = 'x'): void {
+ const abs = path.join(root, rel);
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, body);
+}
+
+describe('the manifest field', () => {
+ it('keeps folder names, and drops empty ones and any that climb out of the project', () => {
+ const m = parseManifest({ name: 'p', assetExclude: ['art', 'docs/', '', '..', '../x', 'a/../b'] });
+ expect(m.assetExclude).toEqual(['art', 'docs']);
+ });
+ it('is absent when none is given', () => {
+ expect(parseManifest({ name: 'p' }).assetExclude).toBeUndefined();
+ });
+});
+
+describe('the content policy', () => {
+ it('excludes a folder and everything under it, and nothing that merely starts with its name', () => {
+ expect(isExcludedByProject('art', ['art'])).toBe(true);
+ expect(isExcludedByProject('art/models/a.glb', ['art'])).toBe(true);
+ expect(isExcludedByProject('artifacts/a.png', ['art'])).toBe(false);
+ expect(isNonContentPath('art/a.png', ['art'])).toBe(true);
+ expect(isNonContentPath('assets/a.png', ['art'])).toBe(false);
+ });
+});
+
+describe('the asset scan', () => {
+ it('neither indexes nor adopts what an excluded folder holds', async () => {
+ writeFileSync(path.join(root, 'project.esproject'), JSON.stringify({ name: 'p', assetExclude: ['art'] }));
+ put('assets/textures/a.png', 'PNG');
+ put('art/source/b.png', 'PNG');
+ await scanAssetDatabase(root, { write: false });
+ expect(existsSync(path.join(root, 'assets/textures/a.png.meta'))).toBe(true);
+ expect(existsSync(path.join(root, 'art/source/b.png.meta'))).toBe(false);
+ });
+
+ it('adopts it when the manifest says nothing', async () => {
+ writeFileSync(path.join(root, 'project.esproject'), JSON.stringify({ name: 'p' }));
+ put('art/source/b.png', 'PNG');
+ await scanAssetDatabase(root, { write: false });
+ expect(existsSync(path.join(root, 'art/source/b.png.meta'))).toBe(true);
+ });
+});