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(editor): exclude scenes from export (packaging.excludeScenes)

yhhd033bc8568b2
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index 61dfac3af..3d03b3a60 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -41,14 +41,18 @@ export interface ExportScene {
/**
* Every scene the shipped game can switch to: all `.esscene` under the
- * project's scenes dir plus the entry scene wherever it lives. Names are the
- * scenes-dir-relative path without extension ('main', 'levels/boss') — the
- * stable ids game code passes to `SceneManager.switchTo`; a scene outside the
- * scenes dir is named by its project-relative path. The entry always sorts
- * first. Cook reachability runs from ALL of these roots, so every scene's
- * assets ship (playable stays entry-only: a size-capped single file).
+ * project's scenes dir plus the entry scene wherever it lives, minus the
+ * project's export exclusions (`packaging.excludeScenes` — dev/test scenes).
+ * Names are the scenes-dir-relative path without extension ('main',
+ * 'levels/boss') — the stable ids game code passes to
+ * `SceneManager.switchTo`; a scene outside the scenes dir is named by its
+ * project-relative path. The entry always sorts first and always ships, an
+ * exclusion notwithstanding. Cook reachability runs from ALL of these roots,
+ * so every scene's assets ship (playable stays entry-only: a size-capped
+ * single file).
*/
-export async function discoverProjectScenes(root: string, entryScene: string, scenesDir?: string): Promise<ExportScene[]> {
+export async function discoverProjectScenes(root: string, entryScene: string, scenesDir?: string, excludeScenes?: string[]): Promise<ExportScene[]> {
+ const excluded = new Set((excludeScenes ?? []).map((p) => p.replace(/\\/g, '/')));
const dir = (scenesDir ?? path.dirname(entryScene)).replace(/\\/g, '/');
const sceneName = (projectPath: string): string => {
const p = projectPath.replace(/\\/g, '/');
@@ -64,7 +68,9 @@ export async function discoverProjectScenes(root: string, entryScene: string, sc
if (entry.isDirectory()) await walk(rel);
else if (/\.esscene$/i.test(entry.name)) {
const projectPath = `${dir}/${rel}`;
- if (projectPath !== scenes[0].path) scenes.push({ name: sceneName(projectPath), path: projectPath });
+ if (projectPath !== scenes[0].path && !excluded.has(projectPath)) {
+ scenes.push({ name: sceneName(projectPath), path: projectPath });
+ }
}
}
};
@@ -244,6 +250,9 @@ export async function exportGame(opts: {
/** Project-relative scenes dir (manifest layout); default the entry's dir.
* Every `.esscene` under it ships as a switchable scene. */
scenesDir?: string;
+ /** Scenes excluded from the build (`packaging.excludeScenes`); the entry
+ * scene always ships. */
+ excludeScenes?: string[];
gameHostEntry: string;
/** Project-relative startup entry (e.g. src/main.ts) → bundled to scripts.mjs. */
scriptsEntry?: string;
@@ -280,7 +289,7 @@ export async function exportGame(opts: {
const platform = opts.platform ?? 'web';
const title = opts.title ?? 'Game';
const progress = opts.onProgress ?? (() => {});
- const scenes = await discoverProjectScenes(opts.root, opts.entryScene, opts.scenesDir);
+ const scenes = await discoverProjectScenes(opts.root, opts.entryScene, opts.scenesDir, opts.excludeScenes);
// WeChat has no import maps + a different module/asset model → its own pipeline.
if (platform === 'wechat') {
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 7c1996478..2707164e3 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -533,6 +533,7 @@ ipcMain.handle(
root,
entryScene,
scenesDir: resolveLayout(manifest).scenes,
+ excludeScenes: manifest.packaging?.excludeScenes,
ySortLayers,
gameHostEntry: path.join(HOSTS_DIR, 'gameHost.js'),
playableHostEntry: path.join(HOSTS_DIR, 'playableHost.js'),
diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsx
index 17d8b58db..0c11e87f3 100644
--- a/desktop/src/panels/ContentBrowser.tsx
+++ b/desktop/src/panels/ContentBrowser.tsx
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { Fragment, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
-import { ChevronRight, LayoutGrid, List, Import, FolderOpen, FolderPlus, ArrowLeft, ArrowRight, ArrowUp, ArrowDownUp, Play } from 'lucide-react';
+import { ChevronRight, LayoutGrid, List, Import, FolderOpen, FolderPlus, ArrowLeft, ArrowRight, ArrowUp, ArrowDownUp, Play, EyeOff } from 'lucide-react';
import { AssetIcon, assetTint } from '@/components/icons';
import { ConfirmDialog } from '@/components/ConfirmDialog';
import { SearchField } from '@/components/SearchField';
@@ -856,9 +856,15 @@ export function ContentBrowser() {
? [{ label: 'Open', onClick: () => onOpen(path, entry.isDir, entry.name) }]
: []),
// The startup scene: what the editor opens, Play boots, and exports ship
- // first. One per project — the current one offers no redundant action.
+ // first. One per project — the current one offers no redundant action,
+ // and it can't be excluded from export (it IS the export's boot scene).
...(isScene && path !== project?.defaultScene
- ? [{ label: 'Set as Startup Scene', onClick: () => void ProjectStore.setDefaultScene(path) }]
+ ? [
+ { label: 'Set as Startup Scene', onClick: () => void ProjectStore.setDefaultScene(path) },
+ project?.packaging?.excludeScenes?.includes(path)
+ ? { label: 'Include in Export', onClick: () => void ProjectStore.setSceneExcluded(path, false) }
+ : { label: 'Exclude from Export', onClick: () => void ProjectStore.setSceneExcluded(path, true) },
+ ]
: []),
...(isTexture
? [{ label: 'Create Tileset', onClick: () => void createTilesetFromTexture(path) }]
@@ -1046,6 +1052,11 @@ export function ContentBrowser() {
<Play size={9} strokeWidth={2.5} />
</span>
)}
+ {project?.packaging?.excludeScenes?.includes(path) && (
+ <span className="badge excluded" title="Excluded from export">
+ <EyeOff size={9} strokeWidth={2.5} />
+ </span>
+ )}
</div>
<div
className="nm"
@@ -1112,6 +1123,9 @@ export function ContentBrowser() {
{path === project?.defaultScene && (
<Play className="start-mark" size={11} strokeWidth={2.5} aria-label="Startup scene" />
)}
+ {project?.packaging?.excludeScenes?.includes(path) && (
+ <EyeOff className="excluded-mark" size={11} strokeWidth={2.5} aria-label="Excluded from export" />
+ )}
</span>
<span className="c">{it.isDir ? '' : TYPE_CODE[type] || type}</span>
</div>
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 0b34dbe18..2db9ba10b 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -921,10 +921,20 @@ class ProjectStoreImpl {
async setDefaultScene(path: string): Promise<void> {
const st = this.state;
if (!st || st.defaultScene === path) return;
- this.store.setState({ project: { ...st, defaultScene: path } });
+ // The startup scene always ships — becoming it lifts any export exclusion.
+ const packaging = this.packagingWithoutExclusion_(st.packaging, path);
+ this.store.setState({ project: { ...st, defaultScene: path, packaging } });
try {
const raw = JSON.parse(await window.estella.fs.read(PROJECT_MANIFEST_FILE)) as Record<string, unknown>;
raw.defaultScene = path;
+ if (packaging !== st.packaging) {
+ // Merge into the RAW packaging so fields the editor parser doesn't
+ // model survive the rewrite.
+ const rawPkg = { ...((raw.packaging as Record<string, unknown>) ?? {}) };
+ if (packaging?.excludeScenes) rawPkg.excludeScenes = packaging.excludeScenes;
+ else delete rawPkg.excludeScenes;
+ raw.packaging = rawPkg;
+ }
await window.estella.fs.write(PROJECT_MANIFEST_FILE, JSON.stringify(raw, null, 2) + '\n');
Toasts.push(`Startup scene: ${path.split('/').pop()}`, 'info');
} catch (e) {
@@ -933,6 +943,48 @@ class ProjectStoreImpl {
}
}
+ /** `packaging` with `path` lifted from excludeScenes (identity when absent). */
+ private packagingWithoutExclusion_(packaging: ProjectPackaging | undefined, path: string): ProjectPackaging | undefined {
+ if (!packaging?.excludeScenes?.includes(path)) return packaging;
+ const excludeScenes = packaging.excludeScenes.filter((p) => p !== path);
+ const next: ProjectPackaging = { ...packaging };
+ if (excludeScenes.length > 0) next.excludeScenes = excludeScenes;
+ else delete next.excludeScenes;
+ return next;
+ }
+
+ /**
+ * Exclude a scene from (or re-include it in) every export — persisted as
+ * `packaging.excludeScenes`. Dev/test scenes stay editable and playable in
+ * the editor; they just don't ship as switchable scenes.
+ */
+ async setSceneExcluded(path: string, excluded: boolean): Promise<void> {
+ const st = this.state;
+ if (!st) return;
+ const cur = new Set(st.packaging?.excludeScenes ?? []);
+ if (excluded) cur.add(path);
+ else cur.delete(path);
+ const packaging: ProjectPackaging = { ...st.packaging };
+ if (cur.size > 0) packaging.excludeScenes = [...cur].sort();
+ else delete packaging.excludeScenes;
+ this.store.setState({ project: { ...st, packaging } });
+ try {
+ const raw = JSON.parse(await window.estella.fs.read(PROJECT_MANIFEST_FILE)) as Record<string, unknown>;
+ // Merge into the RAW packaging so fields the editor parser doesn't model
+ // survive the rewrite.
+ const rawPkg = { ...((raw.packaging as Record<string, unknown>) ?? {}) };
+ if (packaging.excludeScenes) rawPkg.excludeScenes = packaging.excludeScenes;
+ else delete rawPkg.excludeScenes;
+ raw.packaging = rawPkg;
+ await window.estella.fs.write(PROJECT_MANIFEST_FILE, JSON.stringify(raw, null, 2) + '\n');
+ const leaf = path.split('/').pop();
+ Toasts.push(excluded ? `Excluded from export: ${leaf}` : `Included in export: ${leaf}`, 'info');
+ } catch (e) {
+ Toasts.push('Failed to save export exclusion', 'error');
+ console.error('[project] setSceneExcluded write failed', e);
+ }
+ }
+
/** Display info for an asset ref (`@uuid:` or a project-relative path — the same
* forms the loaders accept), or null (none / unresolved). For the inspector's
* asset control: the project-relative path + a leaf name. */
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index a0c5a14e3..a1f473fe4 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -107,6 +107,10 @@ export interface ProjectPackaging {
compressTextures?: boolean;
/** Pack `<name>.atlas/` folders into atlas pages at cook time. */
atlasTextures?: boolean;
+ /** Project-relative scene paths NOT shipped as switchable scenes (dev/test
+ * scenes). Everything else under the scenes dir exports; the startup scene
+ * always ships regardless. */
+ excludeScenes?: string[];
/** Per-platform output-dir overrides (else the per-platform default). */
outDir?: Partial<Record<'web' | 'desktop' | 'wechat' | 'playable', string>>;
/** Per-platform packaging config (appid, app id, orientation, …). */
@@ -281,6 +285,10 @@ export function parseManifest(raw: unknown): ProjectManifest {
if (p.config === 'development' || p.config === 'shipping') pkg.config = p.config;
if (typeof p.sourceMaps === 'boolean') pkg.sourceMaps = p.sourceMaps;
if (typeof p.openFolder === 'boolean') pkg.openFolder = p.openFolder;
+ if (Array.isArray(p.excludeScenes)) {
+ const ex = p.excludeScenes.filter((s): s is string => typeof s === 'string' && s !== '');
+ if (ex.length > 0) pkg.excludeScenes = ex;
+ }
if (p.outDir && typeof p.outDir === 'object') {
const od = p.outDir as Record<string, unknown>;
const out: NonNullable<ProjectPackaging['outDir']> = {};
diff --git a/desktop/src/theme/content.css b/desktop/src/theme/content.css
index c08d5b4f4..fe0d10c89 100644
--- a/desktop/src/theme/content.css
+++ b/desktop/src/theme/content.css
@@ -86,6 +86,10 @@
/* Startup-scene marker — the scene the editor opens, Play boots, exports ship first. */
.asset .th .badge.start { left: auto; right: 5px; display: grid; place-items: center; padding: 2px 3px; background: var(--star); }
.lr .start-mark { flex: none; color: var(--star-hi); }
+/* Excluded-from-export marker (mutually exclusive with .start — the startup
+ scene always ships). */
+.asset .th .badge.excluded { left: auto; right: 5px; display: grid; place-items: center; padding: 2px 3px; background: rgba(0, 0, 0, 0.55); color: var(--text-mute); }
+.lr .excluded-mark { flex: none; color: var(--text-mute); }
.asset .nm { display: flex; align-items: center; gap: 4px; padding: 6px 7px; font-size: var(--fs-xs); color: var(--text); background: var(--srf-3); border-radius: 0 0 var(--r-md) var(--r-md); border-top: 2px solid var(--tc, var(--text-mute)); }
.asset .nm span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.folder .th { background: none; color: var(--cat-collision); }
diff --git a/desktop/tests/export-game.test.ts b/desktop/tests/export-game.test.ts
index 4670f3c4e..05ca039e3 100644
--- a/desktop/tests/export-game.test.ts
+++ b/desktop/tests/export-game.test.ts
@@ -159,6 +159,26 @@ describe('exportGame', () => {
expect(cfg.scenes[0]).toEqual({ name: 'main', path: 'scenes/main.esscene' }); // entry first
}, 60_000);
+ it('excludeScenes drops a scene from the build; the entry is immune', async () => {
+ const outEx = path.join(root, 'dist-game-excluded');
+ const res = await exportGame({
+ root,
+ entryScene: 'scenes/main.esscene',
+ gameHostEntry: GAME_HOST,
+ scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(root, '_sdk'),
+ wasmDir: path.join(root, '_wasm'),
+ outDir: outEx,
+ title: 'My Game',
+ // level2 excluded; excluding the entry must be ignored — it boots the game.
+ excludeScenes: ['scenes/level2.esscene', 'scenes/main.esscene'],
+ });
+ expect(res.ok).toBe(true);
+ const cfg = JSON.parse(readFileSync(path.join(outEx, 'game.config.json'), 'utf8'));
+ expect(cfg.scenes).toEqual([{ name: 'main', path: 'scenes/main.esscene' }]);
+ expect(existsSync(path.join(outEx, 'scenes/level2.esscene'))).toBe(false);
+ }, 60_000);
+
it('fails when the wasm runtime is missing — the build cannot boot without it', async () => {
const out3 = path.join(root, 'dist-game-nowasm');
const res = await exportGame({
diff --git a/desktop/tests/project-packaging.test.ts b/desktop/tests/project-packaging.test.ts
index f80d2899e..5397108fc 100644
--- a/desktop/tests/project-packaging.test.ts
+++ b/desktop/tests/project-packaging.test.ts
@@ -26,6 +26,16 @@ describe('parseManifest — packaging', () => {
expect(m.packaging).toEqual({ outDir: { web: 'ok' } });
});
+ it('parses excludeScenes, dropping non-string / empty entries', () => {
+ const m = parseManifest({
+ name: 'X',
+ packaging: { excludeScenes: ['assets/scenes/dev.esscene', '', 7, 'assets/scenes/test.esscene'] },
+ });
+ expect(m.packaging?.excludeScenes).toEqual(['assets/scenes/dev.esscene', 'assets/scenes/test.esscene']);
+ // An empty list is no list.
+ expect(parseManifest({ name: 'X', packaging: { excludeScenes: [] } }).packaging).toBeUndefined();
+ });
+
it('omits packaging when absent', () => {
expect(parseManifest({ name: 'X' }).packaging).toBeUndefined();
});