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-golden.mjs — the certification corpus says what it covers, or says why not.
*
* The Golden Project Suite is an argument that a release ships working games. An
* argument with a silent hole in it is worse than no argument: "the suite is
* green" then means "the suite is green about the things it happens to run".
*
* So every capability the suite claims must have a project behind it, every
* project must exist and be packageable, and every target must be a real export
* target. A capability nothing covers is allowed — declared in KNOWN_GAPS, with
* a reason, so the hole is a sentence somebody wrote.
*/
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import path from 'node:path';
import {
GOLDEN, CAPABILITIES, KNOWN_GAPS, EVIDENCE, TIERS, TARGETS,
SHIPPED, CENSUS_FLOOR, shippedGround, EVIDENCE_FORMATS, NOT_EVIDENCE_FORMATS,
atTier, uncoveredCapabilities, nonGoldenExamples, projectDir, parityFor, interactFor,
ROOT,
} from './goldenProjects.mjs';
import { CRITERIA } from './releaseGate.mjs';
const problems = [];
const fail = (msg) => problems.push(msg);
/** What a project is, as text: its sources plus the scene and prefab data it
* opens, since a capability can be exercised declaratively. */
const projectTextCache = new Map();
/** Every extension the reader met, so it can be held to classifying them. */
const seenFormats = new Set();
function projectText(id) {
if (projectTextCache.has(id)) return projectTextCache.get(id);
const parts = [];
const walk = (dir) => {
let entries;
try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
for (const e of entries) {
if (e.name === '.esengine' || e.name === 'node_modules' || e.name === 'dist') continue;
const p = path.join(dir, e.name);
if (e.isDirectory()) walk(p);
else {
const ext = e.name.slice(e.name.lastIndexOf('.'));
seenFormats.add(ext);
if (EVIDENCE_FORMATS.includes(ext)) {
try { parts.push(readFileSync(p, 'utf8')); } catch { /* unreadable */ }
}
}
}
};
walk(projectDir(id));
const text = parts.join('\n');
projectTextCache.set(id, text);
return text;
}
/** Capabilities a packaged frame cannot show, and the declaration whose run reads them. */
const NEEDS_RUN = {
'texture-atlas': 'atlas',
audio: 'audio',
'authored-sound': 'authoredAudio',
settings: 'settings',
'safe-area': 'safeArea',
'pause-resume': 'suspend',
'hot-update': 'runBy',
rollback: 'runBy',
// A frame of two coloured squares is what a working session and a broken one
// both look like. Nothing about replication is visible in a screenshot, so the
// claim needs the run that opens a socket.
networking: 'runBy',
// A packaged frame looks the same whether the first sight of something cost a
// compile or not. Only a run that watches the frame it first appears on says.
'shader-readiness': 'runBy',
};
/** Commands a release is defined as running — what makes `runBy` more than a string. */
const SCHEDULED = CRITERIA.map((c) => c.answeredBy ?? '').join('\n');
// 1. Every golden id is a project that exists and declares a scene to open.
const seen = new Set();
// The engine's own list of targets, so a platform it gained cannot be one no
// golden project is allowed to name — which is how Douyin shipped as a built-in
// target while this file would have rejected a project that certified it.
{
const src = readFileSync(path.join(ROOT, 'pipeline', 'src', 'project', 'platforms.ts'), 'utf8');
const block = /BUILTIN_PLATFORMS: readonly BuiltinPlatform\[\] = \[([\s\S]*?)\];/.exec(src);
if (!block) fail('no BUILTIN_PLATFORMS in pipeline/src/project/platforms.ts — the list moved');
else {
const engine = [...block[1].matchAll(/'([a-z0-9]+)'/g)].map(([, p]) => p);
const missing = engine.filter((p) => !TARGETS.includes(p));
if (missing.length) {
fail(`the engine builds ${missing.join(', ')}, which no golden project may name — add to TARGETS`);
}
}
}
for (const g of GOLDEN) {
if (seen.has(g.id)) fail(`"${g.id}" is listed twice`);
seen.add(g.id);
const manifest = path.join(projectDir(g.id), 'project.esproject');
if (!existsSync(manifest)) {
fail(`"${g.id}" has no examples/${g.id}/project.esproject — a golden project must be packageable`);
continue;
}
let parsed;
try {
parsed = JSON.parse(readFileSync(manifest, 'utf8'));
} catch (e) {
fail(`"${g.id}" has an unreadable manifest: ${e.message}`);
continue;
}
// Every stage after "open" needs a scene to open; an export with no entry
// scene packages an empty game and still exits 0.
const scene = parsed.defaultScene;
if (!scene) fail(`"${g.id}" declares no defaultScene — the chain has nothing to open`);
else if (!existsSync(path.join(projectDir(g.id), scene))) {
fail(`"${g.id}" names a defaultScene that is not there: ${scene}`);
}
if (!TIERS.includes(g.tier)) fail(`"${g.id}" has tier "${g.tier}" (have: ${TIERS.join(', ')})`);
if (!g.targets?.length) fail(`"${g.id}" names no targets — then nothing packages it`);
for (const t of g.targets ?? []) {
if (!TARGETS.includes(t)) fail(`"${g.id}" names target "${t}" (have: ${TARGETS.join(', ')})`);
}
// Parity is the release's own claim, so opting out of it is a sentence, not a flag.
if (g.parityGap !== undefined && !(typeof g.parityGap === 'string' && g.parityGap.trim())) {
fail(`"${g.id}" sets parityGap without a reason — say why its frames cannot be compared`);
}
if (g.parity !== undefined && !(typeof g.parity === 'number' && g.parity > 0 && g.parity < 1)) {
fail(`"${g.id}" has parity ${g.parity} — expected a tolerance between 0 and 1`);
}
if (g.parity !== undefined && g.parityGap) fail(`"${g.id}" both sets a parity tolerance and opts out`);
// Same bargain as parity: a project that cannot be driven says why.
if (g.interactGap !== undefined && !(typeof g.interactGap === 'string' && g.interactGap.trim())) {
fail(`"${g.id}" sets interactGap without a reason — say why nothing can be pressed`);
}
if (g.interact && g.interactGap) fail(`"${g.id}" both declares input and opts out of it`);
if (!g.interact && !g.interactGap) {
fail(`"${g.id}" neither declares input nor says why it has none — the chain has no interact step for it`);
}
if (g.interact && !(g.interact.keys?.length > 0) && !g.interact.pointer) {
fail(`"${g.id}" declares input with neither keys nor a pointer target`);
}
const pt = g.interact?.pointer;
if (pt && !(pt.x >= 0 && pt.x <= 1 && pt.y >= 0 && pt.y <= 1)) {
fail(`"${g.id}" has a pointer target outside the surface — x/y are fractions, not pixels`);
}
if (!g.certifies?.length) fail(`"${g.id}" certifies nothing — say what it is in the suite for`);
for (const c of g.certifies ?? []) {
if (!CAPABILITIES.includes(c)) fail(`"${g.id}" certifies "${c}", which is not a declared capability`);
// Packaging and parity come free with being in the corpus; these do not.
// Claiming one without declaring the run that reads it is how a capability
// ends up "covered" by a project that never exercises it.
const block = NEEDS_RUN[c];
if (block && !g[block]) {
fail(`"${g.id}" certifies "${c}" but declares no ${block} — a claim only a run can settle needs that run`);
}
// The claim has to be findable in the project. Without this, certifying a
// capability is a word in a registry: space-shooter certified `audio` and had
// no sound in it, and the coverage check below was satisfied by that.
if (!(c in EVIDENCE)) {
fail(`"${c}" has no EVIDENCE pattern — say what exercising it looks like, or null if nothing can`);
} else if (EVIDENCE[c] && !EVIDENCE[c].test(projectText(g.id))) {
fail(`"${g.id}" certifies "${c}" but nothing in the project matches ${EVIDENCE[c]} — the claim is not backed`);
}
}
// A command nobody schedules is the hole this whole file exists to refuse: the
// hot-update run existed for a year and no criterion or workflow ever ran it.
if (g.runBy && !SCHEDULED.includes(g.runBy)) {
fail(`"${g.id}" is settled by \`${g.runBy}\`, which no release criterion runs — add it to releaseGate.mjs`);
}
// Membership is only coverage while it is declared somewhere: moving those
// textures out, or dropping the atlases entry, would take the claim with them.
if (g.atlas) {
if (!(g.atlas.packed > 0)) fail(`"${g.id}" declares atlas without a positive packed count`);
const assets = path.join(projectDir(g.id), 'assets');
const byFolder = existsSync(assets)
&& readdirSync(assets, { withFileTypes: true, recursive: true })
.some((e) => e.isDirectory() && e.name.endsWith('.atlas'));
let declared = false;
try {
const cfg = JSON.parse(readFileSync(path.join(projectDir(g.id), '.esengine', 'asset-groups.json'), 'utf8'));
declared = Object.keys(cfg.atlases ?? {}).length > 0;
} catch { declared = false; }
if (!byFolder && !declared) {
fail(`"${g.id}" claims texture-atlas with no atlas: no <name>.atlas/ folder and no \`atlases\` entry`);
}
}
// The fixture is only a guard while it is still there AND still odd-sized.
if (g.oddSizedKtx2) {
const abs = path.join(projectDir(g.id), g.oddSizedKtx2);
if (!existsSync(abs)) fail(`"${g.id}" names oddSizedKtx2 ${g.oddSizedKtx2}, which is not there`);
else {
// KTX2 header: 12-byte identifier, vkFormat, typeSize, then width, height.
const head = readFileSync(abs).subarray(0, 28);
const w = head.readUInt32LE(20);
const h = head.readUInt32LE(24);
if (w % 4 === 0 && h % 4 === 0) {
fail(`"${g.id}" names oddSizedKtx2 ${g.oddSizedKtx2}, but ${w}x${h} IS whole blocks — it guards nothing`);
}
}
}
const au = g.audio;
if (au) {
const t = au.toggle;
if (!t || !(t.x >= 0 && t.x <= 1 && t.y >= 0 && t.y <= 1)) {
fail(`"${g.id}" declares audio without a toggle inside the surface — x/y are fractions`);
}
if (!au.bar) fail(`"${g.id}" declares audio without a bar to read — then nothing says signal arrived`);
// A floor of 0 would pass on a bar the layout never sized, which is the same
// reading as silence.
if (!(au.floor > 0)) fail(`"${g.id}" declares audio with floor ${au.floor} — the silent height has to be a real one`);
}
const sa = g.safeArea;
if (sa) {
if (!sa.entity || !sa.reference) fail(`"${g.id}" declares safeArea without both an entity and a reference`);
if (sa.entity === sa.reference) fail(`"${g.id}" reads safeArea against itself — the reference must be a second node`);
// Equal insets would let a run that moves the node by one fixed amount pass.
if (!(sa.top > 0) || !(sa.left > 0)) fail(`"${g.id}" declares safeArea without a positive top and left inset`);
else if (sa.top === sa.left) fail(`"${g.id}" gives safeArea the same inset on both edges — then the run cannot see scaling`);
}
}
// 2. No capability is claimed by the suite and covered by nobody.
// Every shipped feature is classified, and every classification names one.
// CAPABILITIES is otherwise the only author of how big the world is, and a list
// answerable only against itself reports full coverage of whatever it contains.
const ground = shippedGround();
const matched = new Map();
for (const bullet of ground) {
const keys = Object.keys(SHIPPED).filter((k) => bullet.headline.startsWith(k));
if (keys.length === 0) {
fail(`${bullet.version} ships "${bullet.headline.slice(0, 60)}…" and nothing classifies it`
+ ' — name the capability a project must carry, or why none can');
} else if (keys.length > 1) {
fail(`${bullet.version} "${bullet.headline.slice(0, 40)}…" is classified ${keys.length} times`
+ ` (${keys.join(' / ')}) — one shipped feature, one classification`);
} else {
matched.set(keys[0], (matched.get(keys[0]) ?? 0) + 1);
}
}
for (const [key, entry] of Object.entries(SHIPPED)) {
// The other direction: a classification naming no feature is a census that has
// stopped reading the thing it censuses.
if (!matched.has(key)) {
fail(`nothing at or after ${CENSUS_FLOOR} ships "${key}" — the classification names no feature`);
}
const certifies = entry.certifies === undefined ? [] : [entry.certifies].flat();
if (certifies.length === 0 && !entry.notCertifiable) {
fail(`"${key}" is classified as neither certifiable nor not — say which`);
}
for (const c of certifies) {
if (!CAPABILITIES.includes(c)) {
fail(`"${key}" says a project must certify "${c}", which is not a declared capability`);
}
}
}
// Every format a golden project holds is either evidence or declared not to be.
// A reader that opens some of a project answers about all of it: root motion and
// clip events were authored, verified on the packaged game, and read by nothing.
for (const g of GOLDEN) projectText(g.id);
for (const ext of [...seenFormats].sort()) {
if (EVIDENCE_FORMATS.includes(ext) || ext in NOT_EVIDENCE_FORMATS) continue;
fail(`golden projects hold "${ext}" files and the evidence reader classifies it as neither`
+ ' read nor irrelevant — say which, or a capability authored in one reads as absent');
}
for (const ext of EVIDENCE_FORMATS) {
if (ext in NOT_EVIDENCE_FORMATS) fail(`"${ext}" is declared both evidence and not`);
}
for (const c of uncoveredCapabilities()) {
fail(`nothing certifies "${c}" — add a project, or declare the gap in KNOWN_GAPS with a reason`);
}
// 3. A declared gap that something now covers is stale bookkeeping.
const covered = new Set(GOLDEN.flatMap((g) => g.certifies));
for (const c of Object.keys(KNOWN_GAPS)) {
if (!CAPABILITIES.includes(c)) fail(`KNOWN_GAPS names "${c}", which is not a declared capability`);
else if (covered.has(c)) fail(`"${c}" is declared a gap but ${[...covered].includes(c) ? 'a project certifies it' : ''} — drop the entry`);
}
// 4. Every tier can actually run something.
for (const tier of TIERS) {
if (atTier(tier).length === 0) fail(`tier "${tier}" selects no projects`);
}
if (problems.length) {
console.error('check-golden: the certification corpus does not hold up.\n');
for (const p of problems) console.error(` ${p}`);
process.exit(1);
}
const noParity = GOLDEN.filter((g) => parityFor(g) === null);
const driven = GOLDEN.filter((g) => interactFor(g) !== null);
const gaps = Object.keys(KNOWN_GAPS).length;
const pairs = TIERS.map((t) => `${t} ${atTier(t).length}`).join(' / ');
console.log(
`check-golden: ${GOLDEN.length} golden project(s) certify ${covered.size}/${CAPABILITIES.length} capabilities`
+ `, ${ground.length} shipped feature(s) classified since ${CENSUS_FLOOR}`
+ ' (release notes are the ground; nothing gates THEIR completeness)'
+ `, ${gaps} declared gap(s) — ok (${pairs})`,
);
console.log(` evidence read from ${EVIDENCE_FORMATS.length} authored format(s);`
+ ` ${Object.keys(NOT_EVIDENCE_FORMATS).length} more carry no claim;`
+ ` ${seenFormats.size} met in the corpus, 0 unclassified`);
// Named, not counted. A number is a hole nobody reads; the whole bargain of
// declaring one is that it stays in front of the next person to run this.
for (const [c, why] of Object.entries(KNOWN_GAPS)) {
console.log(` no project certifies "${c}" — ${why}`);
}
console.log(` ${driven.length} project(s) drive their package with input; ${GOLDEN.length - driven.length} say why they cannot`);
for (const g of noParity) console.log(` no editor/package comparison for ${g.id}: ${g.parityGap}`);
const rest = nonGoldenExamples();
if (rest.length) console.log(` ${rest.length} example(s) outside the corpus (smoke-tested, not certified)`);