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.

fix(ci): what Electron needs belongs to the tool, not to whoever remembers

esenginedd485c082121
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 90812661f..6bd219ea9 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -480,9 +480,7 @@ jobs:
# step with no ceiling spent the job's whole 30 minutes and was killed with
# nothing written. A budget reports what it measured and names what it did not.
- name: Run the editor's pixel gates
- env:
- ELECTRON_DISABLE_SANDBOX: '1'
- run: xvfb-run -a --server-args="-screen 0 1920x1080x24" node tools/verify-render.mjs --tier pr --host editor --no-build --budget 10
+ run: node tools/verify-render.mjs --tier pr --host editor --no-build --budget 10
# A run that dies of ENOSPC uploads NO log — this job's last failure lost every
# line of it, including the snapshot that would have said what filled the disk.
@@ -588,42 +586,32 @@ jobs:
# the engine was checked; the package never was — and "it launched" is not the
# claim, since a build that boots to its rotate-to-portrait gate launches fine.
- name: Launch the golden packages and compare them to the editor (PR tier)
- env:
- ELECTRON_DISABLE_SANDBOX: '1'
- run: xvfb-run -a node tools/verify-golden.mjs --tier pr
+ run: node tools/verify-golden.mjs --tier pr
# The same game packaged twice from one tree, compiled and interpreted, and
# the two frames held against each other — the only check that sees what a
# compiled system does to a PIXEL.
- name: Compare a compiled game's frame to an interpreted one (PR tier)
- env:
- ELECTRON_DISABLE_SANDBOX: '1'
- run: xvfb-run -a node tools/verify-aot-parity.mjs
+ run: node tools/verify-aot-parity.mjs
# Does a real exported WEB package DISPATCH to its compiled systems — the
# claim verify-aot-native makes for the desktop road, which the web road had
# nobody making. A twin that loads and is never called changes no pixel and
# raises no error, so parity below cannot see it either.
- name: Check an exported web game runs its systems compiled
- env:
- ELECTRON_DISABLE_SANDBOX: '1'
- run: xvfb-run -a pnpm run verify:aot
+ run: pnpm run verify:aot
# And the exact half: one fixture packaged both ways, stepped by a fixed dt
# rather than by elapsed time, and the two displacements compared. This is
# the check a twin reading the wrong offset cannot survive.
- name: Check a cooked build's compiled systems against the interpreter
- env:
- ELECTRON_DISABLE_SANDBOX: '1'
- run: xvfb-run -a pnpm run verify:cooked
+ run: pnpm run verify:cooked
# Projects as they were RELEASED, opened by the editor of today. The golden
# corpus is re-saved by whoever last touched it, so it can only say that this
# version opens its own files; a person's project is not re-saved by anybody.
- name: Open released projects (PR tier)
- env:
- ELECTRON_DISABLE_SANDBOX: '1'
- run: xvfb-run -a node tools/verify-legacy.mjs --tier pr
+ run: node tools/verify-legacy.mjs --tier pr
# The same scenes on the second backend, on a runner of its own.
#
diff --git a/package.json b/package.json
index 597d32b7e..073bdd86d 100644
--- a/package.json
+++ b/package.json
@@ -31,9 +31,9 @@
"render-host": "node tools/render-host/build.mjs",
"verify:render": "node tools/verify-render.mjs",
"test": "vitest run --config vitest.engine.config.ts",
- "verify:aot": "rm -rf .aot-verify && node pipeline/bin/estella.mjs export examples/ecs-basics --out .aot-verify && pnpm exec electron tools/launchers/headless-aot-verify.mjs .aot-verify",
- "verify:cooked": "ESTELLA_COOK_FIXTURE=1 pnpm --filter @estella/pipeline exec vitest run tests/cooked-verify-fixture.test.ts && pnpm exec electron tools/launchers/headless-cooked-verify.mjs",
- "verify:hotupdate": "ESTELLA_HOTUPDATE_FIXTURE=1 pnpm --filter @estella/pipeline exec vitest run tests/hotupdate-verify-fixture.test.ts && pnpm exec electron tools/launchers/headless-hotupdate-verify.mjs"
+ "verify:aot": "rm -rf .aot-verify && node pipeline/bin/estella.mjs export examples/ecs-basics --out .aot-verify && node tools/run-electron.mjs tools/launchers/headless-aot-verify.mjs .aot-verify",
+ "verify:cooked": "ESTELLA_COOK_FIXTURE=1 pnpm --filter @estella/pipeline exec vitest run tests/cooked-verify-fixture.test.ts && node tools/run-electron.mjs tools/launchers/headless-cooked-verify.mjs",
+ "verify:hotupdate": "ESTELLA_HOTUPDATE_FIXTURE=1 pnpm --filter @estella/pipeline exec vitest run tests/hotupdate-verify-fixture.test.ts && node tools/run-electron.mjs tools/launchers/headless-hotupdate-verify.mjs"
},
"dependencies": {
"chalk": "^5.3.0",
diff --git a/tools/check-electron-preconditions.mjs b/tools/check-electron-preconditions.mjs
new file mode 100644
index 000000000..b19bbb37b
--- /dev/null
+++ b/tools/check-electron-preconditions.mjs
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-electron-preconditions.mjs — one owner for what Electron needs.
+ *
+ * A Linux runner needs xvfb and the sandbox off before Electron can open a
+ * window. That was written at the call sites: eight steps in build.yml carried
+ * the prefix and the env var, and nightly.yml — running the same verifiers as
+ * release criteria — carried neither. Nine exit criteria then reported the
+ * missing display as a verdict about the engine.
+ *
+ * Two lists again, and the second one had the hole. So this refuses both shapes
+ * of it: a verifier that launches Electron without electronRun, and a workflow
+ * that supplies by hand what electronRun now supplies for every caller.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const TOOLS = path.join(ROOT, 'tools');
+const WORKFLOWS = path.join(ROOT, '.github', 'workflows');
+
+/**
+ * Not every Electron on a runner is ours to condition. The desktop scripts live
+ * in the private editor submodule, which cannot import from tools/; the native
+ * desktop render host is not Electron at all and wants xvfb for Vulkan.
+ */
+const NOT_OURS = [/scripts\/editor-checks\//, /scripts\/editor-mcp/, /verify-desktop-render/];
+
+function sources(dir) {
+ const out = [];
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const abs = path.join(dir, entry.name);
+ if (entry.isDirectory()) out.push(...sources(abs));
+ else if (entry.name.endsWith('.mjs') && statSync(abs).isFile()) out.push(abs);
+ }
+ return out;
+}
+
+const problems = [];
+let launchers = 0;
+
+// A tool that names electron as the program it runs has to take its conditions
+// from electronRun. Spawning it any other way is how a caller ends up needing
+// the prefix that this repo just stopped writing.
+for (const file of sources(TOOLS)) {
+ const rel = path.relative(ROOT, file);
+ if (rel.endsWith('lib/electronRun.mjs') || rel.endsWith('check-electron-preconditions.mjs')) continue;
+ const src = readFileSync(file, 'utf8');
+ const byHand = /(?:runTool|spawnSync|spawn|execFile)\(\s*'(?:pnpm|npx|xvfb-run|electron)'[\s\S]{0,140}?'electron'/.test(src);
+ const viaOwner = /\brunElectron\(/.test(src);
+ if (!byHand && !viaOwner) continue;
+ launchers++;
+ if (byHand) problems.push(`${rel} — launches electron without electronRun`);
+}
+
+// A scan that finds nothing reports the same green as a repo with nothing wrong.
+// This repo launches Electron from several verifiers, so zero means the scan
+// broke — the first version of this file said 0 and passed.
+if (!launchers) problems.push('tools/ — found no electron launcher at all; this scan is broken');
+
+// And the other direction: a workflow that still hands a verifier the display
+// it now brings itself, which is the second list growing back.
+for (const name of readdirSync(WORKFLOWS)) {
+ if (!/\.ya?ml$/.test(name)) continue;
+ const rel = path.join('.github', 'workflows', name);
+ const lines = readFileSync(path.join(WORKFLOWS, name), 'utf8').split('\n');
+ lines.forEach((line, i) => {
+ if (!/xvfb-run|ELECTRON_DISABLE_SANDBOX/.test(line)) return;
+ if (NOT_OURS.some((re) => re.test(line))) return;
+ // The env var sits on its own line, so the step it belongs to is the run
+ // command below it — near enough that reading a few lines on finds it.
+ const near = lines.slice(i, i + 4).join('\n');
+ if (NOT_OURS.some((re) => re.test(near))) return;
+ problems.push(`${rel}:${i + 1} — supplies what electronRun supplies: ${line.trim().slice(0, 80)}`);
+ });
+}
+
+if (problems.length) {
+ console.error('check-electron-preconditions: Electron\'s conditions are owned by tools/lib/electronRun.mjs');
+ for (const p of problems) console.error(` ${p}`);
+ process.exit(1);
+}
+console.log(`check-electron-preconditions: ${launchers} verifier(s) launch electron, all through electronRun;`
+ + ' no workflow supplies its conditions by hand.');
diff --git a/tools/gates.mjs b/tools/gates.mjs
index e16fe10fe..37fc48351 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -206,6 +206,7 @@ export const GATES = [
// other direction — every checker has something RUNNING it. `verify:aot` spent
// two releases broken because nothing did.
{ id: 'verifier-owners', run: 'node tools/check-verifier-owners.mjs' },
+ { id: 'electron-preconditions', run: 'node tools/check-electron-preconditions.mjs' },
{ id: 'component-reference', run: 'node tools/component-reference.mjs --check' },
{ id: 'api-stability-page', run: 'node tools/api-stability.mjs --check' },
// The per-symbol tiers say what is frozen; this says what a creator can build
diff --git a/tools/lib/electronRun.mjs b/tools/lib/electronRun.mjs
new file mode 100644
index 000000000..25f561f37
--- /dev/null
+++ b/tools/lib/electronRun.mjs
@@ -0,0 +1,43 @@
+// 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 { runTool } from './runTool.mjs';
+
+/** 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';
+
+export const NEEDS_XVFB = process.platform === 'linux' && !process.env.ESTELLA_NO_XVFB;
+
+/**
+ * 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 electron = via === 'npx' ? ['npx', 'electron'] : ['pnpm', 'exec', 'electron'];
+ const [cmd, ...rest] = NEEDS_XVFB
+ ? ['xvfb-run', '-a', '--server-args', SCREEN, ...electron]
+ : electron;
+ return runTool(cmd, [...rest, ...args], {
+ ...options,
+ env: { ...process.env, ELECTRON_DISABLE_SANDBOX: '1', ...env },
+ });
+}
diff --git a/tools/run-electron.mjs b/tools/run-electron.mjs
new file mode 100644
index 000000000..64ffc09f6
--- /dev/null
+++ b/tools/run-electron.mjs
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file run-electron.mjs — electronRun.mjs, for the callers that are shell.
+ *
+ * Three verify:* scripts launch a headless verifier straight from package.json,
+ * where a JS module cannot be imported. Without this they would each need the
+ * xvfb prefix written beside them, which is the duplication electronRun exists
+ * to end.
+ *
+ * node tools/run-electron.mjs <script.mjs> [args…]
+ */
+import { runElectron } from './lib/electronRun.mjs';
+
+const args = process.argv.slice(2);
+if (!args.length) {
+ console.error('run-electron: name the script to run under electron');
+ process.exit(2);
+}
+const r = runElectron(args, { stdio: 'inherit' });
+if (r.status === null) {
+ console.error(r.stderr?.toString().trim() || 'run-electron: electron did not report a status');
+ process.exit(1);
+}
+process.exit(r.status);
diff --git a/tools/verify-aot-parity.mjs b/tools/verify-aot-parity.mjs
index ef9e5d81c..18fc1cccf 100644
--- a/tools/verify-aot-parity.mjs
+++ b/tools/verify-aot-parity.mjs
@@ -26,7 +26,7 @@ import path from 'node:path';
import { GOLDEN, projectDir, parityFor, launchTimeoutFor, ROOT } from './goldenProjects.mjs';
import { frameDistance } from './frameCompare.mjs';
import { retryOnDeadGpu, deadGpuVerdict } from './lib/deadGpu.mjs';
-import { runTool } from './lib/runTool.mjs';
+import { runElectron } from './lib/electronRun.mjs';
import { requireCurrentEngine } from './lib/engineBuild.mjs';
const argv = process.argv.slice(2);
@@ -108,7 +108,7 @@ function carriesModule(out) {
function launch(id, out, png, timeoutMs) {
const run = retryOnDeadGpu(
() => {
- const r = runTool('pnpm', ['exec', 'electron', LAUNCHER,
+ const r = runElectron([LAUNCHER,
'--dir', out, '--out', png, '--w', String(SURFACE.w), '--h', String(SURFACE.h),
...(timeoutMs ? ['--timeout', String(timeoutMs)] : []),
], { encoding: 'utf8', cwd: ROOT });
diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjs
index a75450478..459818e46 100644
--- a/tools/verify-golden.mjs
+++ b/tools/verify-golden.mjs
@@ -22,7 +22,7 @@ import path from 'node:path';
import { atTier, projectDir, parityFor, interactFor, audioFor, suspendFor, safeAreaFor, atlasFor, webPixels, launchTimeoutFor, ROOT } from './goldenProjects.mjs';
import { frameDistance, frameCellMax, readPNG } from './frameCompare.mjs';
import { retryOnDeadGpu, deadGpuVerdict } from './lib/deadGpu.mjs';
-import { runTool } from './lib/runTool.mjs';
+import { runElectron } from './lib/electronRun.mjs';
import { requireCurrentEngine } from './lib/engineBuild.mjs';
const argv = process.argv.slice(2);
@@ -100,11 +100,11 @@ function captureEditorFrame(id, out) {
const attempt = () => {
// A partial file from the attempt before would be read as this attempt's frame.
rmSync(out, { force: true });
- const r = runTool('npx', ['electron', '.'], {
+ const r = runElectron(['.'], {
+ via: 'npx',
encoding: 'utf8',
cwd: DESKTOP,
env: {
- ...process.env,
ESTELLA_SHOT: out,
ESTELLA_SHOT_PROJECT: projectDir(id),
// The scene the PACKAGE ships, named rather than inherited: opening a
@@ -191,8 +191,7 @@ function launchPackage(id, target, args) {
() => {
// Opening a PACKAGE needs no editor — the launchers are engine-side, so a
// checkout without one can still judge what it shipped.
- const r = runTool('pnpm', ['exec', 'electron', LAUNCHER(target), ...args],
- { encoding: 'utf8', cwd: ROOT });
+ const r = runElectron([LAUNCHER(target), ...args], { encoding: 'utf8', cwd: ROOT });
// The launcher prints a ✓/✗ line once it has looked at the frame; that
// line existing is what says a measurement happened.
const verdictLine = (r.stdout || '').split('\n').find((l) => l.startsWith('✓') || l.startsWith('✗'));
diff --git a/tools/verify-legacy.mjs b/tools/verify-legacy.mjs
index 9efd664a5..0926d0d10 100644
--- a/tools/verify-legacy.mjs
+++ b/tools/verify-legacy.mjs
@@ -25,7 +25,7 @@ import { tmpdir } from 'node:os';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { legacyAtTier, ROOT } from './goldenProjects.mjs';
-import { runTool } from './lib/runTool.mjs';
+import { runElectron } from './lib/electronRun.mjs';
// The migration's own tables, not a copy: a renamed component is not a lost one
// and a retired one is deliberately dropped, so comparing released spellings
@@ -126,11 +126,11 @@ for (const { tag, id } of cases) {
}
return JSON.stringify(shape);
})()`;
- const run = runTool('npx', ['electron', '.'], {
+ const run = runElectron(['.'], {
+ via: 'npx',
encoding: 'utf8',
cwd: DESKTOP,
env: {
- ...process.env,
ESTELLA_SHOT: path.join(work, 'open.png'),
ESTELLA_SHOT_PROJECT: work,
ESTELLA_SHOT_EVAL: probe,
diff --git a/tools/verify-playthrough.mjs b/tools/verify-playthrough.mjs
index 770249131..36577575f 100644
--- a/tools/verify-playthrough.mjs
+++ b/tools/verify-playthrough.mjs
@@ -21,7 +21,7 @@ import { spawnSync } from 'node:child_process';
import { existsSync, mkdirSync, rmSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
-import { runTool } from './lib/runTool.mjs';
+import { runElectron } from './lib/electronRun.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const DESKTOP = path.join(ROOT, 'desktop');
@@ -61,8 +61,8 @@ if (exported.status !== 0) {
process.exit(1);
}
-const played = runTool('pnpm', [
- 'exec', 'electron', path.join(ROOT, 'tools', 'launchers', 'play-through.mjs'),
+const played = runElectron([
+ path.join(ROOT, 'tools', 'launchers', 'play-through.mjs'),
'--dir', out, '--route', ROUTE,
'--out', path.join(WORK, `${PROJECT}.png`),
'--budget', '26000',
@@ -73,6 +73,10 @@ if (!argv.includes('--keep')) rmSync(WORK, { recursive: true, force: true });
if (played.status !== 0) {
console.error(`✗ ${PROJECT} cannot be played to the end of its route`);
+ // Only stdout was reported, so a driver that never launched left this saying
+ // the route failed — which is a verdict about the game, not about the runner.
+ const why = (played.stderr || '').trim();
+ if (why) console.error(why.slice(-800));
process.exit(1);
}
console.log(`verify-playthrough: ${PROJECT} plays through — ok`);
diff --git a/tools/verify-render.mjs b/tools/verify-render.mjs
index 9ad5c38f0..954b7dda8 100644
--- a/tools/verify-render.mjs
+++ b/tools/verify-render.mjs
@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url';
import { TIERS, SCENES, scenesAtTier, sceneWatchdogMs } from './renderScenes.mjs';
import { retryOnDeadGpu, deadGpuVerdict, resultMeasured } from './lib/deadGpu.mjs';
import { runTool } from './lib/runTool.mjs';
+import { runElectron } from './lib/electronRun.mjs';
import { requireCurrentEngine } from './lib/engineBuild.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -37,9 +38,7 @@ const ONLY = flag('only', '');
const BACKEND = flag('backend', 'webgl2');
const BUDGET = flag('budget', '');
const NO_BUILD = argv.includes('--no-build');
-// CI runners cannot use the SUID sandbox helper (not root-owned in
-// node_modules), and a pixel check does not need it.
-const XVFB = process.platform === 'linux' && !argv.includes('--no-xvfb');
+if (argv.includes('--no-xvfb')) process.env.ESTELLA_NO_XVFB = '1';
const only = ONLY ? new Set(ONLY.split(',').map((s) => s.trim())) : null;
if (only) {
@@ -163,17 +162,12 @@ const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
function runScene(scene) {
const RUNNER = 'tools/render-host/run.mjs';
const watchdog = watchdogFor(scene.host);
- const args = XVFB
- ? ['-a', 'pnpm', 'exec', 'electron', RUNNER]
- : ['exec', 'electron', RUNNER];
const at = Date.now();
- const r = runTool(XVFB ? 'xvfb-run' : 'pnpm', args, {
+ const r = runElectron([RUNNER], {
cwd: ROOT,
encoding: 'utf8',
timeout: watchdog + LAUNCH_MARGIN_MS,
env: {
- ...process.env,
- ELECTRON_DISABLE_SANDBOX: '1',
ESTELLA_VERIFY_TIMEOUT_MS: String(watchdog),
ESTELLA_VERIFY_HOST: scene.host,
...scene.env,