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 module the project forced in brings its binary too
esengine425018dcf627
diff --git a/pipeline/src/bundle/engineInstalls.ts b/pipeline/src/bundle/engineInstalls.tsindex 5ef24d5d6..4f5ca5fe1 100644--- a/pipeline/src/bundle/engineInstalls.ts+++ b/pipeline/src/bundle/engineInstalls.ts@@ -36,6 +36,21 @@ const SIDE_MODULE_SUBPATH: Readonly<Record<string, string>> = {dragonbones: 'esengine/dragonbones',};+/**+ * Side-module ids a project FORCED in, from the same table the evidence reads.+ *+ * A module reached only from a script leaves no trace for the wasm scan either,+ * so `include` has to reach it: shipping the JS without the binary fails at the+ * first spawn rather than at build time.+ */+export function forcedSideModules(+ choices: Readonly<Record<string, ModuleChoice>>,+): readonly string[] {+ return Object.entries(SIDE_MODULE_SUBPATH)+ .filter(([, subpath]) => choices[subpath] === 'include')+ .map(([id]) => id);+}+/*** What a project SAYS, against what the build detects. Keyed by the subpath the* module is installed from, and absorbing the older `features.physics.enabled`,diff --git a/pipeline/src/bundle/sideModuleScan.ts b/pipeline/src/bundle/sideModuleScan.tsindex 29a78abb4..d48da39ee 100644--- a/pipeline/src/bundle/sideModuleScan.ts+++ b/pipeline/src/bundle/sideModuleScan.ts@@ -48,8 +48,12 @@ export interface SideModuleScanInput {cookEntries: readonly CookEntryLike[];/** Absolute dir `cookEntries[].path` resolve against. */stagedDir: string;- /** Project Settings → Physics enabled. */- physicsEnabled: boolean;+ /**+ * Module ids the project forced in (`features.modules` → `include`), from+ * `forcedSideModules`. A module only a script reaches leaves no trace for this+ * scan either, so the project's word is the evidence.+ */+ forced?: readonly string[];}const VERSION_PREFIXES: ReadonlyArray<readonly [string, SpineVersion]> = [@@ -136,7 +140,8 @@ export async function scanSideModuleIds(input: SideModuleScanInput): Promise<Set// 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');+ for (const id of input.forced ?? []) ids.add(id as SideModuleId);+ if (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');diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 4b0777ddd..b47e77e1a 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -34,7 +34,7 @@ import {DEFAULT_RUNTIME_CONFIG, packagedRuntimeFields, type RuntimeProjectConfig,} from '../project/runtimeConfig';import { engineImportMap, FULL_IMPORT_MAP, LEAN_ENTRY_FILE, FULL_ENTRY_FILE, type EngineImportMap } from '../bundle/importMap';-import { engineInstalls, moduleChoices, type EngineInstallPlan } from '../bundle/engineInstalls';+import { engineInstalls, forcedSideModules, moduleChoices, type EngineInstallPlan } from '../bundle/engineInstalls';import { exportMiniGame } from './exportMiniGame';import { wechatExportProfile, douyinExportProfile } from './miniGameExportProfile';import type { MiniGameExportProfile } from './miniGameExportProfile';@@ -698,6 +698,8 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>title,orientation,minify: opts.minify,+ features: opts.features,+ modulesByPlatform: opts.modulesByPlatform,runtime,adProfile: opts.playableAdProfile,onProgress: opts.onProgress,@@ -823,7 +825,10 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>const sideModuleIds = !nativeContent && existsSync(opts.wasmDir)? await scanSideModuleIds({root: opts.root, includedPaths: cook.includedPaths, cookEntries,- stagedDir: payloadDir, physicsEnabled: runtime.physicsEnabled,+ stagedDir: payloadDir,+ // One path for old and new: moduleChoices reads `physics.enabled` as an+ // include, so the legacy flag arrives here as the choice it always meant.+ forced: forcedSideModules(moduleChoices(opts.features, opts.modulesByPlatform?.[platform])),}): [];/** The subpaths this package installs, and whether a lean entry can carry it.diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.tsindex b26784d3e..2e1c21bbf 100644--- a/pipeline/src/export/exportMiniGame.ts+++ b/pipeline/src/export/exportMiniGame.ts@@ -53,7 +53,7 @@ import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSysimport { resolveEmcc, runEmcc } from '../bundle/emccPath';import type { MiniGameExportProfile, MiniGameVendor } from './miniGameExportProfile';import { contentSubsystems } from './contentSubsystems';-import { engineInstalls, moduleChoices } from '../bundle/engineInstalls';+import { engineInstalls, forcedSideModules, moduleChoices } from '../bundle/engineInstalls';@@ -205,10 +205,10 @@ async function scanSideModules(absOut: string,wasmDir: string,errors: string[],- physicsEnabled: boolean,+ forced: readonly string[],): Promise<Array<{ id: string; file: string }>> {const ids = await scanSideModuleIds({- root, includedPaths, cookEntries, stagedDir: absOut, physicsEnabled,+ root, includedPaths, cookEntries, stagedDir: absOut, forced,});const { files, unknown } = sideModuleFiles(ids);for (const id of unknown) errors.push(`internal: no artifact mapping for side module "${id}"`);@@ -379,7 +379,7 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {// the runtime's self-gating.const engineSideModules = await scanSideModules(profile, opts.root, cook.includedPaths, cookEntries, absOut, opts.wasmDir, errors,- opts.runtime?.physicsEnabled ?? false,+ forcedSideModules(moduleChoices(opts.features, opts.modulesByPlatform?.[profile.id])),);// …plus the ones the PROJECT supplies. They are not scanned for: a project put// them in `.esengine/modules/` in order to use them, and unlike physics ordiff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.tsindex 2e0fea236..3a82cd131 100644--- a/pipeline/src/export/exportPlayable.ts+++ b/pipeline/src/export/exportPlayable.ts@@ -35,6 +35,8 @@ import type { ScreenOrientation } from './orientationHtml';import { genericPlayableProfile, playableAdInjection, type PlayableAdProfile } from './playableAdProfile';import { makeZip } from '../../../build-tools/utils/zip.js';import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';+import { forcedSideModules, moduleChoices } from '../bundle/engineInstalls';+import type { ProjectFeatures, ProjectPackaging } from '../project/format';export interface ExportPlayableResult {ok: boolean;@@ -150,10 +152,10 @@ async function collectSideModules(cookDir: string,wasmDir: string,errors: string[],- physicsEnabled: boolean,+ forced: readonly string[],): Promise<Record<string, { glue: PackedBytes; wasm: PackedBytes }>> {const ids = await scanSideModuleIds({- root, includedPaths, cookEntries: manifestEntries, stagedDir: cookDir, physicsEnabled,+ root, includedPaths, cookEntries: manifestEntries, stagedDir: cookDir, forced,});const { files, unknown } = sideModuleFiles(ids);for (const id of unknown) errors.push(`internal: no artifact mapping for side module "${id}"`);@@ -208,6 +210,10 @@ export async function exportPlayable(opts: {* to the pixel). An explicit `false` is still honoured.*/minify?: boolean;+ /** What the project says about its engine modules; see ProjectFeatures.modules. */+ features?: ProjectFeatures;+ /** Per-target overrides laid over those. */+ modulesByPlatform?: ProjectPackaging['modulesByPlatform'];/** The project's runtime settings, derived once by `runtimeConfigOf`; the page* carries the packaged slice of them as one global the host reads. */runtime?: RuntimeProjectConfig;@@ -344,7 +350,7 @@ export async function exportPlayable(opts: {progress({ phase: 'Embedding modules' });const sideModules = await collectSideModules(opts.root, cook.includedPaths, manifestEntries, cookDir, opts.wasmDir, errors,- opts.runtime?.physicsEnabled ?? false,+ forcedSideModules(moduleChoices(opts.features, opts.modulesByPlatform?.playable)),);// 6. Assemble the single HTML, then drop the temp cook dir.diff --git a/pipeline/tests/engine-installs.test.ts b/pipeline/tests/engine-installs.test.tsindex f443a4529..e37b21f83 100644--- a/pipeline/tests/engine-installs.test.ts+++ b/pipeline/tests/engine-installs.test.ts@@ -9,7 +9,7 @@* fine — it was never installed.*/import { describe, it, expect } from 'vitest';-import { engineInstalls, moduleChoices } from '../src/bundle/engineInstalls';+import { engineInstalls, forcedSideModules, moduleChoices } from '../src/bundle/engineInstalls';import { ENGINE_MODULES, ESENGINE_SUBPATHS } from '../src/bundle/engineSubpaths';import { SUBSYSTEM_COMPONENTS, SUBSYSTEM_INSTALL, type Subsystem } from '../src/project/targetSupport';@@ -221,3 +221,34 @@ describe('a project that answers differently per target', () => {.refused.map((r) => r.specifier)).toEqual(['esengine/physics3d']);});});++/**+ * A module only a script reaches leaves no trace for the WASM scan either, so+ * `include` has to name it there too — otherwise a project that spawns bodies+ * from code ships the solver's JS and no binary to run.+ */+describe('a side module the project forced in', () => {+ it('is named for the wasm scan, not only for the JS', () => {+ expect(forcedSideModules(moduleChoices({ modules: { 'esengine/physics': 'include' } })))+ .toEqual(['physics']);+ });++ it('comes through the older physics.enabled by the same path', () => {+ expect(forcedSideModules(moduleChoices({ physics: { enabled: true } })))+ .toEqual(['physics']);+ });++ it('covers every module that has a binary of its own', () => {+ const all = { modules: {+ 'esengine/physics': 'include', 'esengine/physics3d': 'include',+ 'esengine/dragonbones': 'include',+ } } as const;+ expect([...forcedSideModules(moduleChoices(all))].sort())+ .toEqual(['dragonbones', 'physics', 'physics3d']);+ });++ it('names nothing for a module with no binary, or for one merely detected', () => {+ expect(forcedSideModules(moduleChoices({ modules: { 'esengine/tilemap': 'include' } }))).toEqual([]);+ expect(forcedSideModules(moduleChoices({ modules: { 'esengine/physics': 'exclude' } }))).toEqual([]);+ });+});diff --git a/pipeline/tests/export-engine-installs.test.ts b/pipeline/tests/export-engine-installs.test.tsindex 0e309bf88..9355f530f 100644--- a/pipeline/tests/export-engine-installs.test.ts+++ b/pipeline/tests/export-engine-installs.test.ts@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url';import { exportGame } from '../src/export/exportGame';import { writeFakeSdkDist } from './fixtures/fakeSdkDist';import type { ModuleChoice } from '../src/project/format';+import { moduleOfComponent } from '../src/project/targetSupport';const HERE = path.dirname(fileURLToPath(import.meta.url));const HOSTS = path.join(HERE, '..', 'src', 'runtime');@@ -173,3 +174,39 @@ describe('a web package whose project excluded a module', () => {} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }});});++/**+ * The page shows the components its documents carry; the build has more evidence+ * than that. So the two are not equal — but everything the page calls used has+ * to be installed, or a creator is told a module ships and it does not.+ */+describe('what the page says and what the build installs', () => {+ const pageWouldSay = (components: string[]): string[] => {+ const used = new Set<string>();+ for (const name of components) {+ const module = moduleOfComponent(name);+ if (module !== null) used.add(module);+ }+ return [...used].sort();+ };++ it('agree for content that uses several modules', async () => {+ const f = setup(['Tilemap', 'NavAgent', 'Health']);+ try {+ await run(f);+ const page = pageWouldSay(['Tilemap', 'NavAgent', 'Health']);+ expect(page).toEqual(['esengine/ai', 'esengine/gameplay', 'esengine/tilemap']);+ const game = readFileSync(path.join(f.out, 'game.js'), 'utf8');+ for (const module of page) expect(game).toContain(`import ${JSON.stringify(module)}`);+ } finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }+ });++ it('agree that nothing optional is used, for content that uses none', async () => {+ const f = setup(['Transform', 'Sprite']);+ try {+ await run(f);+ expect(pageWouldSay(['Transform', 'Sprite'])).toEqual([]);+ expect(readFileSync(path.join(f.out, 'game.js'), 'utf8')).not.toContain('import "esengine/');+ } finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }+ });+});diff --git a/pipeline/tests/export-playable.test.ts b/pipeline/tests/export-playable.test.tsindex 31c15d5b6..f4575b896 100644--- a/pipeline/tests/export-playable.test.ts+++ b/pipeline/tests/export-playable.test.ts@@ -371,6 +371,9 @@ export function packagedRuntimeInit(c){return c;}\n`);const res = await exportGame({root: r, entryScene: 'scenes/main.esscene', hostsDir: HOSTS,sdkDistDir: path.join(r, '_sdk'), wasmDir: path.join(r, '_wasm'), outDir: o, platform: 'playable',+ // The project's declaration, which is what the build reads; `runtime` is+ // the packaged game's copy of the same manifest, not a second authority.+ features: { physics: { enabled: true, gravity: { x: 0, y: -20 } } },runtime: runtimeConfigOf({ features: { physics: { enabled: true, gravity: { x: 0, y: -20 } } } }),});expect(res.ok).toBe(true);diff --git a/pipeline/tests/export-side-modules.test.ts b/pipeline/tests/export-side-modules.test.tsindex 5bb8521d6..a72d02a19 100644--- a/pipeline/tests/export-side-modules.test.ts+++ b/pipeline/tests/export-side-modules.test.ts@@ -48,10 +48,14 @@ function setup(scene: unknown, extra?: (root: string) => void): Fixture {return { root, out: path.join(root, 'dist') };}-const run = (f: Fixture, runtime?: Parameters<typeof exportGame>[0]['runtime']) => exportGame({+const run = (+ f: Fixture,+ runtime?: Parameters<typeof exportGame>[0]['runtime'],+ features?: Parameters<typeof exportGame>[0]['features'],+) => exportGame({root: f.root, entryScene: 'scenes/main.esscene', hostsDir: HOSTS,sdkDistDir: path.join(f.root, '_sdk'), wasmDir: path.join(f.root, '_wasm'),- outDir: f.out, ...(runtime ? { runtime } : {}),+ outDir: f.out, ...(runtime ? { runtime } : {}), ...(features ? { features } : {}),});/** The module artifact base names the package actually carries. */@@ -86,7 +90,10 @@ describe('web package side modules', () => {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 } } }));+ // The project's declaration, which is what the build reads: `runtime` is+ // the packaged game's copy of the same manifest, not a second authority.+ const features = { physics: { enabled: true } };+ await run(f, runtimeConfigOf({ features }), features);expect(shipped(f.out)).toEqual(['physics']);} finally { rmSync(f.root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); }}, 60_000);