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.

feat(build): assemble a runnable macOS app, with no toolchain

esengine38503cbb1109
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 364eee161..455b79d86 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -180,6 +180,9 @@ program
.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)')
@@ -213,6 +216,9 @@ program
passphrase: options.passphrase,
jdk: options.jdk,
content: options.content,
+ out: options.out,
+ signIdentity: options.signIdentity,
+ icon: options.icon,
});
} catch (err) {
logger.error(err.message);
diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.js
index c24af4616..3ffca6100 100644
--- a/build-tools/tasks/native.js
+++ b/build-tools/tasks/native.js
@@ -25,6 +25,7 @@ import {
} from '../utils/nativeTemplate.js';
import { readAppConfig, fillTemplate, iosInterfaceOrientations } from '../utils/nativeApp.js';
import { emitIosXcodeProject } from '../utils/iosProject.js';
+import { assembleMacApp } from '../utils/desktopApp.js';
import { assembleApk, apkFileName } from '../utils/apk.js';
import { assembleAab, aabFileName } from '../utils/aab.js';
import { debugSigningKey, signingKeyFromPem } from '../utils/androidKeystore.js';
@@ -366,6 +367,12 @@ async function buildDesktopHost(options) {
const exe = path.join(buildDir, 'estella_desktop');
logger.success(`Desktop host: ${path.relative(rootDir, exe)}`);
+
+ // Same rule as the other two: the compiled half is project-independent, so it
+ // is packed as the template every package is assembled from.
+ if (options.template !== false) {
+ await emitNativeTemplate({ platform: target, root: rootDir, zipTo: options.templateOut });
+ }
logger.info(`Run an export with: ${path.relative(rootDir, exe)} <exported-project-dir>`);
return exe;
}
@@ -648,6 +655,35 @@ function requireTemplate(platform) {
return template;
}
+/**
+ * Assemble a runnable `.app` around an export, from the installed runtime
+ * template. Pure Node: nothing here compiles, and the toolchain that produced the
+ * template stayed on the machine that built it.
+ */
+async function packageDesktopApp(options) {
+ const template = requireTemplate('macos');
+ const contentDir = packagedContent(options);
+ const app = readAppConfig(contentDir, (m) => logger.warn(m));
+ const outDir = options.out
+ ? (path.isAbsolute(options.out) ? options.out : path.join(config.paths.root, options.out))
+ : path.dirname(contentDir);
+
+ logger.step(`Assembling ${app.name}.app...`);
+ const bundle = await assembleMacApp({
+ templateDir: template.dir,
+ contentDir,
+ outDir,
+ app,
+ iconPng: options.icon,
+ macosMin: options.macosMin || MACOS_MIN,
+ signIdentity: options.signIdentity,
+ warn: (m) => logger.warn(m),
+ });
+ logger.success(`macOS app: ${path.relative(config.paths.root, bundle) || bundle}`);
+ logger.info(`Run it with: open "${bundle}"`);
+ return bundle;
+}
+
/**
* Assemble a signed APK around an export — from the installed runtime template,
* with no Android SDK involved. The same call the editor's export makes.
@@ -774,12 +810,9 @@ export async function buildNative(options = {}) {
throw new Error(`Unknown --target ${target} (expected android, ios or macos).`);
}
if (isDesktopTarget(target)) {
- // No template emit and no --package yet: those are S3, and a template that
- // claimed to exist before the assembler that reads it would be a version
- // the editor offers and cannot use.
- if (options.templateOnly || options.package) {
- throw new Error(`--${options.package ? 'package' : 'template-only'} is not implemented for `
- + `${target} yet (S3 in docs/REARCH_STEAM.md).`);
+ if (options.package) return packageDesktopApp(options);
+ if (options.templateOnly) {
+ return emitNativeTemplate({ platform: target, root: config.paths.root, zipTo: options.templateOut });
}
return buildDesktopHost(options);
}
diff --git a/build-tools/utils/desktopApp.js b/build-tools/utils/desktopApp.js
new file mode 100644
index 000000000..70a5dd3bc
--- /dev/null
+++ b/build-tools/utils/desktopApp.js
@@ -0,0 +1,104 @@
+// 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.
+ */
+
+import path from 'path';
+import { existsSync } from 'fs';
+import { chmod, cp, mkdir, readFile, rm, writeFile } from 'fs/promises';
+import { pngToIcns } from './icns.js';
+import { desktopTemplateSources } 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';
+
+/**
+ * Assemble `<out>/<name>.app` from @p template and @p contentDir.
+ *
+ * The bundle's Resources hold ONE asset 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 {string} options.templateDir Installed runtime template.
+ * @param {string} options.contentDir The editor export to ship.
+ * @param {string} options.outDir Where the .app 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.
+ * @returns {Promise<string>} the bundle's path.
+ */
+export async function assembleMacApp(options) {
+ const { templateDir, contentDir, outDir, app } = options;
+ const sources = desktopTemplateSources(templateDir);
+ 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 bundle 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 bundle = path.join(outDir, `${app.name}.app`);
+ await rm(bundle, { recursive: true, force: true });
+ const macos = path.join(bundle, 'Contents', 'MacOS');
+ const resources = path.join(bundle, 'Contents', 'Resources');
+ await mkdir(macos, { recursive: true });
+ await mkdir(resources, { recursive: true });
+
+ const executable = path.join(macos, app.name);
+ await cp(sources.executable, executable);
+ await chmod(executable, 0o755);
+
+ await cp(contentDir, path.join(resources, 'Content'), { recursive: true });
+ if (existsSync(sources.bytecode)) {
+ await cp(sources.bytecode, path.join(resources, 'Content', path.basename(sources.bytecode)));
+ }
+
+ const iconPng = options.iconPng && existsSync(options.iconPng) ? options.iconPng : sources.icon;
+ if (existsSync(iconPng)) {
+ await writeFile(path.join(resources, 'AppIcon.icns'), pngToIcns(await readFile(iconPng)));
+ }
+
+ const template = await readFile(sources.infoPlistIn, 'utf8');
+ await writeFile(path.join(bundle, '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(bundle, options);
+ return bundle;
+}
+
+/**
+ * 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.
+ */
+async function signBundle(bundle, options) {
+ 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 || '-';
+ await promisify(execFile)('codesign', ['--force', '--sign', identity, bundle]);
+}
diff --git a/build-tools/utils/icns.js b/build-tools/utils/icns.js
new file mode 100644
index 000000000..f2f1ef5ab
--- /dev/null
+++ b/build-tools/utils/icns.js
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+/**
+ * @file The macOS icon container, written rather than depended on.
+ *
+ * `iconutil` is macOS-only and the assembler must run anywhere. The format is a
+ * header plus typed blocks, and since 10.7 a block may simply BE a PNG — so the
+ * project's icon goes in as its own bytes, with nothing to encode.
+ */
+
+/**
+ * The block type for each nominal icon size. A type is a SLOT, not a promise
+ * about the pixels — macOS scales whatever it finds — so one block is a valid
+ * icon file and the largest slot is the one worth filling.
+ */
+const SIZE_TYPES = [
+ [16, 'icp4'], [32, 'icp5'], [64, 'icp6'], [128, 'ic07'],
+ [256, 'ic08'], [512, 'ic09'], [1024, 'ic10'],
+];
+
+/** A PNG's pixel size, straight out of IHDR (which is always the first chunk). */
+export function pngSize(bytes) {
+ const png = Buffer.from(bytes);
+ const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+ if (png.length < 24 || !png.subarray(0, 8).equals(signature)) {
+ throw new Error('not a PNG (bad signature)');
+ }
+ if (png.subarray(12, 16).toString('ascii') !== 'IHDR') {
+ throw new Error('not a PNG (first chunk is not IHDR)');
+ }
+ return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
+}
+
+/**
+ * Wrap a square PNG as an `.icns`.
+ *
+ * NOTHING is resized, as with the Android and iOS icons — the platform scales.
+ * The slot is the largest standard size the image covers, so a 300px icon lands
+ * in the 256 slot rather than claiming 512.
+ *
+ * @param {Uint8Array|Buffer} png The icon.
+ * @returns {Buffer} the .icns file.
+ */
+export function pngToIcns(png) {
+ const { width, height } = pngSize(png);
+ if (width !== height) throw new Error(`icon must be square, got ${width}x${height}`);
+ const slot = [...SIZE_TYPES].reverse().find(([size]) => size <= width);
+ if (!slot) throw new Error(`icon is ${width}px; the smallest macOS slot is ${SIZE_TYPES[0][0]}px`);
+
+ const data = Buffer.from(png);
+ const block = Buffer.alloc(8);
+ block.write(slot[1], 0, 'ascii');
+ block.writeUInt32BE(data.length + 8, 4);
+
+ const header = Buffer.alloc(8);
+ header.write('icns', 0, 'ascii');
+ header.writeUInt32BE(8 + block.length + data.length, 4);
+ return Buffer.concat([header, block, data]);
+}
diff --git a/desktop/tests/desktop-app.test.ts b/desktop/tests/desktop-app.test.ts
new file mode 100644
index 000000000..8a0932b13
--- /dev/null
+++ b/desktop/tests/desktop-app.test.ts
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+/**
+ * @file The desktop assembler and the icon container it writes.
+ *
+ * Pinned here: a package is ASSEMBLED from a runtime template with no toolchain,
+ * as the APK and the Xcode project are. The bundle's Resources are ONE asset
+ * namespace — the game's files plus the runtime's bytecode — because that is what
+ * Platform::readAsset reads, and bytecode the host cannot find costs every first
+ * launch seconds of black screen with nothing to say why.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { assembleMacApp } from '../../build-tools/utils/desktopApp.js';
+import { pngToIcns, pngSize } from '../../build-tools/utils/icns.js';
+import { templateLayout, desktopTemplateSources } from '../../build-tools/utils/nativeTemplate.js';
+
+/** A minimal but REAL png — the icns writer reads IHDR, so a stub will not do. */
+function png(size: number): Buffer {
+ const ihdr = Buffer.alloc(13);
+ ihdr.writeUInt32BE(size, 0);
+ ihdr.writeUInt32BE(size, 4);
+ ihdr[8] = 8;
+ ihdr[9] = 6;
+ const chunk = (type: string, data: Buffer) => {
+ const head = Buffer.alloc(8);
+ head.writeUInt32BE(data.length, 0);
+ head.write(type, 4, 'ascii');
+ return Buffer.concat([head, data, Buffer.alloc(4)]);
+ };
+ return Buffer.concat([
+ Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+ chunk('IHDR', ihdr),
+ ]);
+}
+
+let dir: string;
+let templateDir: string;
+let contentDir: string;
+let outDir: string;
+
+const APP = { id: 'com.acme.game', name: 'Acme Game', version: '2.1', versionCode: 7 };
+
+beforeEach(() => {
+ dir = mkdtempSync(path.join(tmpdir(), 'estella-desktop-'));
+ templateDir = path.join(dir, 'template');
+ contentDir = path.join(dir, 'content');
+ outDir = path.join(dir, 'out');
+ mkdirSync(templateDir, { recursive: true });
+ mkdirSync(contentDir, { recursive: true });
+
+ const sources = desktopTemplateSources(templateDir);
+ writeFileSync(sources.executable, 'MZ-not-really-a-binary');
+ writeFileSync(sources.bytecode, 'BYTECODE');
+ writeFileSync(sources.icon, png(1024));
+ writeFileSync(sources.infoPlistIn,
+ '<plist><dict><key>N</key><string>@APP_NAME@</string>'
+ + '<key>I</key><string>@APP_ID@</string>'
+ + '<key>V</key><string>@VERSION_NAME@</string>'
+ + '<key>M</key><string>@MACOS_MIN@</string></dict></plist>');
+
+ writeFileSync(path.join(contentDir, 'game.config.json'), '{"entryScene":"a.esscene"}');
+ mkdirSync(path.join(contentDir, 'assets'), { recursive: true });
+ writeFileSync(path.join(contentDir, 'assets', 'a.esscene'), '{}');
+});
+
+afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+describe('macOS app assembly', () => {
+ it('produces a bundle named and executed by the app, not by the runtime', async () => {
+ const bundle = await assembleMacApp({ templateDir, contentDir, outDir, app: APP });
+ expect(bundle).toBe(path.join(outDir, 'Acme Game.app'));
+ // The executable carries the app's name because on desktop the executable
+ // IS the identity — the host reads its own argv[0] rather than a config.
+ expect(existsSync(path.join(bundle, 'Contents/MacOS/Acme Game'))).toBe(true);
+ expect(existsSync(path.join(bundle, 'Contents/MacOS/estella_desktop'))).toBe(false);
+ });
+
+ it('puts the runtime bytecode in the SAME asset namespace as the game', async () => {
+ const bundle = await assembleMacApp({ templateDir, contentDir, outDir, app: APP });
+ const content = path.join(bundle, 'Contents/Resources/Content');
+ expect(readFileSync(path.join(content, 'game.config.json'), 'utf8')).toContain('entryScene');
+ // Beside the game's files, since that is the one path readAsset resolves.
+ expect(readFileSync(path.join(content, 'esengine.native.qjsbc'), 'utf8')).toBe('BYTECODE');
+ expect(existsSync(path.join(content, 'assets/a.esscene'))).toBe(true);
+ });
+
+ it('fills the identity into Info.plist', async () => {
+ const bundle = await assembleMacApp({
+ templateDir, contentDir, outDir, app: APP, macosMin: '12.3',
+ });
+ const plist = readFileSync(path.join(bundle, 'Contents/Info.plist'), 'utf8');
+ expect(plist).toContain('<string>Acme Game</string>');
+ expect(plist).toContain('<string>com.acme.game</string>');
+ expect(plist).toContain('<string>2.1</string>');
+ expect(plist).toContain('<string>12.3</string>');
+ expect(plist).not.toContain('@');
+ });
+
+ it('refuses a content dir that is not an export', async () => {
+ rmSync(path.join(contentDir, 'game.config.json'));
+ await expect(assembleMacApp({ templateDir, contentDir, outDir, app: APP }))
+ .rejects.toThrow(/not an editor export/);
+ });
+
+ it('refuses a template with no runtime in it', async () => {
+ rmSync(desktopTemplateSources(templateDir).executable);
+ await expect(assembleMacApp({ templateDir, contentDir, outDir, app: APP }))
+ .rejects.toThrow(/no executable/);
+ });
+
+ it('reassembling replaces the bundle rather than merging into it', async () => {
+ const bundle = await assembleMacApp({ templateDir, contentDir, outDir, app: APP });
+ writeFileSync(path.join(bundle, 'Contents/Resources/Content/stale.txt'), 'x');
+ await assembleMacApp({ templateDir, contentDir, outDir, app: APP });
+ expect(existsSync(path.join(bundle, 'Contents/Resources/Content/stale.txt'))).toBe(false);
+ });
+});
+
+describe('the icon container', () => {
+ it('writes a slot matching the icon and a length covering the file', () => {
+ const icns = pngToIcns(png(1024));
+ expect(icns.subarray(0, 4).toString('ascii')).toBe('icns');
+ expect(icns.readUInt32BE(4)).toBe(icns.length);
+ expect(icns.subarray(8, 12).toString('ascii')).toBe('ic10'); // the 1024 slot
+ expect(icns.readUInt32BE(12)).toBe(icns.length - 8);
+ });
+
+ it('takes the largest slot the icon covers rather than claiming one it does not', () => {
+ expect(pngToIcns(png(512)).subarray(8, 12).toString('ascii')).toBe('ic09');
+ expect(pngToIcns(png(256)).subarray(8, 12).toString('ascii')).toBe('ic08');
+ // Between two slots: the smaller one, so the file never says 512 about a
+ // 300px picture.
+ expect(pngToIcns(png(300)).subarray(8, 12).toString('ascii')).toBe('ic08');
+ });
+
+ it('refuses what it cannot honestly wrap', () => {
+ expect(() => pngToIcns(png(8))).toThrow(/smallest macOS slot/);
+ expect(() => pngToIcns(Buffer.from('not a png'))).toThrow(/not a PNG/);
+ const oblong = png(64);
+ oblong.writeUInt32BE(32, 20);
+ expect(() => pngToIcns(oblong)).toThrow(/square/);
+ });
+
+ it('reads a PNG size from IHDR', () => {
+ expect(pngSize(png(128))).toEqual({ width: 128, height: 128 });
+ });
+});
+
+describe('the layout table is the only thing that names files', () => {
+ it('describes the macOS template the assembler reads', () => {
+ const rels = templateLayout('macos').map((e: { rel: string }) => e.rel);
+ const sources = desktopTemplateSources('T');
+ for (const file of Object.values(sources)) {
+ expect(rels).toContain(path.relative('T', file as string));
+ }
+ });
+});