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
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file The scale gate — run the budgets against the stress corpus.
*
* Generates the 50,000-asset project (or reuses it), runs the scale suite, and
* prints the contract as a table: what each cost is allowed to be, what it is,
* and how much of its budget it uses.
*
* The gate itself is inside the suite — each metric asserts against its own
* budget, so a failure names the metric and prints the reason the budget exists.
* This script exists to make the corpus, to show the whole table at once, and to
* put that table in the CI job summary where somebody will actually read it.
*
* Its counterpart is `tools/perf-guard.mjs`, and they answer different
* questions. The guard asserts RATIOS between microbenchmarks — architectural
* invariants like "editing one UI field is far cheaper than adding a node" — and
* its numbers are a snapshot you accept with `--update`. This asserts CEILINGS
* on whole operations at a size no example reaches, and its numbers are not
* acceptable by the change that breaks them.
*
* node tools/perf-budget.mjs generate if needed, measure, gate
* node tools/perf-budget.mjs --table print the last run's table only
* node tools/perf-budget.mjs --regen force the corpus to be rebuilt
*/
import { existsSync, readFileSync, rmSync, appendFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { runTool } from './lib/runTool.mjs';
// The editor is an optional submodule and this verifier drives it. Saying so
// beats the failure a missing checkout produces on its own ("Command vitest not
// found"), which names neither the editor nor the reason it is wanted.
function requireEditor(what) {
if (existsSync(join(ROOT, 'desktop', 'package.json'))) return;
console.error(`${what} measures the EDITOR, which is not checked out.`);
console.error(' git submodule update --init desktop (private; you need access)');
process.exit(2);
}
import { generateStressProject, countAssets } from './stress-project.mjs';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const REPORT = join(ROOT, 'build', 'scale-report.json');
const argv = process.argv.slice(2);
if (argv.includes('--table')) {
if (!existsSync(REPORT)) {
console.error('perf-budget: no report yet — run `node tools/perf-budget.mjs` first.');
process.exit(1);
}
printTable(JSON.parse(readFileSync(REPORT, 'utf8')));
process.exit(0);
}
const corpus = await generateStressProject({
force: argv.includes('--regen'),
log: (m) => console.log(m),
});
if (corpus.assets !== countAssets(1)) {
console.error(`perf-budget: the corpus holds ${corpus.assets} assets, not ${countAssets(1)}.`
+ ' Budgets are calibrated against the full corpus and mean nothing against a smaller one.');
process.exit(1);
}
// A report left by an earlier run would be read as this one's if the suite died
// before writing anything.
rmSync(REPORT, { force: true });
requireEditor('The scale budget suite');
const run = runTool('pnpm', ['exec', 'vitest', 'run', '--config', 'vitest.scale.config.ts'], {
cwd: join(ROOT, 'desktop'),
stdio: 'inherit',
env: { ...process.env, ESTELLA_STRESS_PROJECT: corpus.dir },
});
if (!existsSync(REPORT)) {
console.error('perf-budget: the scale suite produced no report — it did not reach a single metric.');
process.exit(1);
}
const report = JSON.parse(readFileSync(REPORT, 'utf8'));
printTable(report);
summarise(report);
process.exit(run.status ?? 1);
// ---------------------------------------------------------------------------
function printTable(report) {
const { units, metrics } = report;
console.log('');
console.log(`Scale budgets — ${countAssets(1).toLocaleString('en-US')} assets`);
console.log(` one unit on this machine: ${Object.entries(units ?? {})
.map(([k, v]) => `${k} ${v.toFixed(2)}ms`).join(' ')}`);
console.log('');
let group = null;
for (const m of metrics) {
if (m.group !== group) {
group = m.group;
console.log(` ${group}`);
}
const bar = meter(m.pctOfBudget);
const raw = m.rawMs === null ? '' : ` (${fmt(m.rawMs)}ms)`;
console.log(` ${status(m.pctOfBudget)} ${m.name.padEnd(52)}`
+ `${String(m.measured).padStart(9)} / ${String(m.budget).padEnd(6)}${unitName(m.unit).padEnd(6)}`
+ ` ${bar} ${String(m.pctOfBudget).padStart(3)}%${raw}`);
}
console.log('');
const over = metrics.filter((m) => m.pctOfBudget > 100);
const near = metrics.filter((m) => m.pctOfBudget > 70 && m.pctOfBudget <= 100);
if (over.length) console.log(` ${over.length} over budget.`);
// Not a failure, and worth saying out loud: a metric drifting into its
// headroom is the only warning anybody gets before it stops being headroom.
if (near.length) console.log(` ${near.length} above 70% of budget — headroom is going.`);
if (!over.length && !near.length) console.log(' All within budget, none above 70%.');
console.log('');
}
/** The same table as markdown, for the GitHub job summary. */
function summarise(report) {
const out = process.env.GITHUB_STEP_SUMMARY;
if (!out) return;
const lines = [
`### Scale budgets — ${countAssets(1).toLocaleString('en-US')} assets`,
'',
`Calibration on this runner: ${Object.entries(report.units ?? {})
.map(([k, v]) => `\`${k}\` ${v.toFixed(2)}ms`).join(', ')}`,
'',
'| | metric | measured | budget | used | on this runner |',
'| --- | --- | ---: | ---: | ---: | ---: |',
];
for (const m of report.metrics) {
lines.push(`| ${m.pctOfBudget > 100 ? '❌' : m.pctOfBudget > 70 ? '⚠️' : '✅'} | ${m.name}`
+ ` | ${m.measured} ${unitName(m.unit)} | ${m.budget} ${unitName(m.unit)}`
+ ` | ${m.pctOfBudget}% | ${m.rawMs === null ? '—' : `${fmt(m.rawMs)}ms`} |`);
}
appendFileSync(out, `${lines.join('\n')}\n`);
}
// Declarations, not consts: printTable runs at module top level (above), so an
// arrow bound down here would still be in its temporal dead zone.
function unitName(u) { return u === 'MB' ? 'MB' : u === 'count' ? '' : u; }
function fmt(n) { return n >= 100 ? n.toFixed(0) : n.toFixed(1); }
function status(pct) { return pct > 100 ? 'FAIL' : pct > 70 ? 'near' : ' ok'; }
function meter(pct) {
const width = 20;
// Clamped at BOTH ends: a measurement can legitimately come out negative (a
// heap that shrank), and an unclamped bar threw a RangeError instead of
// printing which measurement it was.
const filled = Math.max(0, Math.min(width, Math.round((pct / 100) * width)));
return `[${'#'.repeat(filled)}${'.'.repeat(width - filled)}]`;
}