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
feat(build): assemble a runnable macOS app, with no toolchain
esengine38503cbb1109
diff --git a/build-tools/cli.js b/build-tools/cli.jsindex 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 @@ programpassphrase: 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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.tsnew file mode 100644index 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));+ }+ });+});