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 module the project forced in brings its binary too

esengine425018dcf627
diff --git a/pipeline/src/bundle/engineInstalls.ts b/pipeline/src/bundle/engineInstalls.ts
index 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.ts
index 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.ts
index 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.ts
index 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/buildCompiledSys
import { 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 or
diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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);