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): 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.mdxindex 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 areference into a usable handle, and **reference counting** frees what's no longerused. 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 assetsIn code, reference an asset by its **project-relative path** — readable, and whatdiff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdxindex 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.tsindex 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[] = []): Proif (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 | nreturn 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.tsindex 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.tsindex 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 thatdiff --git a/pipeline/tests/asset-exclude.test.ts b/pipeline/tests/asset-exclude.test.tsnew file mode 100644index 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);+ });+});