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 The desktop assembler: a runtime template plus an editor export, out the
* other side a thing you can double-click.
*
* The three-layer shape iOS and Android already use (REARCH_NATIVE_DISTRIBUTION
* §3) — the toolchain stays on the machine that built the template and this step
* is pure Node. Desktop had no such step at all: it wrote an npm project and
* asked the user to install electron-builder.
*
* ONE function for every desktop OS, because they differ in less than they share:
* a directory named for the app, the runtime renamed to it, one asset namespace,
* an icon. Only the shape of that directory and how it is signed are per-OS.
*/
import path from 'path';
import { existsSync, readdirSync, statSync } from 'fs';
import { chmod, cp, mkdir, readdir, readFile, rm, writeFile } from 'fs/promises';
import { pngToIcns } from './icns.js';
import { setExeIcon } from './peResource.js';
import { desktopTemplateSources, steamRedistIn } from './nativeTemplate.js';
import { fillTemplate } from './nativeApp.js';
/** Everything a bundle's Info.plist needs that is not the host's own business. */
const PLIST_DEFAULT_MIN = '11.0';
/**
* Where each OS puts the pieces, relative to the directory the assembler produces.
*
* `root` is that directory's own name — it is what the Steam depot maps and what
* a player drags, so it is the app's name on both.
*/
const LAYOUT = {
macos: {
root: (name) => `${name}.app`,
appName: (dir) => (dir.endsWith('.app') ? dir.slice(0, -'.app'.length) : null),
executable: (name) => path.join('Contents', 'MacOS', name),
content: path.join('Contents', 'Resources', 'Content'),
beside: path.join('Contents', 'Resources'),
},
windows: {
root: (name) => name,
appName: (dir) => dir,
executable: (name) => `${name}.exe`,
content: 'Content',
beside: '.',
},
// The same shape as Windows, without the extension: a directory a depot maps
// whole, with the runtime at its root.
linux: {
root: (name) => name,
appName: (dir) => dir,
executable: (name) => name,
content: 'Content',
beside: '.',
},
};
/**
* Assemble the app for @p platform from a runtime template and an export.
*
* The app's asset directory holds ONE namespace — the game's exported files plus
* the runtime's precompiled bytecode — because that is what the host reads
* through Platform::readAsset, exactly as the APK's assets/ is one namespace.
*
* @param {object} options
* @param {'macos'|'windows'|'linux'} options.platform
* @param {string} options.templateDir Installed runtime template.
* @param {string} options.contentDir The editor export to ship.
* @param {string} options.outDir Where the app directory is written.
* @param {{id: string, name: string, version: string, versionCode: number}} options.app
* @param {string} [options.iconPng] Project icon; the template's is used otherwise.
* @param {string} [options.macosMin] LSMinimumSystemVersion.
* @param {string} [options.steamSdkDir] A Steamworks SDK on this machine; its
* redistributable rides along so the game can reach Steam.
* @returns {Promise<{dir: string, steamLibrary: string | null}>} where the app is,
* and whether a store library went into it — a caller shipping to Steam has to
* be able to say so, because without it every achievement silently does nothing.
*/
export async function assembleDesktopApp(options) {
const { platform, templateDir, contentDir, outDir, app } = options;
const layout = LAYOUT[platform];
if (!layout) throw new Error(`no desktop layout for "${platform}" (macos, windows, linux)`);
const sources = desktopTemplateSources(templateDir, platform);
if (!existsSync(sources.executable)) {
throw new Error(`runtime template has no executable at ${sources.executable}`);
}
if (!existsSync(path.join(contentDir, 'game.config.json'))) {
throw new Error(`${contentDir} is not an editor export (no game.config.json)`);
}
// The directory is named by the app, and so is the executable inside it: on
// desktop the executable IS the identity, which is why the host reads its own
// name rather than parsing a config (see desktop.cpp appName).
const root = path.join(outDir, layout.root(app.name));
await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
const executable = path.join(root, layout.executable(app.name));
await mkdir(path.dirname(executable), { recursive: true });
await cp(sources.executable, executable);
await chmod(executable, 0o755);
// Entry by entry: the app directory usually lands INSIDE the export directory
// (the layout Android has), and copying a directory into itself is refused
// before any filter is consulted. Previous packages are skipped as not-content.
const content = path.join(root, layout.content);
await mkdir(content, { recursive: true });
const packaged = new Set(Object.values(LAYOUT).map((l) => l.root(app.name)));
for (const entry of await readdir(contentDir)) {
if (entry.endsWith('.app') || packaged.has(entry)) continue;
await cp(path.join(contentDir, entry), path.join(content, entry), { recursive: true });
}
if (existsSync(sources.bytecode)) {
await cp(sources.bytecode, path.join(content, path.basename(sources.bytecode)));
}
// What the runtime dlopens goes NEXT TO THE EXECUTABLE, the one directory the
// host looks in — Contents/MacOS on macOS (Platform::executableDir).
const besideExe = path.dirname(executable);
// The project's own SDK beats whatever the template was built with: a template
// published by CI can carry no Valve file at all.
const steamLib = steamRedistIn(options.steamSdkDir, platform)
?? (existsSync(sources.steamRedist) ? sources.steamRedist : null);
if (options.steamSdkDir && !steamLib) {
options.warn?.(`No redistributable under ${options.steamSdkDir} — a Steamworks SDK keeps it `
+ 'at redistributable_bin/<os>/. This build reaches no store.');
}
let steamLibrary = null;
for (const lib of [sources.d3dCompiler, steamLib, ...sources.v8Runtime]) {
if (!lib || !existsSync(lib)) continue;
const shipped = path.join(besideExe, path.basename(lib));
await cp(lib, shipped);
if (lib === steamLib) steamLibrary = shipped;
}
const iconPng = options.iconPng && existsSync(options.iconPng) ? options.iconPng : sources.icon;
if (existsSync(iconPng)) {
const png = await readFile(iconPng);
// Three OSes, three places: a container beside the resources (macOS),
// INSIDE the executable (Windows), and a plain file a .desktop entry
// points at (Linux — a PE rewriter over an ELF would corrupt it).
if (platform === 'macos') {
await writeFile(path.join(root, layout.beside, 'AppIcon.icns'), pngToIcns(png));
} else if (platform === 'windows') {
await writeFile(executable, setExeIcon(await readFile(executable), png));
} else {
await writeFile(path.join(root, 'icon.png'), png);
}
}
if (platform === 'macos') {
const template = await readFile(sources.infoPlistIn, 'utf8');
await writeFile(path.join(root, 'Contents', 'Info.plist'), fillTemplate(template, {
APP_NAME: app.name,
APP_ID: app.id,
VERSION_NAME: app.version,
VERSION_CODE: String(app.versionCode),
MACOS_MIN: options.macosMin || PLIST_DEFAULT_MIN,
}));
await signBundle(root, options, steamLibrary ? [steamLibrary] : []);
}
return { dir: root, steamLibrary };
}
/**
* Sign the assembled bundle ad-hoc, or say plainly that it is unsigned.
*
* The template's executable is signed AS A FILE; a bundle needs
* `_CodeSignature/CodeResources` too, and without it the app still launches — so
* nothing tells you until notarization. macOS only.
*
* Inside out: a library shipped in the bundle is code, and a bundle whose nested
* code is unsigned fails `--verify --deep --strict` even though the bundle itself
* signed cleanly.
*/
async function signBundle(bundle, options, nested = []) {
if (process.platform !== 'darwin') {
options.warn?.(`${path.basename(bundle)} is UNSIGNED — assembling on ${process.platform} `
+ 'cannot sign a macOS app. Run `codesign --force --sign - <app>` on a Mac before shipping it.');
return;
}
const { execFile } = await import('node:child_process');
const { promisify } = await import('node:util');
const identity = options.signIdentity || '-';
const sign = (target) => promisify(execFile)('codesign', ['--force', '--sign', identity, target]);
for (const item of nested) await sign(item);
await sign(bundle);
}
/**
* The executable inside an assembled app, from the same table that put it there.
*
* Not a search for "a file with no extension": every signed macOS bundle carries
* `Contents/_CodeSignature/CodeResources`, which fits that shape, and directory
* order decided which one a walk reached first.
*
* @param {string} dir A directory an export wrote an app into, at any depth.
* @param {'macos'|'windows'|'linux'} platform Whose layout to read.
* @returns {string|null} The executable, or null when no app is under @p dir.
*/
export function desktopExecutableIn(dir, platform) {
const layout = LAYOUT[platform];
if (layout === undefined) throw new Error(`no desktop layout for "${platform}"`);
// Breadth first over sorted names, so a nested app is still found and the
// answer does not depend on the order a filesystem hands entries back.
for (const queue = [dir]; queue.length > 0;) {
const at = queue.shift();
const name = layout.appName(path.basename(at));
if (name) {
const exe = path.join(at, layout.executable(name));
if (existsSync(exe) && statSync(exe).isFile()) return exe;
}
for (const entry of readdirSync(at, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
if (entry.isDirectory()) queue.push(path.join(at, entry.name));
}
}
return null;
}