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
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { program } from 'commander';
import { rm, mkdir } from 'fs/promises';
import { existsSync } from 'fs';
import path from 'path';
import config from './build.config.js';
import * as logger from './utils/logger.js';
import { checkEnvironment } from './utils/emscripten.js';
import { runEht } from './tasks/eht.js';
import { buildWasm, buildWasmParallel, cleanWasm } from './tasks/wasm.js';
import { buildNative } from './tasks/native.js';
import { buildSdk, cleanSdk } from './tasks/sdk.js';
import { syncToDesktop } from './tasks/sync.js';
import { startWatch } from './tasks/watch.js';
import { BuildManifest } from './manifest.js';
import { handleBuildError } from './utils/errorHelp.js';
import { checkExamples } from './tasks/check-examples.js';
import { validateDocuments } from './tasks/validate-documents.js';
program
.name('esengine-build')
.description('ESEngine build tools')
.version('1.0.0');
program
.command('build')
.description('Build ESEngine')
.option('-t, --target <target>', 'Build target (web, wechat, wechat-lite, spine, spine21, spine38, spine41, spine43, dragonbones, physics, physics-wechat, spine-wechat, dragonbones-wechat, basis, basis-wechat, sdk, all)', 'web')
.option('-d, --debug', 'Debug build', false)
.option('-c, --clean', 'Clean before build', false)
.option('--no-cache', 'Disable EHT cache')
.option('-v, --verbose', 'Verbose output', false)
.option('--no-sync', 'Skip syncing to desktop/public')
.option('--manifest', 'Generate build manifest with timing and sizes', false)
.option('--continue-on-error', 'Continue building other targets if one fails (for CI)', false)
.action(async (options) => {
logger.setVerbose(options.verbose);
const startTime = Date.now();
const manifest = options.manifest ? new BuildManifest() : null;
try {
logger.header('ESEngine Build');
if (!await checkEnvironment()) {
process.exit(1);
}
const isDebug = options.debug;
// Every module the config declares, rather than a second list of them.
const targets = options.target === 'all'
? Object.keys(config.wasm)
: [options.target];
if (options.clean) {
await cleanAll();
}
const wasmTargets = targets.filter(t => t !== 'sdk');
const buildSdkFlag = options.target === 'all' || options.target === 'sdk' || wasmTargets.length > 0;
const noCache = !options.cache;
// EHT output feeds sdk/src (component.generated.ts, wasm.generated.ts)
// as well as the wasm bindings, so an sdk-only build needs it too —
// otherwise the SDK bundles stale generated sources after a header edit.
await runEht({ noCache });
if (wasmTargets.length > 0) {
await buildWasmParallel(wasmTargets, {
debug: isDebug,
clean: options.clean,
manifest,
continueOnError: options.continueOnError,
noCache,
});
}
if (buildSdkFlag) {
await buildSdk({ manifest, noCache });
}
if (options.sync) {
await syncToDesktop();
}
if (manifest) {
manifest.printSummary();
const manifestPath = path.join(config.paths.output, 'manifest.json');
await manifest.save(manifestPath);
}
logger.printTime(startTime);
} catch (err) {
handleBuildError(err, { verbose: options.verbose });
}
});
program
.command('watch')
.description('Watch mode for development')
.option('-t, --target <target>', 'Build target for WASM', 'web')
.option('-v, --verbose', 'Verbose output', false)
.action(async (options) => {
logger.setVerbose(options.verbose);
try {
if (!await checkEnvironment()) {
process.exit(1);
}
await startWatch({ target: options.target });
} catch (err) {
handleBuildError(err, { verbose: options.verbose });
}
});
program
.command('clean')
.description('Clean build outputs')
.option('-a, --all', 'Clean all build directories', false)
.option('-t, --target <target>', 'Clean specific target')
.option('-v, --verbose', 'Verbose output', false)
.action(async (options) => {
logger.setVerbose(options.verbose);
try {
logger.header('Clean');
if (options.all || !options.target) {
await cleanAll();
} else {
await cleanWasm(options.target);
}
logger.success('Clean complete');
} catch (err) {
handleBuildError(err, { verbose: options.verbose });
}
});
program
.command('eht')
.description('Run EHT code generation only')
.option('--no-cache', 'Disable cache')
.option('-v, --verbose', 'Verbose output', false)
.action(async (options) => {
logger.setVerbose(options.verbose);
try {
await runEht({ noCache: !options.cache });
} catch (err) {
handleBuildError(err, { verbose: options.verbose });
}
});
program
.command('native')
.description('Build the native (embedded-Dawn) host for Android, iOS or the desktop')
.option('--target <target>', 'android, ios or macos', 'android')
.option('--fetch-deps', 'Check out Dawn, QuickJS-ng and SDL at the pinned commits and fetch the pinned V8, then stop', false)
.option('--build-deps', 'Build Dawn for every ABI/slice the target needs, then stop (for warming a cache)', false)
.option('--dawn <dir>', 'Dawn source dir (default: the pinned checkout; or ESTELLA_DAWN_DIR)')
.option('--dawn-build <dir>', 'Dawn build dir for this target (default: <dawn>/out-<target>, built if absent)')
.option('--quickjs <dir>', 'QuickJS-ng source dir (default: the pinned checkout; or ESTELLA_QUICKJS_DIR)')
.option('--js-engine <engine>', 'JS engine the host embeds: v8 (default where pinned: Windows, Android) or quickjs (iOS always; or ESTELLA_JS_ENGINE)')
.option('--v8 <dir>', 'A prebuilt V8 (include/ + libraries) instead of the pinned one (or ESTELLA_V8_DIR)')
.option('--spine <versions>', 'Spine releases the host carries, comma-separated (default: every vendored one: 2.1, 3.8, 4.1, 4.2, 4.3)')
.option('--sdl <dir>', 'Desktop: SDL3 source dir or install prefix (default: the pinned checkout; or ESTELLA_SDL_DIR)')
.option('--steam-sdk <dir>', 'Desktop: a Steamworks SDK on this machine; its redistributable ships in the package (and in a template built with --template-out)')
.option('--macos-archs <archs>', 'Desktop: CMAKE_OSX_ARCHITECTURES (arm64, or "arm64;x86_64" for a universal build)')
.option('--macos-min <version>', 'Desktop: macOS deployment target')
.option('--abi <abi>', 'Android ABI', 'arm64-v8a')
.option('--platform <platform>', 'Android platform', 'android-29')
.option('--ios-min <version>', 'iOS deployment target', '17.0')
.option('--simulator', 'iOS: build the simulator slice (needs a simulator Dawn)', false)
.option('--package', 'Assemble the app around --content from the installed runtime template: Android a signed APK, iOS an Xcode project', false)
.option('--aab', 'Android --package: also write the Google Play upload format (.aab)', false)
.option('--key <pem>', 'Android --package: PEM private key to sign with (default: the development key)')
.option('--cert <pem>', 'Android --package: PEM certificate for --key')
.option('--passphrase <text>', 'Passphrase for an encrypted --key')
.option('--jdk <dir>', 'JDK home for building a template (javac + d8), else JAVA_HOME or Android Studio\'s')
.option('--content <dir>', 'Ship an exported project (Package Project -> Android / iOS) as the app content')
.option('--out <dir>', 'Desktop --package: where the .app is written (default: beside --content)')
.option('--sign-identity <id>', 'Desktop --package: codesign identity (default: ad-hoc)')
.option('--icon <png>', 'Square PNG app icon; the template\'s mark is used otherwise')
.option('--no-template', 'Skip refreshing this machine\'s runtime template with the build')
.option('--template-only', 'Emit the runtime template from an existing build, without rebuilding', false)
.option('--template-out <dir>', 'Also write the distributable template archive here (for a release)')
.option('--template-index <dir>', 'Write native-templates.json describing the archives in this dir, then stop')
.option('--deps-cache-key <target>', 'Print `key=<cache key>` for a target\'s prebuilt dependencies, then stop (CI)')
.option('-v, --verbose', 'Verbose output', false)
.action(async (options) => {
logger.setVerbose(options.verbose);
try {
await buildNative({
target: options.target,
fetchDeps: options.fetchDeps,
buildDeps: options.buildDeps,
template: options.template,
templateOnly: options.templateOnly,
templateOut: options.templateOut,
templateIndex: options.templateIndex,
depsCacheKey: options.depsCacheKey,
dawn: options.dawn,
dawnBuild: options.dawnBuild,
quickjs: options.quickjs,
jsEngine: options.jsEngine,
v8: options.v8,
spine: options.spine,
sdl: options.sdl,
steamSdk: options.steamSdk,
macosArchs: options.macosArchs,
macosMin: options.macosMin,
abi: options.abi,
platform: options.platform,
iosMin: options.iosMin,
simulator: options.simulator,
package: options.package,
aab: options.aab,
key: options.key,
cert: options.cert,
passphrase: options.passphrase,
jdk: options.jdk,
content: options.content,
out: options.out,
signIdentity: options.signIdentity,
icon: options.icon,
});
} catch (err) {
logger.error(err.message);
process.exit(1);
}
});
program
.command('sdk')
.description('Build SDK only')
.option('--no-cache', 'Disable build cache')
.option('-v, --verbose', 'Verbose output', false)
.action(async (options) => {
logger.setVerbose(options.verbose);
try {
const noCache = !options.cache;
// Regenerate EHT outputs in sdk/src first, or the SDK bundles stale
// generated sources after a C++ header edit.
await runEht({ noCache });
await buildSdk({ noCache });
await syncToDesktop({ wasm: false, sdk: true });
} catch (err) {
handleBuildError(err, { verbose: options.verbose });
}
});
program
.command('sync')
.description('Sync build outputs to desktop/public')
.option('-v, --verbose', 'Verbose output', false)
.action(async (options) => {
logger.setVerbose(options.verbose);
try {
await syncToDesktop();
} catch (err) {
handleBuildError(err, { verbose: options.verbose });
}
});
async function cleanAll() {
logger.step('Cleaning all build outputs...');
const outputDir = config.paths.output;
if (existsSync(outputDir)) {
await rm(outputDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
logger.debug('Removed build/');
}
await cleanWasm();
await cleanSdk();
}
program
.command('check-examples')
.description('Type-check all example projects against current SDK types')
.action(async () => {
logger.header('Check Examples');
const startTime = Date.now();
await checkExamples(config.paths.root);
logger.printTime(startTime);
});
program
.command('validate-documents')
.description('Run the shared document validators over every shipped scene and prefab')
.action(async () => {
logger.header('Validate Documents');
const startTime = Date.now();
await validateDocuments(config.paths.root);
logger.printTime(startTime);
});
// Forwarded rather than reimplemented: the pipeline owns packaging, and its own
// entry is what CI and a build server call. This is here so someone who already
// knows `cli.js` does not have to learn a second command to ship a project.
program
.command('export <projectDir>')
.description('Package a project (no editor) — see pipeline/bin/estella.mjs for the options')
.allowUnknownOption()
.helpOption(false)
.action(async (projectDir, _opts, command) => {
const { spawnSync } = await import('child_process');
const bin = path.join(config.paths.root, 'pipeline', 'bin', 'estella.mjs');
const result = spawnSync(process.execPath, [bin, 'export', projectDir, ...command.args.slice(1)], {
stdio: 'inherit',
});
process.exit(result.status ?? 1);
});
program
.command('verify-template <archives...>')
.description('Check published runtime-template archives carry everything a release must')
.action(async (archives) => {
logger.header('Verify Runtime Templates');
const { verifyTemplates } = await import('./tasks/verifyTemplate.js');
try {
verifyTemplates(archives);
} catch (err) {
// The reason is already printed per archive; a stack trace on top of it
// only buries what a release engineer has to read.
logger.error(err.message);
process.exit(1);
}
});
program
.command('toolchain')
.description('Package local emsdk + cmake into Tauri resources for bundling')
.option('--no-strip', 'Skip stripping unnecessary files')
.option('--no-archive', 'Skip creating tar.gz archive')
.action(async (options) => {
const args = [import.meta.dirname + '/toolchain/package.js'];
if (!options.strip) args.push('--no-strip');
if (!options.archive) args.push('--no-archive');
const { execSync } = await import('child_process');
execSync(`node ${args.join(' ')}`, { stdio: 'inherit', cwd: config.paths.root });
});
program.parse();