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.

4.2 KB
Raw Blame
// 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 },
  }];
}