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(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.tsindex 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.tsindex 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, screturn 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 SAMEdiff --git a/desktop/src/project/targetSupport.ts b/desktop/src/project/targetSupport.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+});