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.

10.2 KB
Raw Blame
// 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;
}