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
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.ymlindex 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.jsonindex 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.mjsnew file mode 100644index 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.mjsindex 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 builddiff --git a/tools/lib/electronRun.mjs b/tools/lib/electronRun.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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,