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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file Mini-game export pipeline (REARCH_EXPORT E2), shared by every vendor.
*
* Assembles a project into the exact shape the shipped runtime
* `initWeChatRuntime` / `initMiniGameRuntime` consumes — correct-by-
* construction against that contract (this sandbox has no mini-game
* devtools, so runtime correctness is validated by the user in devtools):
*
* asset-manifest.json AddressableManifest (groups.<g>.assets[uuid] = {path,…});
* the resolver keys by uuid → path.
* scenes/<name>.json the entry scene, refs as authored (`@uuid:` like the web package).
* game-bundle.js esbuild CJS of [the vendor SDK (esengine aliased) +
* project scripts + a boot()] — one esengine instance
* so custom components/systems run.
* game.js the MiniGame entry: require the wasm factory + boot.
* wasm/ the vendor engine runtime (WXWebAssembly glue).
* game.json / project.config.json MiniGame config (per profile).
*
* Everything vendor-specific — the config/entry files, the packaging
* suffix policy, the SDK entry + glue names, the es-target floor — is a
* field/hook on the passed `MiniGameExportProfile`. Adding Douyin is one
* profile, not a fork of this file.
*
* Unlike web/desktop (which share the import-map web payload), mini-games
* have no import maps and a different module/asset model, so this is its
* own path. Pure Node (esbuild + fs) — IPC wiring is in main.ts.
*/
import { minifiesScripts } from './scriptMinify';
import type { DebugChannelConfig } from 'esengine';
import { packagedDebugChannel } from './debugChannel';
import { packagedHotUpdate } from './hotUpdateConfig';
import { loadEsbuild } from '../bundle/esbuildRuntime';
import { liteEngineAnswer, scriptsMentionOmitted, scriptsMentionSkeletal } from './liteEngine';
import type { ModuleChoice, ProjectFeatures, ProjectPackaging } from '../project/format';
import {
DEFAULT_RUNTIME_CONFIG, packagedRuntimeFields, withAudioLoadTypes, type RuntimeProjectConfig,
} from '../project/runtimeConfig';
import { writeFile, mkdir, cp, readFile, rename, rm } from 'node:fs/promises';
import { brotliCompress as brotliCompressCb, constants as zlibConstants } from 'node:zlib';
import { promisify } from 'node:util';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets, type Inclusion } from '../assets/cookAssets';
import { buildAddressableManifest } from '../assets/addressableManifest';
import type { ExportScene } from './exportGame';
import type { OnExportProgress } from './exportProgress';
import { runtimeHostEntry } from '../bundle/runtimeHosts';
import { breakdownOf, type ModuleBytes } from './bundleBreakdown';
import { esengineAlias } from '../bundle/esengineResolve';
import { officialPackagesPlugin } from '../bundle/officialPackages';
import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';
import { planSideModules, spineRefusalMessage, sideModuleFiles, textureDecoderBytes, type SpineRuntimePlan } from '../bundle/sideModuleScan';
import { exportedAssetFiles, pruneExportedAssets } from './assetCleanup';
import { OPEN_DATA_DIR, isEsModule } from './miniGameExportProfile';
import type { RpkSigningKey } from './rpk';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSystems';
import { resolveEmcc, runEmcc } from '../bundle/emccPath';
import type { MiniGameExportProfile, MiniGameVendor } from './miniGameExportProfile';
import { contentSubsystems } from './contentSubsystems';
import type { Physics3DBackend } from 'esengine';
import { engineInstalls, forcedSideModules, moduleChoices } from '../bundle/engineInstalls';
/** The icon's bytes, or null. A path that no longer exists is a warning: the
* package is still correct, it just carries the vendor profile's default. */
async function readAppIcon(root: string, rel: string | undefined, warnings: string[]): Promise<Uint8Array | null> {
if (!rel) return null;
const file = path.join(root, rel);
if (existsSync(file)) return new Uint8Array(await readFile(file));
warnings.push(`The app icon ${rel} does not exist — packaged with the default.`);
return null;
}
export interface ExportMiniGameResult {
ok: boolean;
platform: MiniGameVendor;
outDir: string;
included: number;
warnings: string[];
errors: string[];
/** Each Spine runtime, whether this package carries it, and why. */
spineRuntimes?: SpineRuntimePlan['decisions'];
/** @internal Why each asset is in the build; the size report consumes and drops it. */
inclusion?: Record<string, Inclusion>;
/** What each subsystem costs inside `game-bundle.js`, largest first. The bundle
* is the main package's biggest file once the engine binary can move out, and
* a vendor's brotli path does not take `.js`, so this is where the remaining
* room is. */
bundleModules?: ModuleBytes[];
/** Project-relative subpackage roots — what is NOT on the main package's cap. */
subPackageRoots?: string[];
/** The single file the vendor takes, when it takes one (a quick game's `.rpk`). */
packageFile?: string;
/** Staged path → what that file weighed before this export packed it. A limit
* is judged on packed bytes, so the report has no other way to know. */
packedFrom?: Record<string, number>;
}
interface CookManifest {
entries: {
uuid: string; path: string; sourcePath?: string; type: string;
contentHash?: string; size?: number; group?: string; groupMode?: string;
atlas?: { page: number; frame: { x: number; y: number; width: number; height: number }; pageWidth: number; pageHeight: number };
}[];
}
const brotliPack = promisify(brotliCompressCb);
/** What this export stages into `wasm/`, and the engine path the loader is told. */
interface RuntimeLayout {
/** Package-relative path the boot config hands the loader. */
readonly enginePath: string;
/** Package-relative directory the runtime artifacts land in, as the generated
* entry requires them (`./wasm/`) — one author for where they are and where
* they are asked for. */
readonly runtimeDir: string;
/** Engine artifacts to stage: the name in `wasmDir` → the PACKAGE-RELATIVE path
* it lands at, so a binary that moves into a 分包 is the same list with a
* different path rather than a second staging rule. */
readonly files: ReadonlyArray<{ readonly src: string; readonly staged: string; readonly brotli?: true }>;
/** The 分包 the engine binary went into, for the host config to declare. */
readonly subpackage: { readonly name: string; readonly root: string } | null;
/** Suffix the side-module binaries landed under, for the boot config. */
readonly sideModuleSuffix: string;
}
/**
* Decided ONCE, read by the boot config and the copy loop: what lands is what
* the loader is told. The side modules compress with the engine — the mini-game
* transport is TOLD the suffix (`sideModuleSuffix`) rather than spelling it.
*/
const ENGINE_SUBPACKAGE = 'engine';
/** What a compressed binary is called. The vendor's loader takes this path
* verbatim, so the package carries one binary per module, not two. */
const BROTLI_SUFFIX = '.wasm.br';
function planRuntimeLayout(
engineGlueFile: string,
sideModules: ReadonlyArray<{ file: string }>,
opts: { brotli: boolean; subpackage: boolean; subpackageDir: string },
): RuntimeLayout {
const engineBinary = engineGlueFile.replace(/\.js$/, '.wasm');
const engineName = opts.brotli ? `${engineBinary}.br` : engineBinary;
// Only the BINARY moves. The glue is `require`d by the entry, and a 分包's files
// are not requirable before the host has loaded it — so it stays beside game.js,
// which is where every engine that ships this keeps it.
const root = `${opts.subpackageDir}/${ENGINE_SUBPACKAGE}`;
const enginePath = opts.subpackage ? `${root}/${engineName}` : `wasm/${engineName}`;
const binary = opts.brotli
? { src: engineBinary, staged: enginePath, brotli: true as const }
: { src: engineBinary, staged: enginePath };
const sideModuleSuffix = opts.brotli ? BROTLI_SUFFIX : '.wasm';
return {
enginePath,
runtimeDir: 'wasm',
subpackage: opts.subpackage ? { name: ENGINE_SUBPACKAGE, root } : null,
sideModuleSuffix,
files: [
{ src: engineGlueFile, staged: `wasm/${engineGlueFile}` },
binary,
...sideModules.flatMap((m) => [
{ src: `${m.file}.js`, staged: `wasm/${m.file}.js` },
// The glue stays raw: a vendor's brotli path takes wasm, not `.js`.
opts.brotli
? { src: `${m.file}.wasm`, staged: `wasm/${m.file}${sideModuleSuffix}`, brotli: true as const }
: { src: `${m.file}.wasm`, staged: `wasm/${m.file}.wasm` },
]),
],
};
}
/**
* The vendor subPackage roots this package actually carries, read off the STAGED
* paths: a root the package lacks fails the whole game at load ("root 不存在").
* Only LAZY delivery is a 分包 — a group's name outlives its delivery, so a
* project that once had one still carries the name of one.
*/
function subPackagesOf(
entries: CookManifest['entries'],
subpackageDir: string,
): { subPackages: Array<{ name: string; root: string }>; strays: string[] } {
const carried = new Set<string>();
const strays: string[] = [];
for (const e of entries) {
if (!e.group || e.group === 'main' || e.groupMode !== 'lazy') continue;
const root = `${subpackageDir}/${e.group}`;
if (e.path === root || e.path.startsWith(`${root}/`)) carried.add(e.group);
else strays.push(`${e.sourcePath} is in 分包 '${e.group}' but ships at ${e.path}, outside ${root}/`);
}
return {
subPackages: [...carried].map((name) => ({ name, root: `${subpackageDir}/${name}` })),
strays,
};
}
/** packOptions.include suffix rules for every custom extension the cook staged.
* Extensions the packer/fs handles without an entry (script + config it compiles
* itself) are excluded via `nativeSuffixes`; the rest get an include rule —
* mini-game packers deny fs reads of unlisted custom types (.skel/.atlas/.ktx2). */
function packIncludeSuffixes(entries: CookManifest['entries'], nativeSuffixes: ReadonlySet<string>): string[] {
const suffixes = new Set<string>();
for (const e of entries) {
const ext = path.extname(e.path).toLowerCase();
if (ext && !nativeSuffixes.has(ext)) suffixes.add(ext);
}
return [...suffixes].sort();
}
/** 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,
root: string,
includedPaths: readonly string[],
cookEntries: CookManifest['entries'],
absOut: string,
wasmDir: string,
errors: string[],
forced: readonly string[],
physics3dBackend: Physics3DBackend | undefined,
choices: Readonly<Record<string, ModuleChoice>>,
onSpine: (plan: SpineRuntimePlan) => void,
): Promise<Array<{ id: string; file: string }>> {
// One decision for every target (resolveSpineRuntimes): a mini-game pays for
// each Spine runtime it carries, and fails to boot a skeleton whose runtime it
// dropped, so the project's per-runtime choice is applied here too.
const { ids, spine } = await planSideModules({
root, includedPaths, cookEntries, stagedDir: absOut, forced, physics3dBackend, choices,
});
for (const r of spine.refused) errors.push(spineRefusalMessage(r));
onSpine(spine);
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, 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;
}
/**
* Export the open project as a mini-game for `profile`'s vendor into `outDir`.
* `sdkDir` is the SDK dist dir the bundle aliases `esengine` to (the vendor
* build, profile.sdkEntryFile); `wasmDir` the vendor engine runtime to copy.
*/
export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
root: string;
entryScene: string;
/** Every switchable scene to ship (name + project-relative path, entry
* included) — discovered by exportGame. Absent: the entry scene only. */
scenes?: ExportScene[];
scriptsEntry?: string;
sdkDir: string;
wasmDir: string;
/** WeChat: ship the engine built with EmscriptenGLX, from the `-glx` runtime
* beside `wasmDir`; the side modules still come from `wasmDir`. */
engineGlx?: boolean;
outDir: string;
/** Where the runtime hosts live — sources in dev, a prebuilt tree in a packaged
* editor. A built-in vendor's platform profile is resolved against it. */
hostsDir: string;
/** The official `estella-plugin-*` packages the editor ships (`plugins/`);
* a project's scripts resolve them from here. */
packagesDir: string;
title?: string;
/** MiniGame appid (Project Settings) → project config. */
appid?: string;
/** The project's version (ProjectManifest.version), for a host config that asks. */
appVersion?: string;
/** The build ordinal, for a host that compares packages by it. Absent ⇒ 1. */
versionCode?: number;
/** The app icon, project-relative (packaging.icon). */
appIcon?: string;
/** The project's signing key, for a vendor that takes a signed file. */
releaseKey?: RpkSigningKey;
/** Screen orientation (Project Settings) → game.json. */
orientation?: 'portrait' | 'landscape';
/** The project's runtime settings, derived once by `runtimeConfigOf`; the
* generated boot passes the packaged slice of them to the vendor runtime. */
runtime?: RuntimeProjectConfig;
minify?: boolean;
minifyScripts?: boolean;
debugChannel?: DebugChannelConfig | null;
/** Overrides the project's own CDN root / persistence key (see `packagedHotUpdate`). */
hotUpdate?: { remoteRoot?: string; persistUpdateKey?: string };
/**
* Where emcc is, for the systems a project marked `@compiled`
* (docs/REARCH_AOT.md). Absent ⇒ found from the environment; a project that
* promised nothing never needs one.
*/
emcc?: string | null;
/** Whether this export compiles `@compiled` systems; see exportGame. */
aotMode?: BuildMode;
/** Content-addressed asset filenames (<hash><ext>), on unless turned off: a remote
* asset whose content changed must have a new URL, or a hot update and the CDN
* serve the old bytes under it. */
contentAddressed?: boolean;
/** Encode raster textures to GPU-compressed KTX2 at cook time. */
compressTextures?: boolean;
compressAudio?: boolean;
/** Pack `<name>.atlas/` folder PNGs into atlas pages at cook time. */
atlasTextures?: boolean;
/** The project's `packaging.compressWasm`; honoured only where the vendor can
* load a `.wasm.br` (profile.wasmBrotli) — policy meeting capability. */
compressWasm?: boolean;
/** The project's `packaging.engineSubpackage`: move the engine binary out of
* the main package into a 分包 the host loads at startup. */
engineSubpackage?: boolean;
/** What the project says about its engine modules; see ProjectFeatures.modules. */
features?: ProjectFeatures;
/** Per-target overrides laid over those. */
modulesByPlatform?: ProjectPackaging['modulesByPlatform'];
onProgress?: OnExportProgress;
}): Promise<ExportMiniGameResult> {
const title = opts.title ?? 'Game';
const absOut = path.isAbsolute(opts.outDir) ? opts.outDir : path.join(opts.root, opts.outDir);
const progress = opts.onProgress ?? (() => {});
const warnings: string[] = [];
const errors: string[] = [];
// 0. The generated entry unconditionally requires the engine glue, so a
// missing vendor runtime cannot produce a runnable package — fail before
// cooking. By its ACTUAL name in the wasm dir; see MINIGAME_ENGINE_GLUE.
const glxDir = `${opts.wasmDir.replace(/[\\/]+$/, '')}-glx`;
const glx = opts.engineGlx === true && profile.id === 'wechat';
if (glx && !profile.engineGlueCandidates.some((f) => existsSync(path.join(glxDir, f)))) {
errors.push(`this project renders through EmscriptenGLX, and there is no GLX engine in ${glxDir} — `
+ 'build it with `node build-tools/cli.js build -t wechat-glx`, or turn EmscriptenGLX off in Project Settings → WeChat');
return { ok: false, platform: profile.id, outDir: absOut, included: 0, warnings, errors };
}
// The engine without particles, post-processing and tilemaps, beside the full one: used when the content says it needs none
// (decided once the content has been read, below, and before any engine file is staged).
const liteDir = `${opts.wasmDir.replace(/[\/]+$/, '')}-lite`;
let lite = false;
/** The engine's own files come from the GLX runtime when the project asked for it, or the lite one when it can. */
const runtimeFile = (name: string): string => {
const fromGlx = path.join(glxDir, name);
if (glx && existsSync(fromGlx)) return fromGlx;
const fromLite = path.join(liteDir, name);
return lite && existsSync(fromLite) ? fromLite : path.join(opts.wasmDir, name);
};
const engineGlueFile = profile.engineGlueCandidates
.find((f) => existsSync(runtimeFile(f)));
if (!engineGlueFile) {
// The optional-module targets come off the profile, so the guidance names
// THIS vendor's builds rather than a hardcoded WeChat pair.
const moduleTargets = [...new Set(Object.values(profile.sideModuleBuildTargets))];
errors.push(
`${profile.id} engine runtime not found in ${opts.wasmDir} — ` +
`build it with \`node build-tools/cli.js build -t ${profile.wasmBuildHint}\`` +
(moduleTargets.length > 0
? ` (optional modules build separately: ${moduleTargets.map((t) => `-t ${t}`).join(' / ')})`
: ''),
);
return { ok: false, platform: profile.id, outDir: absOut, included: 0, warnings, errors };
}
// ...and it has to be a build this host can load. The browser artifact throws
// `Unexpected token 'export'` at the entry's first line: a package that exports
// clean, installs, and never reaches a frame.
if (isEsModule(await readFile(runtimeFile(engineGlueFile), 'utf8'))) {
errors.push(
`${runtimeFile(engineGlueFile)} is an ES module, and a ${profile.id} package requires its engine — `
+ `build the mini-game engine with \`node build-tools/cli.js build -t ${profile.wasmBuildHint}\``,
);
return { ok: false, platform: profile.id, outDir: absOut, included: 0, warnings, errors };
}
await mkdir(absOut, { recursive: true });
const previousAssets = await exportedAssetFiles(absOut);
// Every switchable scene ships; the exporter's caller (exportGame) discovers
// them from the project's scenes dir. Absent (tests / direct calls): entry only.
const scenes: ExportScene[] = opts.scenes ?? [
{ name: path.basename(opts.entryScene).replace(/\.[^.]+$/, ''), path: opts.entryScene.replace(/\\/g, '/') },
];
const sceneName = scenes.find((s) => s.path === opts.entryScene.replace(/\\/g, '/'))?.name ?? scenes[0].name;
// 1. Cook reachable assets from every scene root (paths preserved) + the flat
// manifest. KTX2 textures are fine here: the scan below sees the staged
// .ktx2 files and ships the Basis transcoder side module with them.
progress({ phase: 'Cooking assets' });
// `platform: profile.id` — the cook reads each texture's per-platform Import
// Settings under this key, so a vendor must cook against ITS OWN overrides.
const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: absOut, contentAddressed: opts.contentAddressed ?? true, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo: true, platform: profile.id, textureDecoderBytes: textureDecoderBytes(opts.wasmDir) });
warnings.push(...cook.warnings);
for (const file of cook.failed) errors.push(`asset not packaged — ${file}`);
// 1a. Anything the packer will not upload ships as `<name>.<ext>.bin`. Scenes
// have their own transform below (`<x>.esscene` → `scenes/<name>.json`).
progress({ phase: 'Transforming scenes' });
const needsRestage = (p: string): boolean => {
if (!profile.packerSuffixes) return false;
const ext = path.extname(p).slice(1).toLowerCase();
return ext !== '' && !profile.packerSuffixes.has(ext);
};
const flatManifestPath = path.join(absOut, 'assets.manifest.json');
let cookEntries: CookManifest['entries'] = [];
const sceneRawByName = new Map<string, unknown>();
/** Where a staged file went, so a second entry naming it does not move it again. */
const restaged = new Map<string, string>();
try {
const flat = JSON.parse(await readFile(flatManifestPath, 'utf8')) as CookManifest;
for (const e of flat.entries) {
// Scenes FIRST: they have a transform of their own below, which leaves a
// `.json` the packer takes. Restaging one would ship the authored file
// beside the transformed one, under a name nothing reads.
const scene = scenes.find((s) => s.path === e.path);
if (!scene && needsRestage(e.path)) {
// Assets share an output freely — every sprite packed into an atlas
// names the same page — so the file moves once and the rest follow it.
let moved = restaged.get(e.path);
if (moved === undefined) {
moved = `${e.path}.bin`;
await rename(path.join(absOut, e.path), path.join(absOut, moved));
restaged.set(e.path, moved);
}
e.path = moved;
continue;
}
if (scene) {
const staged = path.join(absOut, e.path);
const raw = JSON.parse(await readFile(staged, 'utf8'));
sceneRawByName.set(scene.name, raw);
const outPath = `scenes/${scene.name}.json`;
await mkdir(path.dirname(path.join(absOut, outPath)), { recursive: true });
await writeFile(path.join(absOut, outPath), JSON.stringify(raw) + '\n');
await rm(staged, { force: true });
e.path = outPath;
}
}
await writeFile(flatManifestPath, JSON.stringify(flat, null, 2));
cookEntries = flat.entries;
} catch (err) {
errors.push(`scene transform: ${err instanceof Error ? err.message : String(err)}`);
}
// 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 moduleChoiceMap = moduleChoices(opts.features, opts.modulesByPlatform?.[profile.id]);
let spineRuntimes: SpineRuntimePlan['decisions'] | undefined;
const engineSideModules = await scanSideModules(
profile, opts.root, cook.includedPaths, cookEntries, absOut, opts.wasmDir, errors,
forcedSideModules(moduleChoiceMap),
opts.features?.physics?.backend3d,
moduleChoiceMap,
(spine) => { spineRuntimes = spine.decisions; },
);
// …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
// spine there is no component in the scene the engine could recognize as the
// thing that needs one. Staged and required by the same code path, so a
// third-party runtime loads on a device exactly like a built-in.
const projectModules = await loadProjectModules(opts.root, profile.id);
const sideModules = [
...engineSideModules,
...projectModules.filter((m) => m.buildDir).map((m) => ({ id: m.id, file: m.file })),
];
const sceneRaw = sceneRawByName.get(sceneName) ?? null;
if (!sceneRaw) errors.push(`entry scene "${opts.entryScene}" was not staged by the cook`);
// 2. Flat manifest → AddressableManifest (asset-manifest.json); drop the web one.
progress({ phase: 'Building manifest' });
try {
await writeFile(path.join(absOut, 'asset-manifest.json'), await buildAddressableManifest(absOut));
if (cook.failed.length === 0) await pruneExportedAssets(absOut, opts.root, previousAssets);
await rm(path.join(absOut, 'assets.manifest.json'), { force: true });
} catch (err) {
errors.push(`manifest: ${err instanceof Error ? err.message : String(err)}`);
}
// 4. game-bundle.js — vendor SDK (esengine aliased) + project scripts + boot(),
// one esengine instance so the project's defineComponent/defineSystem run.
const scriptsAbs = opts.scriptsEntry ? path.join(opts.root, opts.scriptsEntry) : null;
// Compressing needs both halves: a vendor whose loader takes `.wasm.br`, and a
// project that asked for it. Either alone leaves the binary as built.
const brotli = profile.wasmBrotli && (opts.compressWasm ?? false);
const runtimeLayout = planRuntimeLayout(engineGlueFile, engineSideModules, {
brotli,
// No API global ⇒ nothing to ask for the 分包 with, so it stays in the main package.
subpackage: profile.hostGlobal !== null && profile.subpackageDir !== '' && (opts.engineSubpackage ?? false),
subpackageDir: profile.subpackageDir,
});
const engineWasmPath = runtimeLayout.enginePath;
// The packaged slice of the project's settings, GENERATED rather than listed:
// a setting added to packagedRuntimeFields reaches this boot without anyone
// having to remember that this template exists. Theme colours are the one that
// is not a plain value — the runtime takes parsed overrides, so a call is
// emitted for them instead.
// Every mini-game vendor gives the runtime a GL context and nothing else, so
// a WebGPU request cannot be honoured here — carrying it would be a config
// field the runtime is guaranteed to ignore.
const { renderBackend: _webgpuNotHere, ...packaged } =
packagedRuntimeFields(withAudioLoadTypes(opts.runtime ?? DEFAULT_RUNTIME_CONFIG, cook.audioLoadTypes, cook.audioEncoded));
const themeColors = packaged.uiThemeColors;
const runtimeArgs = Object.entries(packaged)
.map(([k, v]) => (k === 'uiThemeColors'
? `, uiThemeOverrides: parseThemeOverrides(${JSON.stringify(v)})`
: `, ${k}: ${JSON.stringify(v)}`))
.join('');
const debugChannel = packagedDebugChannel(opts);
const debugArg = debugChannel ? `, debugChannel: ${JSON.stringify(debugChannel)}` : '';
const hotUpdate = await packagedHotUpdate(opts.root, opts.hotUpdate);
const hotUpdateArg = hotUpdate ? `, hotUpdate: ${JSON.stringify(hotUpdate)}` : '';
// esengine/minigame installs no platform until a host is named, so boot() names
// one: a built-in points at a shipped module, a project vendor at a file beside
// its own platform. Unjoined, the package builds and throws on the device.
const platformProfileModule = profile.runtimeProfileHost
? runtimeHostEntry(opts.hostsDir, profile.runtimeProfileHost)
: profile.runtimeProfileModule;
const installsPlatform = !!platformProfileModule;
// A mini-game does not read game.config.json — its configuration IS this
// generated call — so the project modules' artifact names ride it here. The
// factories arrive separately (game.js require()s the glue); this is what tells
// the runtime where each binary sits in the package.
const projectDeclarations = sideModuleDeclarations(projectModules, profile.id);
// The compiled twins, staged as a package file and named in the boot call —
// the target AOT exists for (docs/REARCH_AOT.md §1.1: iOS mini-games have no
// JIT). A PATH, because WXWebAssembly cannot compile bytes.
const built = await buildCompiledSystems(opts.root, {
mode: opts.aotMode ?? 'release', cc: resolveEmcc(opts.emcc), run: runEmcc,
});
if (!built.ok) {
errors.push(...built.errors);
return { ok: false, platform: profile.id, outDir: absOut, included: cook.included.length, warnings, errors };
}
let aotArg = '';
if (built.modulePath && built.manifest) {
progress({ phase: 'Compiling systems', detail: `${built.manifest.systems.length} system(s)` });
await mkdir(path.join(absOut, 'aot'), { recursive: true });
await cp(built.modulePath, path.join(absOut, 'aot', 'systems.wasm'));
aotArg = `, aot: ${JSON.stringify({ module: 'aot/systems.wasm', manifest: built.manifest })}`;
}
// What this project installs on a lean entry — the same answer the web export
// gets, from the same evidence, so a subsystem cannot be installed on one
// target and silently missing on the other.
const usedSubsystems = await contentSubsystems(opts.root, cook.includedPaths);
// A script can add an Animator to a world no scene mentioned, and the name is exported from `esengine` itself.
const needsSkeletal = !usedSubsystems.has('skeletalAnimation') && await scriptsMentionSkeletal(opts.root, opts.scriptsEntry);
const plan = engineInstalls({
subsystems: needsSkeletal ? [...usedSubsystems.keys(), 'skeletalAnimation'] : usedSubsystems.keys(),
assetPaths: cook.includedPaths,
sideModuleIds: sideModules.map((m) => m.id),
choices: moduleChoices(opts.features, opts.modulesByPlatform?.[profile.id]),
debugChannel: !!debugChannel,
});
// The lite engine, when this vendor has one and nothing in the content or the scripts reaches what it leaves out.
lite = !glx && liteEngineAnswer({
subsystems: usedSubsystems.keys(),
scriptsMention: await scriptsMentionOmitted(opts.root, opts.scriptsEntry),
choices: moduleChoices(opts.features, opts.modulesByPlatform?.[profile.id]),
}) && profile.engineGlueCandidates.some((f) => existsSync(path.join(liteDir, f)));
if (lite) progress({ phase: 'Choosing engine', detail: 'lite (no particles, post-processing or tilemaps in the content)' });
// A package missing half a scene, with nothing saying which half, is worse than
// one that refuses to be made.
for (const r of plan.refused) {
errors.push(`${r.specifier} is excluded in Project Settings, and this build uses it — `
+ `${r.evidence}. Set it to Auto or Include, or take it out of the content.`);
}
// Only when the SDK build actually produced one: a tree without it (an older
// dist, a test fixture) must fall back to the whole entry rather than alias
// `esengine` to a file that is not there.
const leanEntry = profile.sdkLeanEntryFile
&& existsSync(path.join(opts.sdkDir, profile.sdkLeanEntryFile))
? profile.sdkLeanEntryFile : null;
const lean = !!leanEntry && plan.lean;
const installs = lean ? plan.subpaths : [];
const entrySrc =
installs.map((m) => `import ${JSON.stringify(m)};\n`).join('') +
`import { ${profile.runtimeInit}${profile.platformInit ? `, ${profile.platformInit}` : ''}${installsPlatform ? ', installMiniGamePlatform' : ''}${themeColors ? ', parseThemeOverrides' : ''} } from 'esengine';\n` +
(installsPlatform ? `import __platformProfile from ${JSON.stringify(platformProfileModule)};\n` : '') +
(scriptsAbs && existsSync(scriptsAbs) ? `import ${JSON.stringify(scriptsAbs)};\n` : '') +
`export function boot(engineFactory, sideModuleFactories) {\n` +
(profile.platformInit ? ` ${profile.platformInit}();\n` : '') +
(installsPlatform ? ` installMiniGamePlatform(__platformProfile);\n` : '') +
` return ${profile.runtimeInit}({ engineFactory, engineWasmPath: ${JSON.stringify(engineWasmPath)}${runtimeLayout.sideModuleSuffix === '.wasm' ? '' : `, sideModuleSuffix: ${JSON.stringify(runtimeLayout.sideModuleSuffix)}`}, sideModuleFactories, sceneNames: ${JSON.stringify(scenes.map((s) => s.name))}, firstScene: ${JSON.stringify(sceneName)}${runtimeArgs}${projectDeclarations.length > 0 ? `, sideModules: ${JSON.stringify(projectDeclarations)}` : ''}${aotArg}${debugArg}${hotUpdateArg} });\n` +
`}\n`;
progress({ phase: 'Bundling game' });
/** What each subsystem costs in the bundle — empty if esbuild wrote no metafile. */
let bundleModules: ModuleBytes[] = [];
try {
const { build } = await loadEsbuild();
const res = await build({
stdin: { contents: entrySrc, resolveDir: opts.root, loader: 'js', sourcefile: 'minigame-entry.js' },
bundle: true,
format: 'cjs',
platform: 'browser',
// Real-device WeChat rejects es2020 syntax (`??`, `?.`) even though the
// devtools accepts it; es2017 down-levels those while keeping async/await.
target: profile.esTarget,
alias: esengineAlias(opts.sdkDir, lean ? leanEntry! : profile.sdkEntryFile),
plugins: [officialPackagesPlugin(opts.packagesDir)],
minify: minifiesScripts(opts),
sourcemap: false,
outfile: path.join(absOut, 'game-bundle.js'),
logLevel: 'silent',
write: true,
// Once the engine binary can leave the main package, this bundle is the
// largest file in it — and the vendor's brotli path does not take `.js`.
// esbuild already knows which subsystem each surviving byte came from.
metafile: true,
});
errors.push(...explainBundleErrors(res.errors));
if (res.metafile) bundleModules = breakdownOf(res.metafile, 'game-bundle.js', opts.sdkDir);
} catch (err) {
const e = err as { errors?: BundleMessage[]; message?: string };
errors.push(...(e.errors ? explainBundleErrors(e.errors) : [String(e.message ?? err)]));
}
// 4b. The open data context — a SECOND bundle, for a second JS runtime.
//
// It has no WebGL, no wasm and almost none of the host API; it draws on a
// 2D canvas the main domain samples as a texture, and it is the only place
// a player's friends can be read. So it cannot share the game bundle, and
// the `esengine` alias is deliberately WITHHELD here: a context that
// imports the engine fails to resolve at export instead of throwing on a
// device, which is the only place that mistake would otherwise surface.
//
// The project owns this file and a package may be what it imports
// (`estella-plugin-minigame-services/open-data` is a friends board in one
// line). No directory, no context — which is what asking for none means.
const openDataEntry = ['index.ts', 'index.js']
.map((f) => path.join(opts.root, OPEN_DATA_DIR, f))
.find((f) => existsSync(f));
if (openDataEntry) {
progress({ phase: 'Bundling open data context' });
try {
const { build } = await loadEsbuild();
const res = await build({
entryPoints: [openDataEntry],
bundle: true,
format: 'cjs',
platform: 'browser',
// Same syntax floor as the game bundle: the host compiles EVERY .js in
// the package, this one included.
target: profile.esTarget,
plugins: [officialPackagesPlugin(opts.packagesDir)],
minify: minifiesScripts(opts),
sourcemap: false,
outfile: path.join(absOut, OPEN_DATA_DIR, 'index.js'),
logLevel: 'silent',
write: true,
});
errors.push(...explainBundleErrors(res.errors));
} catch (err) {
const e = err as { errors?: BundleMessage[]; message?: string };
errors.push(...(e.errors ? explainBundleErrors(e.errors) : [String(e.message ?? err)]));
}
}
// 5. Entry + config (vendor-specific emission).
const cooked = subPackagesOf(cookEntries, profile.subpackageDir);
warnings.push(...cooked.strays);
// The engine's 分包, if the binary went into one, joins the cook's lazy groups
// here: the root entry each vendor demands and the host config's declaration
// are written once, for every subpackage, whatever put it there.
const subPackages = {
subPackages: runtimeLayout.subpackage
? [...cooked.subPackages, runtimeLayout.subpackage]
: cooked.subPackages,
};
// A vendor that wants an entry in every subpackage root refuses the package
// without one, naming the missing file rather than the rule. These roots hold
// assets the runtime reads by path, so the entry has nothing to do but exist.
if (profile.subpackageEntry) {
for (const sp of subPackages.subPackages) {
// A cook group's root exists because its assets landed there; the engine's
// is made by the staging below, which has not run yet.
await mkdir(path.join(absOut, sp.root), { recursive: true });
await writeFile(
path.join(absOut, sp.root, profile.subpackageEntry),
`// Entry for the "${sp.name}" subpackage, which ${profile.id} requires in every\n`
+ '// subpackage root. This one carries assets the runtime loads by path, so it\n'
+ '// has nothing to run.\n',
);
}
}
await writeFile(path.join(absOut, profile.entryFile ?? 'game.js'),
profile.emitEntry({ sideModules, engineGlueFile, runtimeDir: runtimeLayout.runtimeDir,
engineSubpackage: runtimeLayout.subpackage?.name ?? null, hostGlobal: profile.hostGlobal }));
const configFiles = profile.emitConfigFiles({
title,
appid: opts.appid ?? '',
version: opts.appVersion ?? '1.0.0',
versionCode: opts.versionCode ?? 1,
icon: await readAppIcon(opts.root, opts.appIcon, warnings),
orientation: opts.orientation ?? 'portrait',
subPackages: subPackages.subPackages,
includeSuffixes: packIncludeSuffixes(cookEntries, profile.nativeSuffixes),
// Only a bundle that was actually written counts: an entry that failed to
// build must not leave the config pointing at a directory with no index.js.
hasOpenData: !!openDataEntry && errors.length === 0,
openDataRoot: OPEN_DATA_DIR,
debugChannel: !!debugChannel,
});
for (const { file, content } of configFiles) {
await writeFile(path.join(absOut, file), content);
}
// 6. The engine runtime + exactly the side modules the scene needs. WeChat's
// main package has a 4MB budget — unneeded side modules must not ride along.
// Rematerialize wasm/ from scratch: it holds EXACTLY this export's runtime
// set and nothing else. A prior export into the same outDir may have staged
// a module this project no longer needs (e.g. basis.js when KTX2 was on),
// and this run — copying only the current set — would leave that stale .js
// behind. The mini-game packer compiles EVERY .js in the package, so a stale
// glue built by an older pipeline (raw es2020 `?.`/`??`, not down-leveled)
// fails real-device compile ("invalid file: wasm/basis.js … Unexpected token .").
// Scoped to wasm/ (exporter-owned); the outDir root also hosts devtools'
// project.private.config.json, so we don't wipe the whole tree.
/** Filled by the brotli branch below; the report has no other way to know. */
const packedFrom: Record<string, number> = {};
progress({ phase: 'Copying runtime' });
const wasmOut = path.join(absOut, 'wasm');
await rm(wasmOut, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
await mkdir(wasmOut, { recursive: true });
// Engine artifacts only — the project's own come from `.esengine/modules/`,
// not from the engine runtime dir, and are staged below.
const { transform } = await loadEsbuild();
for (const f of runtimeLayout.files) {
const src = runtimeFile(f.src);
if (!existsSync(src)) {
errors.push(`${profile.id} runtime file missing: ${f.src} (in ${opts.wasmDir}) — rebuild with \`node build-tools/cli.js build -t ${profile.wasmBuildHint}\``);
continue;
}
const dest = path.join(absOut, f.staged);
await mkdir(path.dirname(dest), { recursive: true });
if (f.src.endsWith('.js')) {
// Emscripten glue can carry es2020 syntax (`?.`, `??`) that real-device
// WeChat rejects — down-level it like the game bundle.
const out = await transform(await readFile(src, 'utf8'), { target: profile.esTarget, loader: 'js' });
await writeFile(dest, out.code);
} else if (f.brotli) {
// Quality 11: it runs once per build, and the bytes it saves are spent
// against a main-package limit for the life of the package.
const raw = await readFile(src);
const packed = await brotliPack(raw, {
params: {
[zlibConstants.BROTLI_PARAM_QUALITY]: zlibConstants.BROTLI_MAX_QUALITY,
[zlibConstants.BROTLI_PARAM_SIZE_HINT]: raw.byteLength,
},
});
await writeFile(dest, packed);
packedFrom[f.staged.split(path.sep).join('/')] = raw.byteLength;
progress({
phase: 'Copying runtime',
detail: `${f.staged} ${(raw.byteLength / 1048576).toFixed(2)}MB → ${(packed.byteLength / 1048576).toFixed(2)}MB`,
});
} else {
await cp(src, dest);
}
}
// The project's own modules land in the same wasm/ dir, with the same glue
// down-level applied — game.js require()s them by the same path.
warnings.push(...await stageProjectModules(projectModules, wasmOut, profile.id,
async (code) => (await transform(code, { target: profile.esTarget, loader: 'js' })).code));
// Last, over the finished directory: a signed package covers every byte in it.
let packageFile: string | undefined;
if (profile.pack && errors.length === 0) {
const packed = await profile.pack({ outDir: absOut, appid: opts.appid ?? '', releaseKey: opts.releaseKey });
packageFile = packed.file;
warnings.push(...packed.warnings);
}
return {
ok: errors.length === 0, platform: profile.id, outDir: absOut,
...(packageFile ? { packageFile } : {}),
included: cook.included.length, warnings, errors, inclusion: cook.inclusion,
bundleModules,
// The size report weighs the main package against a cap the subpackages are
// NOT on, and it cannot tell a subpackage root from any other directory. The
// export that made them names them.
subPackageRoots: subPackages.subPackages.map((sp) => sp.root),
...(Object.keys(packedFrom).length > 0 ? { packedFrom } : {}),
...(spineRuntimes ? { spineRuntimes } : {}),
};
}