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(export): name the content a target cannot render, instead of shipping it quietly

yhhdb73fa4e0648
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.ts
index d5cfc45e1..258cd0da7 100644
--- a/desktop/electron/cookAssets.ts
+++ b/desktop/electron/cookAssets.ts
@@ -237,6 +237,10 @@ export interface CookResult {
manifestPath: string | null;
/** uuids included (reachable from the entry scenes). */
included: string[];
+ /** The same assets as `included`, by project-relative source path — what a
+ * caller needs to read the content it just shipped (e.g. to scan the scenes
+ * for subsystems the target cannot render). */
+ includedPaths: string[];
/** uuids present in the project but unreachable — culled from the build. */
unused: string[];
warnings: string[];
@@ -610,5 +614,6 @@ export async function cookAssets(
);
const unused = index.entries.filter((e) => !reachable.has(e.uuid)).map((e) => e.uuid);
- return { ok: true, outDir: absOut, manifestPath, included: [...reachable], unused, warnings };
+ const includedPaths = [...reachable].map((uuid) => byUuid.get(uuid)?.path).filter((p): p is string => p !== undefined);
+ return { ok: true, outDir: absOut, manifestPath, included: [...reachable], includedPaths, unused, warnings };
}
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index 7c63b62dd..dd898e14a 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -21,7 +21,7 @@
*/
import type { BuildOptions, Plugin } from 'esbuild';
import { loadEsbuild } from './esbuildRuntime';
-import { writeFile, mkdir, cp, readdir, rm } from 'node:fs/promises';
+import { writeFile, readFile, mkdir, cp, readdir, rm } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets, loadAssetGroups } from './cookAssets';
@@ -36,6 +36,7 @@ import { ESENGINE_EXTERNAL } from './esengineResolve';
import { orientationCss, orientationOverlayHtml, orientationLockScript, type ScreenOrientation } from './orientationHtml';
import type { ExportPlatform } from '../src/project/format';
+import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../src/project/targetSupport';
export type { ExportPlatform };
/** A switchable scene the export ships: SceneManager name + project-relative path. */
@@ -84,6 +85,38 @@ export async function discoverProjectScenes(root: string, entryScene: string, sc
return scenes;
}
+/**
+ * Warn about content this target cannot render. The editor authors every
+ * subsystem the engine has, but a target may compile only some of them (the
+ * native app leaves out tilemaps, particles, post-processing and text) — so an
+ * export that says nothing writes a package quietly missing half a scene.
+ *
+ * Scans the scenes and prefabs that were actually cooked, so the warning names
+ * the files responsible and a project that never authors a tilemap hears
+ * nothing about tilemaps. What each target lacks is declared once, in
+ * project/targetSupport.ts.
+ */
+async function unsupportedContentWarnings(root: string, includedPaths: string[], platform: ExportPlatform): Promise<string[]> {
+ if (targetGaps(platform).length === 0) return [];
+ const usage = new Map<Subsystem, string[]>();
+ for (const rel of includedPaths) {
+ const ext = path.extname(rel).toLowerCase();
+ if (ext !== '.esscene' && ext !== '.esprefab') continue;
+ let doc: unknown;
+ try {
+ doc = JSON.parse(await readFile(path.join(root, rel), 'utf8'));
+ } catch {
+ continue; // unreadable/!JSON — the cook already staged (and warned about) it
+ }
+ for (const subsystem of collectSubsystems(doc)) {
+ const files = usage.get(subsystem);
+ if (files) files.push(rel);
+ else usage.set(subsystem, [rel]);
+ }
+ }
+ return subsystemGapWarnings(platform, usage);
+}
+
export interface ExportGameResult {
ok: boolean;
platform: ExportPlatform;
@@ -417,6 +450,7 @@ export async function exportGame(opts: {
progress({ phase: 'Cooking assets' });
const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: payloadDir, contentAddressed: opts.contentAddressed ?? true, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, platform });
warnings.push(...cook.warnings);
+ warnings.push(...await unsupportedContentWarnings(opts.root, cook.includedPaths, platform));
progress({ phase: 'Cooking assets', detail: `${cook.included.length} reachable` });
// Also emit the AddressableManifest (v2.0) beside the flat one — the SAME
diff --git a/desktop/src/project/targetSupport.ts b/desktop/src/project/targetSupport.ts
new file mode 100644
index 000000000..1b6f9cc23
--- /dev/null
+++ b/desktop/src/project/targetSupport.ts
@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What a build target can render — and what it cannot.
+ *
+ * The editor authors every subsystem the engine has; a target does not
+ * necessarily compile all of them. The native app builds a subset:
+ * `native/CMakeLists.txt` sets ES_ENABLE_WEBGPU and nothing else, so
+ * `cmake/ESEngineSources.cmake` leaves out the tilemap, particle, post-process
+ * and text sources — and the optional emscripten side modules (Box2D, Spine,
+ * video) have no native counterpart yet.
+ *
+ * Without this, an export writes a package that is quietly missing half a
+ * scene. This is the one declaration of that gap, so the export can name it
+ * instead. `desktop/tests/target-support.test.ts` reads the native CMakeLists
+ * and fails when the two drift: flipping a flag there is what deletes an entry
+ * here.
+ *
+ * Deliberately free of node imports — the electron export and the renderer's
+ * build dialog both read it.
+ */
+import type { ExportPlatform } from './format';
+
+/** An engine subsystem a build target may lack. */
+export type Subsystem = 'text' | 'tilemap' | 'particles' | 'postprocess' | 'physics' | 'spine' | 'video';
+
+/**
+ * The authored vocabulary that puts a subsystem in use: a scene or prefab
+ * carrying one of these components needs it at runtime. Scanning the serialized
+ * content is what makes the warning specific — a project that never authors a
+ * tilemap hears nothing about tilemaps.
+ */
+export const SUBSYSTEM_COMPONENTS: Readonly<Record<Subsystem, readonly string[]>> = {
+ text: ['Text', 'BitmapText'],
+ tilemap: ['Tilemap', 'TilemapLayer'],
+ particles: ['ParticleEmitter', 'ParticleForceField'],
+ postprocess: ['PostProcessVolume'],
+ physics: [
+ 'RigidBody', 'BoxCollider', 'CircleCollider', 'CapsuleCollider', 'SegmentCollider',
+ 'PolygonCollider', 'ChainCollider', 'OneWayPlatform', 'CharacterController',
+ 'RevoluteJoint', 'DistanceJoint', 'PrismaticJoint', 'WeldJoint', 'WheelJoint', 'MotorJoint',
+ ],
+ spine: ['SpineAnimation'],
+ video: ['Video'],
+};
+
+/** Human name, for a message someone packaging a game has to act on. */
+export const SUBSYSTEM_LABEL: Readonly<Record<Subsystem, string>> = {
+ text: 'Text',
+ tilemap: 'Tilemaps',
+ particles: 'Particles',
+ postprocess: 'Post-processing',
+ physics: 'Physics (Box2D)',
+ spine: 'Spine animation',
+ video: 'Video',
+};
+
+/**
+ * The cmake option whose absence drops a subsystem from a build of the engine
+ * core (see `cmake/ESEngineSources.cmake`). The others ship as separate modules
+ * and have no flag, so they are absent here.
+ */
+export const SUBSYSTEM_CMAKE_FLAG: Readonly<Partial<Record<Subsystem, string>>> = {
+ text: 'ES_ENABLE_BITMAP_TEXT',
+ tilemap: 'ES_ENABLE_TILEMAP',
+ particles: 'ES_ENABLE_PARTICLES',
+ postprocess: 'ES_ENABLE_POSTPROCESS',
+};
+
+/** A subsystem a target cannot run, and why. */
+export interface SubsystemGap {
+ subsystem: Subsystem;
+ why: string;
+}
+
+/**
+ * Per-target gaps. A platform absent from this table has none *known*: only the
+ * native target's feature set has been audited against the engine's, since it is
+ * the one that compiles a subset.
+ */
+const GAPS: Partial<Record<ExportPlatform, readonly SubsystemGap[]>> = {
+ native: [
+ { subsystem: 'tilemap', why: 'the native build leaves out the tilemap sources (ES_ENABLE_TILEMAP)' },
+ { subsystem: 'particles', why: 'the native build leaves out the particle sources (ES_ENABLE_PARTICLES)' },
+ { subsystem: 'postprocess', why: 'the native build leaves out the post-process pipeline (ES_ENABLE_POSTPROCESS)' },
+ { subsystem: 'physics', why: 'Box2D ships as an emscripten side module; the native host has no counterpart yet' },
+ { subsystem: 'spine', why: 'the Spine runtime ships as an emscripten side module; the native host has no counterpart yet' },
+ { subsystem: 'video', why: 'the video decoder ships as an emscripten side module; the native host has no counterpart yet' },
+ ],
+};
+
+/** What `platform` cannot render, whether or not this project uses it. */
+export function targetGaps(platform: ExportPlatform): readonly SubsystemGap[] {
+ return GAPS[platform] ?? [];
+}
+
+const COMPONENT_SUBSYSTEM: ReadonlyMap<string, Subsystem> = new Map(
+ (Object.entries(SUBSYSTEM_COMPONENTS) as [Subsystem, readonly string[]][])
+ .flatMap(([subsystem, names]) => names.map((name) => [name, subsystem] as const)),
+);
+
+/**
+ * Collect the subsystems a scene / prefab document puts in use. Pure, and shape-
+ * agnostic: it walks for the serialized `type` vocabulary, so nested entities,
+ * prefab bodies and overrides are all seen without knowing the document layout.
+ */
+export function collectSubsystems(doc: unknown, into: Set<Subsystem> = new Set()): Set<Subsystem> {
+ if (Array.isArray(doc)) {
+ for (const item of doc) collectSubsystems(item, into);
+ return into;
+ }
+ if (doc === null || typeof doc !== 'object') return into;
+ const rec = doc as Record<string, unknown>;
+ if (typeof rec.type === 'string') {
+ const subsystem = COMPONENT_SUBSYSTEM.get(rec.type);
+ if (subsystem) into.add(subsystem);
+ }
+ for (const value of Object.values(rec)) collectSubsystems(value, into);
+ return into;
+}
+
+/** How many source files a warning names before it summarizes the rest. */
+const MAX_NAMED_FILES = 3;
+
+/**
+ * One warning per subsystem this target cannot render but the shipped content
+ * uses, naming where it came from. `usage` maps a subsystem to the files that
+ * authored it (project-relative).
+ */
+export function subsystemGapWarnings(
+ platform: ExportPlatform,
+ usage: ReadonlyMap<Subsystem, readonly string[]>,
+): string[] {
+ const warnings: string[] = [];
+ for (const gap of targetGaps(platform)) {
+ const files = usage.get(gap.subsystem);
+ if (!files || files.length === 0) continue;
+ const named = [...files].sort();
+ const shown = named.slice(0, MAX_NAMED_FILES).join(', ');
+ const rest = named.length > MAX_NAMED_FILES ? ` (+${named.length - MAX_NAMED_FILES} more)` : '';
+ warnings.push(
+ `${platform}: ${SUBSYSTEM_LABEL[gap.subsystem]} will not render in this build — ${gap.why}. Used by ${shown}${rest}`,
+ );
+ }
+ return warnings;
+}
diff --git a/desktop/tests/target-support.test.ts b/desktop/tests/target-support.test.ts
new file mode 100644
index 000000000..57eee5759
--- /dev/null
+++ b/desktop/tests/target-support.test.ts
@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What a build target cannot render, and the export saying so.
+ *
+ * The native app compiles a subset of the engine, so a project can author
+ * content that will not appear on the device. Two things are asserted: that the
+ * scan sees the authored vocabulary (scenes, prefabs, nested entities), and that
+ * the declared native gaps still match `native/CMakeLists.txt` — the build file
+ * is the truth about which sources are compiled, and flipping a flag there is
+ * what deletes an entry from the table.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, copyFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+ collectSubsystems, subsystemGapWarnings, targetGaps, SUBSYSTEM_CMAKE_FLAG, type Subsystem,
+} from '../src/project/targetSupport';
+import { exportGame } from '../electron/exportGame';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..', '..');
+const GAME_HOST = path.join(HERE, '..', 'src', 'gameHost.ts');
+
+describe('collectSubsystems', () => {
+ it('sees components wherever they sit in the document', () => {
+ const scene = {
+ version: '1.0',
+ entities: [
+ { id: 0, components: [{ type: 'Transform' }, { type: 'Sprite' }] },
+ { id: 1, components: [{ type: 'TilemapLayer', data: { tileset: '@uuid:x' } }] },
+ { id: 2, children: [{ id: 3, components: [{ type: 'Text', data: { text: 'hi' } }] }] },
+ ],
+ };
+ expect([...collectSubsystems(scene)].sort()).toEqual(['text', 'tilemap']);
+ });
+
+ it('sees a prefab body and its physics vocabulary', () => {
+ const prefab = { version: '1.0', root: { components: [{ type: 'RigidBody' }, { type: 'BoxCollider' }] } };
+ expect([...collectSubsystems(prefab)]).toEqual(['physics']);
+ });
+
+ it('says nothing about a project that only uses what every target has', () => {
+ const scene = { entities: [{ components: [{ type: 'Sprite' }, { type: 'Light2D' }, { type: 'TrailRenderer' }] }] };
+ expect(collectSubsystems(scene).size).toBe(0);
+ });
+
+ it('ignores non-component `type` fields', () => {
+ expect(collectSubsystems({ importer: { type: 'texture' }, asset: { type: 'scene' } }).size).toBe(0);
+ });
+});
+
+describe('subsystemGapWarnings', () => {
+ const usage = new Map<Subsystem, string[]>([['tilemap', ['scenes/b.esscene', 'scenes/a.esscene']]]);
+
+ it('names the subsystem, the reason and the files', () => {
+ const [warning, ...rest] = subsystemGapWarnings('native', usage);
+ expect(rest).toEqual([]);
+ expect(warning).toContain('Tilemaps will not render');
+ expect(warning).toContain('scenes/a.esscene, scenes/b.esscene');
+ });
+
+ it('is silent for a target with no known gaps', () => {
+ expect(subsystemGapWarnings('web', usage)).toEqual([]);
+ });
+
+ it('is silent about a gap the content does not use', () => {
+ expect(subsystemGapWarnings('native', new Map())).toEqual([]);
+ });
+});
+
+describe('the native gaps match the native build', () => {
+ const cmake = readFileSync(path.join(REPO, 'native', 'CMakeLists.txt'), 'utf8');
+ const enabled = new Set([...cmake.matchAll(/set\(\s*(ES_ENABLE_\w+)\s+ON\s*\)/g)].map((m) => m[1]));
+ const gaps = new Set(targetGaps('native').map((g) => g.subsystem));
+
+ it.each(Object.entries(SUBSYSTEM_CMAKE_FLAG) as [Subsystem, string][])(
+ '%s: a source set the native build omits is declared unsupported', (subsystem, flag) => {
+ if (!enabled.has(flag)) expect(gaps).toContain(subsystem);
+ },
+ );
+
+ it.each(Object.keys(SUBSYSTEM_CMAKE_FLAG) as Subsystem[])(
+ '%s: a source set the native build compiles is not declared unsupported', (subsystem) => {
+ if (enabled.has(SUBSYSTEM_CMAKE_FLAG[subsystem]!)) expect(gaps).not.toContain(subsystem);
+ },
+ );
+});
+
+describe('exportGame warns about content the target cannot render', () => {
+ let root: string;
+ const TEX = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+ const SCN = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+ const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
+
+ beforeAll(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-target-support-'));
+ mkdirSync(path.join(root, 'assets'), { recursive: true });
+ copyFileSync(path.join(REPO, 'examples', 'hello-world', 'assets', 'textures', 'logo.png'), path.join(root, 'assets', 'hero.png'));
+ writeFileSync(path.join(root, 'assets', 'hero.png.meta'), meta(TEX, 'texture'));
+ mkdirSync(path.join(root, 'scenes'), { recursive: true });
+ writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({
+ version: '1.0', name: 'Main',
+ entities: [
+ { id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] },
+ { id: 1, components: [{ type: 'Text', data: { text: 'score' } }] },
+ { id: 2, components: [{ type: 'ParticleEmitter', data: {} }] },
+ { id: 3, components: [{ type: 'TilemapLayer', data: {} }] },
+ ],
+ }));
+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
+ mkdirSync(path.join(root, '_sdk'), { recursive: true });
+ writeFileSync(path.join(root, '_sdk', 'index.js'), 'export const x = 1;');
+ mkdirSync(path.join(root, '_wasm'), { recursive: true });
+ writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'export default () => {};');
+ });
+
+ afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+ const run = (platform: 'native' | 'web', outDir: string) => exportGame({
+ root, entryScene: 'scenes/main.esscene', gameHostEntry: GAME_HOST,
+ sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
+ outDir, platform, title: 'Game',
+ });
+
+ it('names every unsupported subsystem the scene uses — and ships anyway', async () => {
+ const res = await run('native', path.join(root, 'dist-native'));
+ expect(res.errors).toEqual([]);
+ expect(res.ok).toBe(true);
+ const gaps = res.warnings.filter((w) => w.startsWith('native:'));
+ expect(gaps).toHaveLength(2);
+ expect(gaps.join('\n')).toContain('Particles will not render');
+ expect(gaps.join('\n')).toContain('Tilemaps will not render');
+ expect(gaps.join('\n')).toContain('scenes/main.esscene');
+ // Text renders on the native core (the host rasterizes glyphs), so the scene's
+ // label is not warned about — the gaps are what the build really cannot do.
+ expect(gaps.join('\n')).not.toContain('Text will not render');
+ }, 60_000);
+
+ it('stays quiet for a target that renders all of it', async () => {
+ const res = await run('web', path.join(root, 'dist-web'));
+ expect(res.warnings.filter((w) => w.includes('will not render'))).toEqual([]);
+ }, 60_000);
+});