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 releaseGate.mjs — what a release has to be able to say, and what says it.
*
* "Do not open 0.50 until these hold" is only a rule if the list is somewhere a
* machine reads. Written down anywhere else it decays the usual way: a criterion
* loses the check that answered it and nobody notices, because nothing was ever
* holding the two together.
*
* So each criterion names the command that settles it. A criterion no command
* answers is allowed — as `manual`, with who does it and why a machine cannot —
* and check-release-gate refuses the third case, a criterion with neither.
*
* This says the criteria are OWNED. Whether they PASS is what running them says.
*/
import { readFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
/**
* Which release these are the exit criteria for — derived, not typed.
*
* It was a literal and it drifted: 0.58 shipped under a list headed "0.57 exit
* criteria". A file whose purpose is refusing to let a list and its checks drift
* apart cannot be a second place the version is written.
*/
export const RELEASE = JSON.parse(readFileSync(
path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8',
)).version.split('.').slice(0, 2).join('.');
/**
* `answeredBy` is a shell command run from the repo root; `needs` are the files
* it lives in, so deleting a verifier fails the gate rather than the release.
*
* `host` says where a criterion CAN be answered — the same dimension gates.mjs
* spells `where`, and it owes a `why` for the same reason. Absent means a plain
* Linux runner, which is most of them; the four that say otherwise need a GPU,
* an Android toolchain, or a phone somebody is holding.
*/
export const CRITERIA = [
{
id: 'golden-packages',
says: 'every golden project packages and launches on every target it declares',
answeredBy: 'node tools/verify-golden.mjs --tier release --jobs 3',
needs: ['tools/verify-golden.mjs', 'tools/goldenProjects.mjs',
'tools/launchers/launch-export.mjs', 'tools/launchers/launch-minigame.mjs'],
},
{
id: 'package-matches-editor',
says: 'a packaged game shows what the editor showed',
answeredBy: 'node tools/verify-golden.mjs --tier release --jobs 3',
needs: ['tools/frameCompare.mjs'],
},
{
id: 'package-answers-input',
says: 'a packaged game visibly answers the input its project declares',
answeredBy: 'node tools/verify-golden.mjs --tier release --jobs 3',
needs: ['tools/launchers/inputScript.mjs'],
},
{
id: 'a-character-may-only-do-what-the-world-allows',
host: 'macos',
why: 'it judges a web package booted in Electron, which says nothing about Linux; a Linux runner has no GPU, and a package rasterised in software boots past the launch timeout often enough that the reading was of a game nobody drove',
says: 'a packaged third-person character climbs, is stopped, and lands where its world says',
// 29 launches over 2440 rendered frames — a nightly question, on the runner with a GPU. It sat in the push
// gate behind a step that always failed first, and never once ran there.
answeredBy: 'node tools/verify-third-person.mjs',
needs: ['tools/verify-third-person.mjs', 'examples/third-person-3d/project.esproject'],
},
{
id: 'a-streamed-place-is-ready-before-it-is-seen',
host: 'macos',
why: 'it judges a web package booted in Electron, which says nothing about Linux; a Linux runner has no GPU, and a package rasterised in software boots past the launch timeout often enough that the reading was of a game nobody drove',
says: 'a streamed place pays its own shader requirements while it is being prepared,'
+ ' not on the frame the player first sees it',
// The same command as above, deliberately under its own name: deleting the
// shader half would leave the character half green, and the registry unable
// to say what this command still owes.
answeredBy: 'node tools/verify-third-person.mjs',
needs: ['tools/verify-third-person.mjs',
'examples/third-person-3d/assets/materials/beacon.esmaterial'],
},
{
id: '3d-runs-where-it-ships',
host: 'android',
why: 'the same emulator boot, for the 3D corpus — only an emulator answers it, and it boots the template built from the commit being judged',
says: 'a game whose world is 3D boots and draws on a device',
// The web half is golden-packages' own command, and was run twice for one
// verdict. Only an emulator answers this: a solver that never compiled into
// the native host leaves a game that starts and draws an empty room.
answeredBy: 'node tools/verify-native-boot.mjs --platform android --examples all',
needs: ['examples/physics-3d/project.esproject', 'tools/verify-native-boot.mjs'],
},
{
id: 'every-pixel-gate-runs',
host: 'macos',
why: 'the second backend needs a real GPU — a Linux runner ships no graphics driver and every webgpu run there died in requestDevice',
says: 'every declared pixel gate has run, not just the ones CI happens to list',
// CI pays for the pr tier on each push. The rest — spine, video, particles,
// every material scene, text, ktx2 — was declared and run by nothing at all
// until the registry gave the whole set one runner.
//
// Both backends, because verify-render defaults to one: the scenes that
// declare the second are dropped in silence, which is the hole this
// criterion exists to close.
answeredBy:
'node tools/verify-render.mjs --tier nightly && node tools/verify-render.mjs --tier nightly --backend webgpu',
needs: ['tools/renderScenes.mjs', 'tools/verify-render.mjs'],
},
{
id: 'offline-versions-survive-cache-cleanup',
says: 'a mini-game package cleans old resource bytes at quota, preserves current and rollback versions, and restarts offline without downloading',
answeredBy: 'pnpm run verify:cache-budget',
needs: ['tools/launchers/cache-budget-render-verify.mjs',
'tools/cache-budget-render-fixture.mjs', 'tools/fixtures/cache-budget-render-fixture.ts'],
},
{
id: 'hot-update-lands-or-rolls-back',
says: 'a shipped build takes an update from a CDN, and refuses a broken one whole',
// The corpus can package hot-update-demo and launch it; neither says an
// update ever applied. This one serves a second build as the CDN, then two
// manifests that lie, and reads the pixel after each.
answeredBy: 'pnpm run verify:hotupdate',
needs: [
'tools/launchers/headless-hotupdate-verify.mjs',
'pipeline/tests/hotupdate-verify-fixture.test.ts',
],
},
{
id: 'a-desktop-app-runs-its-systems-as-machine-code',
says: 'a packaged desktop game loads its compiled systems and dispatches to them',
// Installed is not enough. A module can load and never be reached: on this
// road binding is settled at the first call, because a script pool does not
// exist until an entity has that component.
answeredBy: 'node tools/verify-aot-native.mjs',
needs: [
'tools/verify-aot-native.mjs',
'native/host/bindings/AotBindings.cpp',
'sdk/src/ecs/aot/installNativeAot.ts',
],
},
{
id: 'every-road-answers-the-same-world',
says: 'one source, on every road it runs, leaves the same world after every frame',
// Dispatching is not COMPUTING: the criterion above asks whether a packaged
// game REACHES a compiled system. A road that quietly fell back agrees with
// any trace, so the run must say a system was taken before agreement counts.
answeredBy: 'node tools/verify-native-conformance.mjs',
needs: [
'tools/verify-native-conformance.mjs',
'sdk/tests/fixtures/conformance-systems.ts',
'tests/aot/test_aot_conformance.cpp',
],
},
{
id: 'a-native-game-runs-the-solver-its-project-chose',
says: 'a native app runs the 3D solver (Jolt or PhysX) its project chose, not the other one under its name',
// Both solvers answer one interface and a host links both, so the failure
// is silent: a PhysX project that reached Jolt still simulates. The run must
// say which module it acquired, and the character's skin (PhysX's, not
// Jolt's) must show in where it stands.
answeredBy: 'node tools/verify-native-physx.mjs',
needs: [
'tools/verify-native-physx.mjs',
'sdk/src/ecs/bridge/nativeSideModules.ts',
'examples/physics-3d/project.esproject',
],
},
{
id: 'a-web-game-runs-its-systems-as-machine-code',
says: 'an exported web game loads its compiled systems and dispatches to them',
// The claim the desktop road already makes, on the road most games ship on.
// A twin that loads and is never called raises no error and changes no pixel,
// so neither parity nor the cooked check can see it.
answeredBy: 'pnpm run verify:aot',
needs: [
'tools/launchers/headless-aot-verify.mjs',
'sdk/src/runtime/runtimeLoader.ts',
'pipeline/src/bundle/buildCompiledSystems.ts',
],
},
{
id: 'a-compiled-system-is-cheaper-where-there-is-no-jit',
says: 'on a host with no JIT, a compiled system costs a fraction of the interpreted one',
// The fallback is SILENT: a system the dispatcher stops taking goes back to
// the interpreter by design, raising no error and changing no pixel. The bar
// is a same-machine RATIO — a millisecond ceiling is per machine.
answeredBy: 'node bench/aot-native/frame-bench.mjs --gate',
needs: [
'bench/aot-native/frame-bench.mjs',
'native/host/Bench.cpp',
'bench/aot-frame/project/src/systems.ts',
],
},
{
id: 'a-compiled-system-costs-what-it-matches',
says: 'a compiled system is paid over the entities it matches, not over the size of the world',
answeredBy: 'node bench/aot-native/frame-bench.mjs --gate',
needs: ['bench/aot-native/frame-bench.mjs', 'src/esengine/aot/AotHost.hpp',
'native/host/bindings/AotBindings.cpp'],
},
{
id: 'compiled-systems-compute-what-the-interpreter-computes',
says: 'a packaged compiled system moves the world exactly as the interpreted one does',
// Over the same FIXED steps, not the same wall clock: two launches of one
// package disagree by more than a wrong field offset does, so a comparison
// built on elapsed time measures the runner and not the arithmetic.
answeredBy: 'pnpm run verify:cooked',
needs: [
'tools/launchers/headless-cooked-verify.mjs',
'pipeline/tests/cooked-verify-fixture.test.ts',
],
},
{
id: 'compiled-game-packages-and-draws',
host: 'macos',
why: 'it judges a web package booted in Electron, which says nothing about Linux; a Linux runner has no GPU, and a package rasterised in software boots past the launch timeout often enough that the reading was of a game nobody drove',
says: 'a game whose systems were compiled packages, boots and draws the game it drew interpreted',
// Not "the same pixels": the loop is wall-clock, so two launches of ONE
// package already differ by more than a wrong field offset does (the file
// carries the measurement). This settles black, dead, or a different game.
answeredBy: 'node tools/verify-aot-parity.mjs',
needs: ['tools/verify-aot-parity.mjs', 'examples/space-shooter/src/systems/effects.ts'],
},
{
id: 'a-crash-leaves-something-the-player-can-send',
host: 'device',
why: '--require-device reads `adb devices` on the machine it runs on, and the Device Farm path uploads a bundle rather than attaching one — so no runner here can answer it. An EMULATOR answers it too, measured: the handler builds for whatever ABI the device reports, faults, and the record comes back with its phase and a backtrace',
says: 'the boot record survives a crash on a real device, with the phase and a backtrace',
// `--require-device` on purpose: without it the tool skips where there is no
// phone, which is right on a laptop and is a false pass under a release.
answeredBy: 'node tools/verify-bootlog-crash.mjs --require-device',
needs: ['tools/verify-bootlog-crash.mjs', 'native/host/BootLog.cpp'],
},
{
id: 'streamed-world-comes-and-goes',
says: 'in a packaged streamed world a place exists while someone is near it, and leaving takes everything it brought',
answeredBy: 'node tools/verify-world-residency.mjs',
needs: ['tools/verify-world-residency.mjs', 'examples/world-streaming-3d/project.esproject'],
},
{
id: 'old-projects-open',
says: 'projects released by older versions still open, with nothing dropped',
answeredBy: 'node tools/verify-legacy.mjs --tier release',
needs: ['tools/verify-legacy.mjs'],
},
{
id: 'play-stop-conserves',
says: 'Play/Stop 100 times returns every conserved counter to baseline, GL objects included',
// The check defaults to 12 cycles for a PR; the criterion is 100, so the
// command that answers it is the one that asks for 100.
answeredBy: 'cd desktop && SOAK_CYCLES=100 node scripts/editor-checks/run.mjs soak',
needs: ['desktop/scripts/editor-checks/soak.mjs', 'desktop/scripts/lib/censusJudge.mjs'],
},
{
id: 'scene-churn-flat',
says: 'opening and closing scenes shows no upward trend in GPU resources',
answeredBy: 'cd desktop && SOAK_CYCLES=40 node scripts/editor-checks/run.mjs scene-churn',
needs: ['desktop/scripts/editor-checks/scene-churn.mjs'],
},
{
id: 'headless-soak',
says: 'entity and prefab churn holds its bounded resources flat',
answeredBy: 'pnpm run soak',
needs: ['sdk/tests/soak/churn.test.ts', 'sdk/tests/soak/dist-probes.test.ts'],
},
{
id: 'lifecycle-torture',
says: 'asset and scene lifecycles survive interleaved load/unload/reload',
answeredBy: 'pnpm run torture',
needs: ['sdk/tests/torture/asset-lifecycle.test.ts', 'sdk/tests/torture/scene-lifecycle.test.ts'],
},
{
id: 'performance-ceilings',
says: 'no benchmark regresses past its recorded ceiling',
answeredBy: 'pnpm run perf && pnpm run scale',
needs: ['tools/perf-guard.mjs', 'tools/perf-budget.mjs'],
},
{
id: 'static-gates',
says: 'every declared contract still holds (api surface, layers, corpus, host shim…)',
// --complete, because `pnpm run verify` answers "the gates that could run are
// green" — 69 of 80 without an editor checkout, and exit 0 all the same. `ci`,
// not `local`: the seven `local` adds want a built engine no runner here has.
answeredBy: 'node tools/run-gates.mjs --scope ci --complete',
needs: ['tools/check-golden.mjs', 'tools/check-minigame-host.mjs'],
},
{
id: 'gates-that-need-a-built-engine',
says: 'the gates a built engine answers — C++ harnesses, the engine off emscripten,'
+ ' both physics modules, the shader twins, the arena server, and a package that boots',
host: 'dev',
why: 'each reads something a gate should not download — a pinned Dawn checkout and a build'
+ ' of it, or the engine and side-module wasm; CI covers them in its own C++ and'
+ ' engine-coupled jobs, and a release captain answers them together with'
+ ' `pnpm run gate:run --host dev`',
// `--where local` rather than their seven ids: gates.mjs already holds which
// gates these are, and a criterion that spelled them again would drift from it
// the first time an eighth is added.
answeredBy: 'node tools/run-gates.mjs --scope local --where local',
needs: ['tools/check-cpp-tests.mjs', 'tools/check-native-build.mjs',
'tools/check-script-failure.mjs'],
},
{
id: 'flagship-plays-through',
says: 'the flagship can be played from its first room to its boss, as a package (reached, not defeated)',
// Every other gate asks whether something works. This asks the only thing a
// player asks — and a game whose second door cannot be opened passes all of
// the others.
answeredBy: 'node tools/verify-playthrough.mjs',
needs: [
'tools/verify-playthrough.mjs',
'tools/launchers/play-through.mjs',
'examples/celestial-heights/playthrough.json',
],
},
{
id: 'no-engine-gaps-at-ship',
says: 'the flagship game had to route around the engine nowhere that is still open',
answeredBy: 'node tools/check-engine-gaps.mjs --empty',
needs: ['tools/check-engine-gaps.mjs', 'examples/celestial-heights/engine-gaps.mjs'],
},
{
id: 'site-shows-the-real-game',
says: 'the README and landing showcase use real editor or game captures with accurate captions',
// Keep release acceptance captures separate from the curated site showcase.
// A historical editor preview must not be labelled as a current release capture.
manual: 'release captain: verify the landing showcase caption describes the displayed editor or game capture; separately verify hero-provenance.json in release-site-frame identifies this source commit and its frame matches the exported examples/celestial-heights game',
},
{
id: 'diagnostics-from-a-release-build',
says: 'a shipped build can export a diagnostic bundle',
// No runner: it needs an installed, signed application, which is the one
// artifact CI produces and cannot then run as a user would.
manual: 'release captain, on the downloaded build: Help → Export Diagnostics',
},
{
id: 'frozen-api-earned',
says: 'every @public symbol is documented, pinned by a test, and called by a golden project',
answeredBy: 'node tools/check-freeze-bar.mjs',
needs: ['tools/check-freeze-bar.mjs', 'tools/goldenProjects.mjs'],
},
{
id: 'frozen-api-kept',
says: 'the @public promises the last release shipped are all still kept',
answeredBy: 'node tools/api-surface.mjs --check-baseline',
needs: ['tools/api-surface.mjs', 'tools/lib/apiSnapshot.mjs'],
},
{
id: 'frozen-api-spelled-in-frozen-types',
says: 'no @public signature names a type at a weaker tier except where the gap is declared',
answeredBy: 'node tools/check-tier-leaks.mjs',
needs: ['tools/check-tier-leaks.mjs'],
},
{
id: 'tiers-reach-the-creator',
says: 'the stability tier is in the .d.ts a project compiles against, not only in our snapshot',
// The 17 @beta symbols index claimed while the built declarations carried 3
// is what this is for: a tier nobody can see is a tier nobody can act on.
answeredBy: 'node tools/api-surface.mjs --check-dts',
needs: ['tools/api-surface.mjs', 'tools/lib/sdkProgram.mjs'],
},
{
id: 'plugin-api-answers-for-itself',
says: 'the editor plugin API states which side of the 1.x contract it is on, everywhere it is read',
// The question 0.50 had to answer, and the answer is "experimental, outside
// the contract". What fails a release is not the answer but its absence from
// one of the places somebody acts on it.
answeredBy: 'node tools/check-plugin-api-contract.mjs',
needs: ['tools/check-plugin-api-contract.mjs', 'editor-api/index.ts'],
},
{
id: 'a-tier-above-experimental-is-earned',
says: 'no subsystem is published as beta or public without the evidence a @public symbol needs',
// The other half of `frozen-api-earned`, one level up. A tier is a promise to
// a creator, and before this the only thing holding one was the prose beside
// it — two rows said "not read for a tier yet", which is a note, not a bar.
answeredBy: 'node tools/check-tier-bar.mjs',
needs: ['tools/check-tier-bar.mjs', 'tools/lib/apiEvidence.mjs', 'tools/apiSubsystems.mjs'],
},
{
id: 'every-subsystem-has-a-verdict',
says: 'every part of the engine publishes a tier at the size a creator builds in, and the tags carry it',
// The per-symbol tiers are enforced above. This is the same answer at the
// size somebody actually asks it: 1462 experimental symbols read the same
// whether a subsystem was weighed or nobody looked.
answeredBy: 'node tools/check-subsystem-tiers.mjs',
needs: ['tools/apiSubsystems.mjs', 'tools/check-subsystem-tiers.mjs'],
},
{
id: 'creator-can-say-what-is-safe',
says: 'the docs name the four tiers and which APIs are in each, in both languages',
// What a tier MEANS is a promise to people, and the sentence making it is
// not something to compute from a snapshot.
manual: 'release captain, over docs/astro: the stability page matches sdk/etc and VERSIONING.md',
},
{
id: 'no-p0-packaging-bugs',
says: 'no open P0 against packaging or launch',
manual: 'release captain, over the tracker — a count of issues is not a thing to compute here',
},
];