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
fix(export): a package carries the modules its content can ask for
yhh68140dbf37e6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 thebuild.** A baked environment names its reflection atlas as a sibling of the`.esenv`, and nothing else in the project mentions that file — so thediff --git a/desktop/tests/export-game.test.ts b/desktop/tests/export-game.test.tsindex 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.tsnew file mode 100644index 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.jsonindex 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.tsindex 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) / subpackagediff --git a/pipeline/src/bundle/sideModuleScan.ts b/pipeline/src/bundle/sideModuleScan.tsindex 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.tsindex 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 findsdiff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.tsindex 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: Rreturn [...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 putdiff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.tsindex 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/bundleDiagnosimport 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.mdindex 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: stringtype: "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): stringdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: stringtype: "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): stringdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: stringtype: "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): stringdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: stringtype: "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): stringdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: stringtype: "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): stringdiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 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,