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 check-script-failure.mjs — a packaged game does not hide its own boot.
*
* A build with no project code has nothing to import, and one whose module
* throws at load has something that failed. A host that cannot tell those apart
* boots an empty world, paints a frame and reports a healthy start — and every
* symptom after that points somewhere else.
*
* The package DECLARES whether it has scripts, so they are three cases. This
* drives a real package for each:
*
* declared and sound boots, systems run, no errors
* not declared boots, no import attempted, no errors
* declared and throwing startup fails, the original message is observable
*
* node tools/check-script-failure.mjs
*/
import { spawnSync } from 'node:child_process';
import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { runElectron } from './lib/electronRun.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const WORK = path.join(ROOT, '.golden', 'script-failure');
const SOURCE = path.join(ROOT, 'examples', 'hello-world');
// It BOOTS what it packages, so it needs a real engine — the same two places the
// exporter looks. Skipped where building one is a choice, an error where CI has
// the artifact: otherwise "no runtime here" reads as "the package is broken".
const RUNTIME = [path.join(ROOT, 'build', 'wasm', 'web'),
path.join(ROOT, 'desktop', 'public', 'wasm')]
.find((d) => existsSync(path.join(d, 'esengine.wasm')));
if (!RUNTIME) {
const build = 'node build-tools/cli.js build -t web';
if (process.env.ESTELLA_REQUIRE_WASM) {
console.error('check-script-failure: ESTELLA_REQUIRE_WASM is set and there is no engine'
+ ` runtime in build/wasm/web or desktop/public/wasm.\n ${build}`);
process.exit(1);
}
console.log('check-script-failure: no engine runtime to boot — skipped'
+ ` (build it with \`${build}\`; the engine-coupled CI job sets ESTELLA_REQUIRE_WASM).`);
process.exit(0);
}
const LAUNCHER = path.join(ROOT, 'tools', 'launchers', 'launch-export.mjs');
const MARKER = 'DOGFOOD_BOOT_FAILURE';
const results = [];
const check = (what, ok, detail) => {
results.push(ok);
console.log(`${ok ? '✓' : '✗'} ${what}${detail ? ` — ${detail}` : ''}`);
};
/** A copy of the fixture project, optionally with its entry made to throw. */
function project(name, mutate) {
const dir = path.join(WORK, name);
rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
cpSync(SOURCE, dir, { recursive: true });
rmSync(path.join(dir, '.esengine'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
mutate?.(dir);
return dir;
}
function pack(dir, name) {
const out = path.join(WORK, `${name}-web`);
const r = spawnSync(process.execPath, [
path.join(ROOT, 'pipeline', 'bin', 'estella.mjs'), 'export', dir,
'--platform', 'web', '--out', out,
], { encoding: 'utf8', cwd: ROOT });
if (r.status !== 0) {
console.error(`✗ ${name}: the package did not build`);
console.error((r.stderr || r.stdout || '').split('\n').slice(-6).join('\n'));
process.exit(1);
}
return out;
}
/**
* Errors that say the MACHINE could not render, not that the package is broken.
*
* A software rasteriser losing its context at frame 0 leaves a boot with
* nothing drawn and three errors, none of them about the game. Judging that as
* an unclean boot reports the runner's GPU as the package's defect.
*/
const GPU_GONE = /GPU device lost|createTexture failed|Failed to create texture/;
/**
* What the launcher said the errors WERE, not how many.
*
* It prints each one indented under its verdict, capped at five, and then keeps
* writing at that same indent — how far it got, what the canvas was, "one flat
* colour". Taking every indented line therefore took diagnosis for error, which
* is what made a wholly environmental failure look partly like the package's.
*/
const SHOWN = 5;
function errorLines(text) {
const lines = text.split('\n');
const at = lines.findIndex((l) => /^[✓✗] /.test(l.trim()));
if (at < 0) return [];
const n = Math.min(Number(/errors=(\d+)/.exec(lines[at])?.[1] ?? 0), SHOWN);
return lines.slice(at + 1, at + 1 + n)
.filter((l) => /^ {4}\S/.test(l.trimEnd())).map((l) => l.trim());
}
/** Boot it headless and report what the page said while doing so. */
function boot(dir) {
const r = runElectron([
LAUNCHER, '--dir', dir, '--w', '480', '--h', '320',
'--settle', '20', '--timeout', '60000',
'--out', path.join(WORK, 'frame.png'),
], { encoding: 'utf8', cwd: ROOT });
const text = `${r.stdout ?? ''}${r.stderr ?? ''}`;
const line = text.split('\n').find((l) => /^[✓✗] /.test(l.trim())) ?? '';
// No verdict line at all means the browser never ran — this machine cannot
// answer the question, which is neither a pass nor a failure of the claim.
if (!line) {
console.log('check-script-failure: the packaged game never started here — nothing to judge');
console.log((text.trim().split('\n').slice(-4).join('\n')));
process.exit(2);
}
return { text, ok: line.includes('✓'), errors: Number(/errors=(\d+)/.exec(line)?.[1] ?? -1) };
}
rmSync(WORK, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
mkdirSync(WORK, { recursive: true });
// 1. Declared and sound.
{
const out = pack(project('sound'), 'sound');
const cfg = JSON.parse(readFileSync(path.join(out, 'game.config.json'), 'utf8'));
check('a project with code declares it in the package', /^scripts\.m?js$/.test(cfg.scripts),
`scripts ${JSON.stringify(cfg.scripts)}`);
const run = boot(out);
const said = errorLines(run.text);
// Every one of them, or none: a real script error beside a lost context is
// still a real script error, and only a wholly environmental failure is
// something this machine cannot answer.
if (run.errors > 0 && said.length > 0 && said.every((l) => GPU_GONE.test(l))) {
console.log('check-script-failure: the GPU went away before anything could be drawn'
+ ' — this machine cannot judge whether the package boots clean');
for (const l of said) console.log(` ${l}`);
process.exit(2);
}
check('and boots clean', run.ok && run.errors === 0,
`errors ${run.errors}${run.errors > 0 ? ` — ${said.join(' | ')}` : ''}`);
}
// 2. Not declared. The host must not go looking, and must not mind.
{
const out = pack(project('none', (dir) => {
const file = path.join(dir, 'project.esproject');
const proj = JSON.parse(readFileSync(file, 'utf8'));
delete proj.scriptEntry;
delete proj.scripts;
writeFileSync(file, JSON.stringify(proj, null, 2));
rmSync(path.join(dir, 'src'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
}), 'none');
const cfg = JSON.parse(readFileSync(path.join(out, 'game.config.json'), 'utf8'));
check('a project with no code declares none', cfg.scripts === undefined,
`scripts ${JSON.stringify(cfg.scripts)}`);
const run = boot(out);
check('and boots clean without importing anything', run.ok && run.errors === 0,
`errors ${run.errors}${run.errors > 0 ? ` — ${errorLines(run.text).join(' | ')}` : ''}`);
}
// 3. Declared and throwing. The whole point.
{
const out = pack(project('throwing', (dir) => {
const entry = path.join(dir, 'src', 'main.ts');
writeFileSync(entry, `throw new Error(${JSON.stringify(MARKER)});\n${readFileSync(entry, 'utf8')}`);
}), 'throwing');
const run = boot(out);
check('a project whose code throws does not report a healthy boot', !run.ok && run.errors > 0,
`errors ${run.errors}`);
check('and the original message reaches the page', run.text.includes(MARKER),
run.text.includes(MARKER) ? MARKER : 'marker not observed');
check('named as a startup failure rather than a stray log',
/startup failed/.test(run.text), '');
}
const failed = results.filter((ok) => !ok).length;
console.log(failed === 0
? `check-script-failure: ${results.length} claim(s) — a package cannot hide a boot it did not do`
: `check-script-failure: ${failed} of ${results.length} claim(s) failed`);
process.exit(failed === 0 ? 0 : 1);