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 electronRun.mjs — the conditions Electron needs, owned by one place.
*
* A Linux runner has no display, and the chrome-sandbox helper shipped in
* node_modules is not setuid root. Electron needs xvfb and the sandbox off, or
* it aborts before a window exists.
*
* That knowledge lived at the CALLERS. build.yml prefixed eight steps with
* `xvfb-run -a` and set ELECTRON_DISABLE_SANDBOX beside each; nightly.yml ran
* the same verifiers as release criteria and did neither. So nine exit criteria
* reported a missing display as a verdict about the engine — golden said "the
* editor never produced a play frame", the flagship said it "cannot be played to
* the end of its route". Both were true of the runner and of nothing else.
*
* A precondition that every caller must remember is a precondition one of them
* will forget, so it belongs to the tool that needs it.
*/
import { createRequire } from 'node:module';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { runTool, spawnTool } from './runTool.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
let binaryResolved = false;
/**
* Resolve Electron's binary once, before anything launches it. A binary the install
* left out is downloaded on first launch: two first launches at once raced into
* spawn ETXTBSY, and a download the host refused once (HTTP 500) failed every
* verifier after it with no reading at all.
*/
export function ensureElectronBinary({ attempts = 4, backoffMs = 10_000 } = {}) {
for (let attempt = 1; !binaryResolved; attempt++) {
try {
createRequire(path.join(ROOT, 'package.json'))('electron');
binaryResolved = true;
} catch (err) {
if (attempt >= attempts) throw err;
const wait = backoffMs * attempt;
console.error(`electron binary: attempt ${attempt} failed — retrying in ${wait / 1000}s`);
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, wait);
}
}
}
/** xvfb-run's own default is 1280x1024x8, which is smaller than the windows
* golden asks for and shallower than a pixel judgement should be read from. */
const SCREEN = '-screen 0 1920x1080x24';
// A job that already stands up one display for every step (because the private
// editor's scripts cannot import this file) has given us one too.
export const NEEDS_XVFB = process.platform === 'linux'
&& !process.env.DISPLAY && !process.env.ESTELLA_NO_XVFB;
/** Keep one display alive for a Node controller and all of its Electron children. */
export function runWithElectronDisplay(args, options = {}) {
return NEEDS_XVFB
? runTool('xvfb-run', ['-a', '--server-args', SCREEN, process.execPath, ...args], options)
: runTool(process.execPath, args, options);
}
/**
* Run Electron with a script and its arguments, under whatever this host needs.
*
* `via` names the workspace runner that resolves the binary — 'npx' where a
* nested package has its own. `env` merges over what this adds, never replacing.
*/
export function runElectron(args, { via = 'pnpm', env, ...options } = {}) {
const [cmd, argv, opts] = electronCommand(args, { via, env, ...options });
return runTool(cmd, argv, opts);
}
/** {@link runElectron} without waiting: for a caller that must keep answering
* the process while it runs. */
export function spawnElectron(args, { via = 'pnpm', env, ...options } = {}) {
const [cmd, argv, opts] = electronCommand(args, { via, env, ...options });
return spawnTool(cmd, argv, opts);
}
function electronCommand(args, { via, env, ...options }) {
ensureElectronBinary();
const electron = via === 'npx' ? ['npx', 'electron'] : ['pnpm', 'exec', 'electron'];
const [cmd, ...rest] = NEEDS_XVFB
? ['xvfb-run', '-a', '--server-args', SCREEN, ...electron]
: electron;
// Windows Electron treats colon-bearing app arguments as protocol launches
// unless its own argument parser stops at an explicit separator.
const appArgs = process.platform === 'win32' && args[0] && !args[0].startsWith('-')
? [args[0], '--', ...args.slice(1)] : args;
return [cmd, [...rest, ...appArgs], {
...options,
env: { ...process.env, ELECTRON_DISABLE_SANDBOX: '1', ...env },
}];
}