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.

fix(export): a package carries the modules its content can ask for

yhh68140dbf37e6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 75ebd29be..80c5d2a0b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -50,6 +50,33 @@ published separately; it ships inside the editor.
### Fixed
+- **A web package carried every optional module the engine builds.** The export
+ copied the engine's wasm directory wholesale, so a 2D game shipped the 3D
+ solver, all five Spine runtimes, the DragonBones player, the video decoder and
+ the Basis transcoder — about 3.9 MB of binaries nothing in it could ask for.
+ A package now carries what its content can reach: `hello-world`'s runtime went
+ from 6.0 MB to 1.7 MB, `physics-playground` takes the 2D solver and not the 3D
+ one, and `spine-demo` takes the two Spine runtimes its skeletons report rather
+ than all five.
+
+ The mini-game and playable exports already answered this question — a playable
+ is size-capped, so it had to. What they answered it with was a private copy of
+ the runtime's component tables, and the copies had drifted: neither knew about
+ `MeshCollider3D`, `ConvexCollider3D` or any of the five 3D joints, so a scene
+ held together by a hinge was a scene those exports believed needed no solver.
+ One of them also had no entry for `physics3d` at all, which is why exporting a
+ 3D scene as a playable failed on an artifact called `undefined.js`. There is
+ one scan now, and it calls the runtime's own predicates rather than a
+ reproduction of them.
+
+ Two rules it gained on the way. It reads prefabs, not only scenes: the runtime
+ expands prefabs *before* it asks whether a scene needs physics, so a body that
+ arrives only through a prefab is one the package has to carry, and a project
+ that spawned its bodies that way had been shipping without a solver everywhere
+ the scan was load-bearing. And a module the content needs that the wasm
+ directory does not hold now fails the export, where the web path used to ship
+ it by accident and had no opinion.
+
- **An asset named only inside another asset's document was culled from the
build.** A baked environment names its reflection atlas as a sibling of the
`.esenv`, and nothing else in the project mentions that file — so the
diff --git a/desktop/tests/export-game.test.ts b/desktop/tests/export-game.test.ts
index 79a62a9a3..64f974df9 100644
--- a/desktop/tests/export-game.test.ts
+++ b/desktop/tests/export-game.test.ts
@@ -71,6 +71,10 @@ beforeAll(async () => {
mkdirSync(path.join(root, '_wasm'), { recursive: true });
writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'export default () => {};');
writeFileSync(path.join(root, '_wasm', 'esengine.wasm'), 'wasmbytes');
+ // A KTX2 texture is decoded by the Basis transcoder, so the compressing export
+ // below needs it present the same way a real wasm dir has it.
+ writeFileSync(path.join(root, '_wasm', 'basis.js'), 'export default () => {};');
+ writeFileSync(path.join(root, '_wasm', 'basis.wasm'), 'basisbytes');
out = path.join(root, 'dist-game');
}, 60_000);
@@ -226,6 +230,10 @@ describe('exportGame', () => {
// The scene keeps its logical name and the whole build still assembled.
expect(existsSync(path.join(out2, 'scenes/main.esscene'))).toBe(true);
expect(existsSync(path.join(out2, 'game.js'))).toBe(true);
+ // Compressing to KTX2 is what puts the transcoder in the package; the
+ // uncompressed export above ships the same wasm dir without it.
+ expect(existsSync(path.join(out2, 'wasm/basis.wasm'))).toBe(true);
+ expect(existsSync(path.join(out, 'wasm/basis.wasm'))).toBe(false);
}, 60_000);
it('ships every scene in the scenes dir, listed in game.config.json', async () => {
diff --git a/desktop/tests/export-side-modules.test.ts b/desktop/tests/export-side-modules.test.ts
new file mode 100644
index 000000000..f81c2edb1
--- /dev/null
+++ b/desktop/tests/export-side-modules.test.ts
@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Which optional modules a web package carries: the ones its content can
+ * ask for, and no others. A dropped module is a 404 at boot.
+ */
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exportGame } from '../../pipeline/src/export/exportGame';
+import { runtimeConfigOf } from '../../pipeline/src/project/runtimeConfig';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const GAME_HOST = path.join(HERE, '..', '..', 'pipeline', 'src', 'runtime', 'gameHost.ts');
+
+const SCN = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
+const PFB = 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee';
+const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
+
+/** Every module the engine ships, so a test can assert what did NOT come along. */
+const ALL_MODULES = [
+ 'physics', 'physics3d', 'basis', 'videodec', 'dragonbones',
+ 'spine21', 'spine38', 'spine41', 'spine42', 'spine43',
+];
+
+interface Fixture { root: string; out: string }
+
+function setup(scene: unknown, extra?: (root: string) => void): Fixture {
+ const root = mkdtempSync(path.join(tmpdir(), 'estella-sidemod-'));
+ mkdirSync(path.join(root, 'scenes'), { recursive: true });
+ writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify(scene));
+ 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 () => {};');
+ writeFileSync(path.join(root, '_wasm', 'esengine.wasm'), 'ENGINE');
+ writeFileSync(path.join(root, '_wasm', 'wasm.manifest.json'), JSON.stringify({ schema: 1 }));
+ for (const m of ALL_MODULES) {
+ writeFileSync(path.join(root, '_wasm', `${m}.js`), `export default () => {};/*${m}*/`);
+ writeFileSync(path.join(root, '_wasm', `${m}.wasm`), m.toUpperCase());
+ }
+ extra?.(root);
+ return { root, out: path.join(root, 'dist') };
+}
+
+const run = (f: Fixture, runtime?: Parameters<typeof exportGame>[0]['runtime']) => exportGame({
+ root: f.root, entryScene: 'scenes/main.esscene', gameHostEntry: GAME_HOST,
+ sdkDistDir: path.join(f.root, '_sdk'), wasmDir: path.join(f.root, '_wasm'),
+ outDir: f.out, ...(runtime ? { runtime } : {}),
+});
+
+/** The module artifact base names the package actually carries. */
+function shipped(out: string): string[] {
+ return ALL_MODULES.filter((m) => existsSync(path.join(out, 'wasm', `${m}.wasm`)));
+}
+
+const entities = (...components: Array<{ type: string; data?: unknown }>) =>
+ [{ id: 0, components }];
+
+describe('web package side modules', () => {
+ it('carries the engine and nothing optional for a scene that asks for nothing', async () => {
+ const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'Sprite', data: {} }) });
+ try {
+ const res = await run(f);
+ expect(res.errors).toEqual([]);
+ expect(shipped(f.out)).toEqual([]);
+ // The engine core and the dir's other contents are never the scan's to drop.
+ expect(existsSync(path.join(f.out, 'wasm', 'esengine.wasm'))).toBe(true);
+ expect(existsSync(path.join(f.out, 'wasm', 'esengine.js'))).toBe(true);
+ expect(existsSync(path.join(f.out, 'wasm', 'wasm.manifest.json'))).toBe(true);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+
+ it('carries the 2D solver for a scene with a body', async () => {
+ const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'RigidBody', data: { bodyType: 1 } }) });
+ try {
+ expect(shipped((await run(f), f.out))).toEqual(['physics']);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+
+ it('carries the 2D solver a project declares but no scene uses', async () => {
+ const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'Sprite', data: {} }) });
+ try {
+ await run(f, runtimeConfigOf({ features: { physics: { enabled: true } } }));
+ expect(shipped(f.out)).toEqual(['physics']);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+
+ it('carries the 3D solver for a 3D body, and never implies it from the 2D flag', async () => {
+ const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'RigidBody3D', data: {} }) });
+ try {
+ await run(f);
+ expect(shipped(f.out)).toEqual(['physics3d']);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+
+ // Joints and mesh colliders are 3D physics components like the bodies are;
+ // the scan answers for every type the runtime's own gate counts.
+ it('carries the 3D solver for a joint, not only for a body', async () => {
+ const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'HingeJoint3D', data: {} }) });
+ try {
+ await run(f);
+ expect(shipped(f.out)).toEqual(['physics3d']);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+
+ it('carries the 3D solver for a mesh collider', async () => {
+ const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'MeshCollider3D', data: {} }) });
+ try {
+ await run(f);
+ expect(shipped(f.out)).toEqual(['physics3d']);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+
+ // The runtime expands prefabs before it asks whether the scene needs physics,
+ // so a body reachable only through a prefab is one the package must carry.
+ it('carries what a shipped prefab needs, not only what a scene holds', async () => {
+ const f = setup(
+ { version: '1.0', name: 'Main', entities: entities({ type: 'Spawner', data: { prefab: `@uuid:${PFB}` } }) },
+ (root) => {
+ mkdirSync(path.join(root, 'prefabs'), { recursive: true });
+ writeFileSync(path.join(root, 'prefabs', 'enemy.esprefab'), JSON.stringify({
+ version: '1.0', name: 'Enemy', rootEntityId: 'r',
+ entities: [{ prefabEntityId: 'r', name: 'Enemy', parent: null, children: [], visible: true, components: [{ type: 'RigidBody', data: { bodyType: 1 } }] }],
+ }));
+ writeFileSync(path.join(root, 'prefabs', 'enemy.esprefab.meta'), meta(PFB, 'prefab'));
+ },
+ );
+ try {
+ const res = await run(f);
+ expect(res.errors).toEqual([]);
+ expect(shipped(f.out)).toEqual(['physics']);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+
+ it('fails the export when the content needs a module the wasm dir has not built', async () => {
+ const f = setup({ version: '1.0', name: 'Main', entities: entities({ type: 'RigidBody3D', data: {} }) });
+ rmSync(path.join(f.root, '_wasm', 'physics3d.js'));
+ try {
+ const res = await run(f);
+ expect(res.ok).toBe(false);
+ expect(res.errors.join('\n')).toMatch(/physics3d/);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 60_000);
+});
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 5fc3e29f6..04c3e00de 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 73,
- "experimental": 1562,
+ "experimental": 1564,
"deprecated": 3
},
- "total": 1748,
+ "total": 1750,
"subsystems": [
{
"id": "ecs",
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index 3bebcb6a4..810636a48 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -93,6 +93,12 @@ export interface CookManifestEntry extends AssetEntry {
};
}
+/** `assets.manifest.json` as the cook writes it — what the package carries. */
+export interface CookManifest {
+ version: string;
+ entries: CookManifestEntry[];
+}
+
/**
* Load the project's asset-delivery config (`.esengine/asset-groups.json`) — the
* single authored source for which folders ship as remote (CDN) / subpackage
diff --git a/pipeline/src/bundle/sideModuleScan.ts b/pipeline/src/bundle/sideModuleScan.ts
index a14be1587..4d44f5cb6 100644
--- a/pipeline/src/bundle/sideModuleScan.ts
+++ b/pipeline/src/bundle/sideModuleScan.ts
@@ -1,86 +1,53 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file sideModuleScan.ts — the export-time half of side-module gating. The
- * runtime self-gates physics/spine off a scene scan (runtimeLoader +
- * SpineManager); for the INLINED targets (playable single-file) the
- * exporter must run the SAME scan so it embeds exactly the modules the
- * scene needs and no more (playables are size-capped). The constant lists
- * below mirror the SDK's so the two halves agree; keep them in sync.
+ * @file sideModuleScan.ts — which optional modules the content a package ships
+ * can ask for. Every rule here is the export-time half of a runtime
+ * gate, and calls the runtime's own predicate where one exists.
*/
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+ SIDE_MODULES, spineModuleId, getEditorType,
+ sceneUsesPhysics, sceneUses3DPhysics,
+ type SideModuleId, type SpineVersion,
+} from 'esengine';
+
+export type { SpineVersion };
+export { SIDE_MODULES, spineModuleId };
+
+/** id → the `build-tools/cli.js build -t <target>` producing its WeChat artifacts. */
+export const WECHAT_MODULE_BUILD_TARGET: Record<string, string> = {
+ physics: 'physics-wechat',
+ basis: 'basis-wechat',
+ videodec: 'videodec-wechat',
+ dragonbones: 'dragonbones-wechat',
+ 'spine:2.1': 'spine-wechat',
+ 'spine:3.8': 'spine-wechat',
+ 'spine:4.1': 'spine-wechat',
+ 'spine:4.2': 'spine-wechat',
+ 'spine:4.3': 'spine-wechat',
+};
-/** Component types whose presence means the scene needs physics.
- * Mirrors sdk/src/runtimeLoader.ts PHYSICS_COMPONENT_TYPES. */
-const PHYSICS_COMPONENT_TYPES = new Set([
- 'RigidBody', 'BoxCollider', 'CircleCollider', 'CapsuleCollider',
- 'SegmentCollider', 'PolygonCollider', 'ChainCollider',
-]);
-
-const PHYSICS3D_COMPONENT_TYPES = new Set([
- 'RigidBody3D', 'BoxCollider3D', 'SphereCollider3D', 'CapsuleCollider3D',
- 'CharacterController3D',
-]);
-
-interface SceneLike {
- entities?: Array<{ components?: Array<{ type?: string; data?: unknown }> }>;
-}
-
-/** True if any entity carries a physics component, or a TilemapLayer that bakes
- * collidable tiles (which spawn colliders at runtime). Mirrors runtimeLoader.sceneUsesPhysics. */
-export function sceneUsesPhysics(scene: SceneLike): boolean {
- for (const entity of scene.entities ?? []) {
- for (const comp of entity.components ?? []) {
- if (comp.type && PHYSICS_COMPONENT_TYPES.has(comp.type)) return true;
- if (comp.type === 'TilemapLayer') {
- const ids = (comp.data as Record<string, unknown> | undefined)?.collidableTileIds;
- if (Array.isArray(ids) && ids.length > 0) return true;
- }
- }
- }
- return false;
-}
-
-/** The same question for the 3D world, which ships as its own module. Mirrors
- * runtimeLoader.sceneUses3DPhysics. */
-export function sceneUses3DPhysics(scene: SceneLike): boolean {
- for (const entity of scene.entities ?? []) {
- for (const comp of entity.components ?? []) {
- if (comp.type && PHYSICS3D_COMPONENT_TYPES.has(comp.type)) return true;
- }
- }
- return false;
-}
-
-/** True if any entity carries a DragonBonesAnimation. Unlike Spine there is no
- * version to detect: the format is frozen and one module reads all of it, so the
- * presence of the component IS the answer. */
-export function sceneUsesDragonBones(scene: SceneLike): boolean {
- for (const entity of scene.entities ?? []) {
- for (const comp of entity.components ?? []) {
- if (comp.type === 'DragonBonesAnimation') return true;
- }
- }
- return false;
+interface CookEntryLike {
+ path: string;
+ sourcePath?: string;
+ type?: string;
}
-/** True if any entity carries a Video component — the wasm video decoder is
- * WeChat's only video path, so any Video means the module must ship. */
-export function sceneUsesVideo(scene: SceneLike): boolean {
- for (const entity of scene.entities ?? []) {
- for (const comp of entity.components ?? []) {
- if (comp.type === 'Video') return true;
- }
- }
- return false;
+export interface SideModuleScanInput {
+ /** Project root — the authored documents are read from here. */
+ root: string;
+ /** Project-relative paths the cook reached; scenes and prefabs are scanned. */
+ includedPaths: readonly string[];
+ /** Entries the cook staged, naming what the package physically carries. */
+ cookEntries: readonly CookEntryLike[];
+ /** Absolute dir `cookEntries[].path` resolve against. */
+ stagedDir: string;
+ /** Project Settings → Physics enabled. */
+ physicsEnabled: boolean;
}
-export type SpineVersion = '2.1' | '3.8' | '4.1' | '4.2' | '4.3';
-
-/**
- * Which runtime reads a skeleton's reported version, newest prefix first — the same
- * table SpineManager keeps, because a cook that ships one module and a runtime that
- * asks for another is the one mismatch nothing downstream can recover from.
- */
const VERSION_PREFIXES: ReadonlyArray<readonly [string, SpineVersion]> = [
['4.3', '4.3'],
['4.2', '4.2'],
@@ -96,38 +63,6 @@ function runtimeFor(reported: string): SpineVersion | null {
return null;
}
-/** id → artifact base name. Mirrors sdk/src/sideModules/registry.ts SIDE_MODULES. */
-export const SIDE_MODULE_FILE: Record<string, string> = {
- physics: 'physics',
- basis: 'basis',
- videodec: 'videodec',
- dragonbones: 'dragonbones',
- 'spine:2.1': 'spine21',
- 'spine:3.8': 'spine38',
- 'spine:4.1': 'spine41',
- 'spine:4.2': 'spine42',
- 'spine:4.3': 'spine43',
-};
-
-/** id → the `build-tools/cli.js build -t <target>` that produces its WeChat artifacts. */
-export const WECHAT_MODULE_BUILD_TARGET: Record<string, string> = {
- physics: 'physics-wechat',
- basis: 'basis-wechat',
- videodec: 'videodec-wechat',
- dragonbones: 'dragonbones-wechat',
- 'spine:2.1': 'spine-wechat',
- 'spine:3.8': 'spine-wechat',
- 'spine:4.1': 'spine-wechat',
- 'spine:4.2': 'spine-wechat',
- 'spine:4.3': 'spine-wechat',
-};
-
-export function spineModuleId(version: SpineVersion): string {
- return `spine:${version}`;
-}
-
-// --- Spine skeleton version detection (mirrors SpineManager.detectVersion[Json]) ---
-
export function detectSpineVersionJson(json: string): SpineVersion | null {
const m = json.match(/"spine"\s*:\s*"(\d+\.\d+)/);
return m ? runtimeFor(m[1]) : null;
@@ -171,3 +106,95 @@ function tryRead3xVersion(data: Uint8Array): SpineVersion | null {
const ver = new TextDecoder().decode(data.subarray(pos, pos + verLen - 1));
return (ver.startsWith('3.') || ver.startsWith('2.')) ? runtimeFor(ver) : null;
}
+
+async function readDocuments(root: string, includedPaths: readonly string[]): Promise<unknown[]> {
+ const docs: unknown[] = [];
+ for (const rel of includedPaths) {
+ const ext = path.extname(rel).toLowerCase();
+ if (ext !== '.esscene' && ext !== '.esprefab') continue;
+ try {
+ docs.push(JSON.parse(await readFile(path.join(root, rel), 'utf8')));
+ } catch { /* unreadable or not JSON — the cook already warned */ }
+ }
+ return docs;
+}
+
+/**
+ * The union of optional modules any shipped document can ask for. A dynamically
+ * switched scene and a prefab spawned from script both have to find their module
+ * present, so this is a union over everything the package carries, not over the
+ * entry scene.
+ */
+export async function scanSideModuleIds(input: SideModuleScanInput): Promise<Set<SideModuleId>> {
+ const ids = new Set<SideModuleId>();
+ const docs = await readDocuments(input.root, input.includedPaths);
+
+ // The project's own declaration counts as a use: a game that spawns bodies from
+ // script has none in any document, and shipping the flag without the binary
+ // fails at the first spawn instead of at build time.
+ if (input.physicsEnabled || docs.some((d) => sceneUsesPhysics(d as never))) ids.add('physics');
+ // Never implied by the 2D flag — that declares the solver 2D scenes use, and
+ // this is a different module.
+ if (docs.some((d) => sceneUses3DPhysics(d as never))) ids.add('physics3d');
+
+ for (const e of input.cookEntries) {
+ const lower = e.path.toLowerCase();
+ if (/\.ktx2(\.bin)?$/.test(lower)) ids.add('basis');
+ // Script-driven playback references cooked videos no component names.
+ if (/\.esv(\.bin)?$/.test(lower)) ids.add('videodec');
+ const editorType = getEditorType(e.sourcePath ?? e.path);
+ if (editorType === 'dragonbones-skeleton' || editorType === 'dragonbones-atlas') ids.add('dragonbones');
+ if (e.type !== 'spine') continue;
+ const ext = path.extname(e.sourcePath ?? e.path).toLowerCase();
+ try {
+ let v: SpineVersion | null = null;
+ if (ext === '.skel') {
+ v = detectSpineVersion(new Uint8Array(await readFile(path.join(input.stagedDir, e.path))));
+ } else if (ext === '.json') {
+ v = detectSpineVersionJson(await readFile(path.join(input.stagedDir, e.path), 'utf8'));
+ }
+ if (v) ids.add(spineModuleId(v));
+ } catch { /* unreadable cook entry — cookAssets already warned */ }
+ }
+ return ids;
+}
+
+/**
+ * A `cp` filter over the engine's wasm dir keeping only the side modules in
+ * `needed`. Anything that is not a known side-module artifact ships untouched:
+ * the only files this can prove unnecessary are the ones the scan answered for.
+ */
+export function shipsSideModule(needed: readonly string[]): (src: string) => boolean {
+ const keep = new Set(needed);
+ const droppable = new Set<string>();
+ for (const descriptor of Object.values(SIDE_MODULES)) {
+ if (!keep.has(descriptor.file)) droppable.add(descriptor.file);
+ }
+ return (src: string) => {
+ const base = path.basename(src);
+ const dot = base.indexOf('.');
+ if (dot < 0) return true;
+ const stem = base.slice(0, dot);
+ const ext = base.slice(dot).toLowerCase();
+ if (ext !== '.js' && ext !== '.wasm') return true;
+ return !droppable.has(stem);
+ };
+}
+
+/**
+ * The artifact base names `ids` resolve to. An id with no entry in the engine's
+ * table is reported rather than skipped: a module the scan asks for and the
+ * package does not carry is a 404 the moment the content needs it.
+ */
+export function sideModuleFiles(
+ ids: Iterable<SideModuleId>,
+): { files: Array<{ id: SideModuleId; file: string }>; unknown: SideModuleId[] } {
+ const files: Array<{ id: SideModuleId; file: string }> = [];
+ const unknown: SideModuleId[] = [];
+ for (const id of ids) {
+ const descriptor = SIDE_MODULES[id as keyof typeof SIDE_MODULES];
+ if (descriptor) files.push({ id, file: descriptor.file });
+ else unknown.push(id);
+ }
+ return { files, unknown };
+}
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index ab63ca2a8..af7ad1b9c 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -24,7 +24,7 @@ import { loadEsbuild } from '../bundle/esbuildRuntime';
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 '../assets/cookAssets';
+import { cookAssets, loadAssetGroups, type CookManifest } from '../assets/cookAssets';
import { buildAddressableManifest } from '../assets/addressableManifest';
import { activeRemoteRoot } from '../../../sdk/src/asset/assetGroups';
import type { PackagedGameConfig } from 'esengine';
@@ -55,6 +55,7 @@ import type { SizeBudget } from '../project/sizeBudget';
import { measureBuild, type BuildSizeReport } from './sizeReport';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../project/targetSupport';
+import { scanSideModuleIds, sideModuleFiles, shipsSideModule } from '../bundle/sideModuleScan';
export type { ExportPlatform };
/**
@@ -599,6 +600,18 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
warnings.push(...await unsupportedContentWarnings(opts.root, cook.includedPaths, platform));
progress({ phase: 'Cooking assets', detail: `${cook.included.length} reachable` });
+ // What the cook physically staged, read before the flat manifest is dropped
+ // below: the side-module scan asks it what the package carries, and a texture
+ // compressed to KTX2 or a video transcoded to .esv is only nameable here.
+ let cookEntries: CookManifest['entries'] = [];
+ try {
+ cookEntries = (JSON.parse(
+ await readFile(path.join(payloadDir, 'assets.manifest.json'), 'utf8'),
+ ) as CookManifest).entries;
+ } catch (err) {
+ errors.push(`cook manifest: ${err instanceof Error ? err.message : String(err)}`);
+ }
+
// Also emit the AddressableManifest (v2.0) beside the flat one — the SAME
// model every target now shares, so `loadGroup` / remote-group / hot-update
// work on web + desktop too (not just mini-games). Additive: the eager boot
@@ -658,8 +671,22 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
if (existsSync(opts.sdkDistDir)) {
await cp(opts.sdkDistDir, path.join(payloadDir, 'sdk'), { recursive: true, filter: shipsToBrowser });
} else errors.push(`sdk dist not found: ${opts.sdkDistDir}`);
- if (existsSync(opts.wasmDir)) await cp(opts.wasmDir, path.join(payloadDir, 'wasm'), { recursive: true });
- else errors.push(`wasm runtime dir not found: ${opts.wasmDir}`);
+ if (existsSync(opts.wasmDir)) {
+ const ids = await scanSideModuleIds({
+ root: opts.root, includedPaths: cook.includedPaths, cookEntries,
+ stagedDir: payloadDir, physicsEnabled: runtime.physicsEnabled,
+ });
+ const { files, unknown } = sideModuleFiles(ids);
+ for (const id of unknown) errors.push(`internal: no artifact mapping for side module "${id}"`);
+ for (const { id, file } of files) {
+ if (!existsSync(path.join(opts.wasmDir, `${file}.js`))) {
+ errors.push(`content needs "${id}" but ${file}.js is not in ${opts.wasmDir} — build the target that produces it (build-tools/build.config.js maps artifacts to targets) and re-export.`);
+ }
+ }
+ await cp(opts.wasmDir, path.join(payloadDir, 'wasm'), {
+ recursive: true, filter: shipsSideModule(files.map((f) => f.file)),
+ });
+ } else errors.push(`wasm runtime dir not found: ${opts.wasmDir}`);
}
// The project's own modules go beside the engine's, so every transport finds
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index 4d05058b5..47b8f89e6 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -41,10 +41,7 @@ import type { ExportScene } from './exportGame';
import type { OnExportProgress } from './exportProgress';
import { esengineAlias } from '../bundle/esengineResolve';
import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';
-import {
- sceneUsesPhysics, sceneUses3DPhysics, sceneUsesVideo, sceneUsesDragonBones, detectSpineVersion, detectSpineVersionJson,
- spineModuleId, SIDE_MODULE_FILE,
-} from '../bundle/sideModuleScan';
+import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';
import { OPEN_DATA_DIR } from './miniGameExportProfile';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
import type { MiniGameExportProfile, MiniGameVendor } from './miniGameExportProfile';
@@ -103,61 +100,34 @@ function packIncludeSuffixes(entries: CookManifest['entries'], nativeSuffixes: R
return [...suffixes].sort();
}
-/** The export-time mirror of the runtime's physics/spine self-gating: which
- * optional modules ANY shipped scene needs (a dynamically switched scene must
- * find its modules present). A needed module absent from the vendor wasm dir
- * is a HARD error — the package would otherwise ship silently broken (same
- * contract as the playable exporter's collectSideModules). */
+/** A needed module absent from the vendor wasm dir is a HARD error — the package
+ * would otherwise ship silently broken (same contract as the playable
+ * exporter's collectSideModules). */
async function scanSideModules(
profile: MiniGameExportProfile,
- sceneDatas: unknown[],
+ root: string,
+ includedPaths: readonly string[],
cookEntries: CookManifest['entries'],
absOut: string,
wasmDir: string,
errors: string[],
physicsEnabled: boolean,
): Promise<Array<{ id: string; file: string }>> {
- const ids = new Set<string>();
- // The project's own declaration counts as a use: a game that spawns bodies from
- // script has none in the scene, and shipping the enable flag without the binary
- // would fail at the first spawn instead of at build time.
- if (physicsEnabled
- || sceneDatas.some((s) => s && sceneUsesPhysics(s as Parameters<typeof sceneUsesPhysics>[0]))) ids.add('physics');
- // Never implied by the 2D flag: that declares the solver 2D scenes use, and
- // this is a different module.
- if (sceneDatas.some((s) => s && sceneUses3DPhysics(s as Parameters<typeof sceneUses3DPhysics>[0]))) {
- ids.add('physics3d');
- }
- if (sceneDatas.some((s) => s && sceneUsesVideo(s as Parameters<typeof sceneUsesVideo>[0]))) ids.add('videodec');
- if (sceneDatas.some((s) => s && sceneUsesDragonBones(s as Parameters<typeof sceneUsesDragonBones>[0]))) ids.add('dragonbones');
- // Any staged .esv also needs the decoder: script-driven playback
- // (VideoPlayer.play) references cooked videos no scene component names.
- if (cookEntries.some((e) => /\.esv(\.bin)?$/.test(e.path.toLowerCase()))) ids.add('videodec');
- // Spine: the skeleton carries the version. Skeleton + atlas share the authored
- // meta type `spine`, so discriminate by extension — `.skel` is a binary
- // skeleton, `.json` a JSON one; the `.atlas` sibling is not a skeleton.
- for (const e of cookEntries) {
- // Any staged KTX2 texture (compressTextures cook, or an authored .ktx2 —
- // staged as .ktx2.bin for the suffix whitelist) needs the Basis transcoder
- // at runtime. Mirrors sdk isKtx2Path.
- if (/\.ktx2(\.bin)?$/.test(e.path.toLowerCase())) ids.add('basis');
- if (e.type !== 'spine') continue;
- const ext = path.extname(e.sourcePath ?? e.path).toLowerCase();
- try {
- let v: ReturnType<typeof detectSpineVersionJson> = null;
- if (ext === '.skel') {
- v = detectSpineVersion(new Uint8Array(await readFile(path.join(absOut, e.path))));
- } else if (ext === '.json') {
- v = detectSpineVersionJson(await readFile(path.join(absOut, e.path), 'utf8'));
- }
- if (v) ids.add(spineModuleId(v));
- } catch { /* unreadable cook entry — cookAssets already warned; skip */ }
- }
+ const ids = await scanSideModuleIds({
+ root, includedPaths, cookEntries, stagedDir: absOut, physicsEnabled,
+ });
+ const { files, unknown } = sideModuleFiles(ids);
+ for (const id of unknown) errors.push(`internal: no artifact mapping for side module "${id}"`);
+
const present: Array<{ id: string; file: string }> = [];
- for (const id of ids) {
- const file = SIDE_MODULE_FILE[id];
- if (file && existsSync(path.join(wasmDir, `${file}.js`))) present.push({ id, file });
- else errors.push(`scene needs "${id}" but ${file}.js is not in the ${profile.id} wasm dir — build it with \`node build-tools/cli.js build -t ${profile.sideModuleBuildTargets[id] ?? id}\` and re-export.`);
+ for (const { id, file } of files) {
+ if (existsSync(path.join(wasmDir, `${file}.js`))) { present.push({ id, file }); continue; }
+ const target = profile.sideModuleBuildTargets[id];
+ // No target means the vendor has no build of this module at all, and naming
+ // one that does not exist sends the reader to build the web artifact instead.
+ errors.push(target
+ ? `content needs "${id}" but ${file}.js is not in the ${profile.id} wasm dir — build it with \`node build-tools/cli.js build -t ${target}\` and re-export.`
+ : `content needs "${id}", which has no ${profile.id} build — the module is not available on this platform.`);
}
return present;
}
@@ -279,12 +249,11 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
errors.push(`scene transform: ${err instanceof Error ? err.message : String(err)}`);
}
- // 1b. Scan every scene for the optional modules it needs (physics/spine), so
- // the generated entry requires exactly those — the export-time half of
- // the runtime's self-gating. A dynamically switched scene must find its
- // modules present, so the union over ALL shipped scenes counts.
+ // 1b. Scan the shipped content for the optional modules it needs (physics/spine),
+ // so the generated entry requires exactly those — the export-time half of
+ // the runtime's self-gating.
const engineSideModules = await scanSideModules(
- profile, [...sceneRawByName.values()], cookEntries, absOut, opts.wasmDir, errors,
+ profile, opts.root, cook.includedPaths, cookEntries, absOut, opts.wasmDir, errors,
opts.runtime?.physicsEnabled ?? false,
);
// …plus the ones the PROJECT supplies. They are not scanned for: a project put
diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.ts
index e682317aa..2a08eba19 100644
--- a/pipeline/src/export/exportPlayable.ts
+++ b/pipeline/src/export/exportPlayable.ts
@@ -30,10 +30,7 @@ import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnos
import type { ScreenOrientation } from './orientationHtml';
import { genericPlayableProfile, playableAdInjection, type PlayableAdProfile } from './playableAdProfile';
import { makeZip } from '../../../build-tools/utils/zip.js';
-import {
- sceneUsesPhysics, sceneUses3DPhysics, sceneUsesDragonBones, detectSpineVersion, detectSpineVersionJson,
- spineModuleId, SIDE_MODULE_FILE, type SpineVersion,
-} from '../bundle/sideModuleScan';
+import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';
export interface ExportPlayableResult {
ok: boolean;
@@ -112,52 +109,27 @@ function indexHtml(
}
/**
- * The export-time mirror of the runtime's physics/spine self-gating: scan the
- * scene for needed modules and inline their glue+wasm as base64 (single-file, no
- * fetch). A needed module absent from `wasmDir` is pushed as a HARD error — the
- * playable would otherwise ship silently broken (the bug this whole path fixes).
+ * Inline the glue+wasm of exactly the modules the shipped content can ask for
+ * (single-file, no fetch). A needed module absent from `wasmDir` is pushed as a
+ * HARD error — the playable would otherwise ship silently broken.
*/
async function collectSideModules(
- sceneData: unknown,
+ root: string,
+ includedPaths: readonly string[],
manifestEntries: CookManifest['entries'],
cookDir: string,
wasmDir: string,
errors: string[],
physicsEnabled: boolean,
): Promise<Record<string, { glueBase64: string; wasmBase64: string }>> {
- const ids = new Set<string>();
- // A declared physics project counts as a use even with no bodies in the scene:
- // it spawns them from script, and the flag is worthless without the binary.
- if (physicsEnabled
- || (sceneData && sceneUsesPhysics(sceneData as Parameters<typeof sceneUsesPhysics>[0]))) ids.add('physics');
- // The 3D world is never implied by the 2D flag: a project declaring `physics`
- // is declaring the solver its 2D scenes use, and this module is a different one.
- if (sceneData && sceneUses3DPhysics(sceneData as Parameters<typeof sceneUses3DPhysics>[0])) {
- ids.add('physics3d');
- }
- if (sceneData && sceneUsesDragonBones(sceneData as Parameters<typeof sceneUsesDragonBones>[0])) ids.add('dragonbones');
- // Spine: the skeleton carries the version. Skeleton + atlas share the authored
- // meta type `spine`, so we discriminate by extension (as the runtime does via
- // the asset-type registry's contentType) — `.skel` is a binary skeleton, `.json`
- // a JSON one; the `.atlas` sibling is not a skeleton and is skipped.
- for (const e of manifestEntries) {
- if (e.type !== 'spine') continue;
- const ext = path.extname(e.sourcePath ?? e.path).toLowerCase();
- try {
- let v: SpineVersion | null = null;
- if (ext === '.skel') {
- v = detectSpineVersion(new Uint8Array(await readFile(path.join(cookDir, e.path))));
- } else if (ext === '.json') {
- v = detectSpineVersionJson(await readFile(path.join(cookDir, e.path), 'utf8'));
- }
- if (v) ids.add(spineModuleId(v));
- } catch { /* unreadable cook entry — cookAssets already warned; skip */ }
- }
+ const ids = await scanSideModuleIds({
+ root, includedPaths, cookEntries: manifestEntries, stagedDir: cookDir, physicsEnabled,
+ });
+ const { files, unknown } = sideModuleFiles(ids);
+ for (const id of unknown) errors.push(`internal: no artifact mapping for side module "${id}"`);
const registry: Record<string, { glueBase64: string; wasmBase64: string }> = {};
- for (const id of ids) {
- const file = SIDE_MODULE_FILE[id];
- if (!file) { errors.push(`internal: no artifact mapping for side module "${id}"`); continue; }
+ for (const { id, file } of files) {
const gluePath = path.join(wasmDir, `${file}.js`);
const wasmPath = path.join(wasmDir, `${file}.wasm`);
if (!existsSync(gluePath) || !existsSync(wasmPath)) {
@@ -308,12 +280,12 @@ export async function exportPlayable(opts: {
}
// 5b. Side modules (physics / spine): run the runtime's gating scan, then inline
- // exactly the modules the scene needs (playables are single-file + size-capped).
+ // exactly the modules the content needs (playables are single-file + size-capped).
// A needed module missing from wasmDir is a HARD error — better a failed
// export than a playable that silently ships without physics.
progress({ phase: 'Embedding modules' });
const sideModules = await collectSideModules(
- scenes[0]?.data, manifestEntries, cookDir, opts.wasmDir, errors,
+ opts.root, cook.includedPaths, manifestEntries, cookDir, opts.wasmDir, errors,
opts.runtime?.physicsEnabled ?? false,
);
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index c54c0efbe..40eb97b11 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1447 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1450 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7049,6 +7049,11 @@ name: string
type: "spine"
```
+## SpineVersion — type @experimental
+```
+'2.1' | '3.8' | '4.1' | '4.2' | '4.3'
+```
+
## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
@@ -11341,11 +11346,21 @@ Plugin
(app: App): boolean
```
+## sceneUses3DPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## sceneUsesI18n — function @experimental
```
(sceneData: SceneData): boolean
```
+## sceneUsesPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## scopeDomain — function @experimental
```
(name: string): string
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 2261218ed..b77c95f3f 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 71 beta · 1466 experimental · 3 deprecated
+Symbols: 113 public · 71 beta · 1469 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7242,6 +7242,11 @@ name: string
type: "spine"
```
+## SpineVersion — type @experimental
+```
+'2.1' | '3.8' | '4.1' | '4.2' | '4.3'
+```
+
## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
@@ -11584,11 +11589,21 @@ Plugin
(app: App): boolean
```
+## sceneUses3DPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## sceneUsesI18n — function @experimental
```
(sceneData: SceneData): boolean
```
+## sceneUsesPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## scopeDomain — function @experimental
```
(name: string): string
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 5e0dfed21..407ccc332 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 68 beta · 1446 experimental · 3 deprecated
+Symbols: 113 public · 68 beta · 1449 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7044,6 +7044,11 @@ name: string
type: "spine"
```
+## SpineVersion — type @experimental
+```
+'2.1' | '3.8' | '4.1' | '4.2' | '4.3'
+```
+
## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
@@ -11346,11 +11351,21 @@ Plugin
(app: App): boolean
```
+## sceneUses3DPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## sceneUsesI18n — function @experimental
```
(sceneData: SceneData): boolean
```
+## sceneUsesPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## scopeDomain — function @experimental
```
(name: string): string
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 7bc09fc61..fc9b26f3f 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1467 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1470 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7289,6 +7289,11 @@ name: string
type: "spine"
```
+## SpineVersion — type @experimental
+```
+'2.1' | '3.8' | '4.1' | '4.2' | '4.3'
+```
+
## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
@@ -11596,11 +11601,21 @@ Plugin
(app: App): boolean
```
+## sceneUses3DPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## sceneUsesI18n — function @experimental
```
(sceneData: SceneData): boolean
```
+## sceneUsesPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## scopeDomain — function @experimental
```
(name: string): string
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index cf9221d77..a215db285 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1457 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1460 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7051,6 +7051,11 @@ name: string
type: "spine"
```
+## SpineVersion — type @experimental
+```
+'2.1' | '3.8' | '4.1' | '4.2' | '4.3'
+```
+
## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
@@ -11368,11 +11373,21 @@ Plugin
(app: App): boolean
```
+## sceneUses3DPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## sceneUsesI18n — function @experimental
```
(sceneData: SceneData): boolean
```
+## sceneUsesPhysics — function @experimental
+```
+(sceneData: SceneData): boolean
+```
+
## scopeDomain — function @experimental
```
(name: string): string
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index a182f9945..5b449402e 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -288,6 +288,8 @@ export {
createRuntimeSceneConfig,
initRuntime,
sceneUsesI18n,
+ sceneUsesPhysics,
+ sceneUses3DPhysics,
type RuntimeAssetSource,
type LoadRuntimeSceneOptions,
type RuntimeInitConfig,
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index dd3bd7842..beacfd4d1 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -308,6 +308,7 @@ export {
type SideModuleId,
type BuiltinSideModuleId,
type SideModuleDescriptor,
+ type SpineVersion,
type EmbeddedSideModuleEntry,
type EmbeddedSideModuleRegistry,
type WeChatSideModuleFactories,