Skip to content

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.

feat(gates): the capability census is answerable against what shipped

esengine584f0989d7b2
diff --git a/tools/check-golden.mjs b/tools/check-golden.mjs
index 269d29e88..500c6446a 100644
--- a/tools/check-golden.mjs
+++ b/tools/check-golden.mjs
@@ -16,6 +16,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
import path from 'node:path';
import {
GOLDEN, CAPABILITIES, KNOWN_GAPS, EVIDENCE, TIERS, TARGETS,
+ SHIPPED, CENSUS_FLOOR, shippedGround,
atTier, uncoveredCapabilities, nonGoldenExamples, projectDir, parityFor, interactFor,
} from './goldenProjects.mjs';
import { CRITERIA } from './releaseGate.mjs';
@@ -59,6 +60,9 @@ const NEEDS_RUN = {
// 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. */
@@ -196,6 +200,40 @@ for (const g of GOLDEN) {
}
// 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`);
+ }
+ }
+}
+
for (const c of uncoveredCapabilities()) {
fail(`nothing certifies "${c}" — add a project, or declare the gap in KNOWN_GAPS with a reason`);
}
@@ -224,8 +262,15 @@ 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})`,
);
+// 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();
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index 6f04df6db..a2dd85805 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -15,7 +15,7 @@
* (check-golden.mjs) refuses a capability nobody covers unless the gap is
* declared here in the open.
*/
-import { readdirSync, existsSync } from 'node:fs';
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -42,6 +42,102 @@ export const DEFAULT_PARITY = 0.06;
*/
export const DEFAULT_RESPONDS = 0.15;
+/**
+ * The release the shipped-feature census reaches back to. Older releases are out
+ * of its scope BY DECLARATION rather than by silence, and the gate says so.
+ */
+export const CENSUS_FLOOR = '0.60.0';
+
+/**
+ * Every shipped feature at or after {@link CENSUS_FLOOR}, classified: key names
+ * one release-note headline, value the capability a project must carry or why
+ * none can. A feature missing from {@link CAPABILITIES} reads exactly like one
+ * that does not exist, and release notes are a different act. Theirs is ungated.
+ */
+export const SHIPPED = {
+ // — 0.61.0 —
+ 'World streaming': { certifies: 'world-streaming' },
+ 'Level of detail': { certifies: 'level-of-detail' },
+ 'An inventory of what the engine\'s runtime contract facts':
+ { notCertifiable: 'an inventory OF contracts; check-contract-inventory reads it, and no game act exercises it' },
+ 'Two ways out of an animation': { certifies: ['animation-events', 'root-motion'] },
+ 'Emission asks the shape': { certifies: 'particles' },
+ 'Screen-space ambient occlusion': { certifies: 'ssao' },
+ 'The hitch when something first becomes visible': { certifies: 'shader-readiness' },
+ 'A mesh comes back after a device loss':
+ { notCertifiable: 'a playthrough cannot lose the device; the device-loss harness is the proof' },
+ 'A texture\'s compression is two decisions':
+ { notCertifiable: 'a cook/upload pair, read by check-texture-format; a game ships the result and cannot tell the two records apart' },
+ 'The shadow atlas and the light cap name who they turned away':
+ { notCertifiable: 'a census of refusals, read by check-shadow-plan and check-light-cap' },
+ 'The post chain commits to one intermediate format':
+ { notCertifiable: 'one format per frame, read by check-hdr-format' },
+ 'The built-in audio buses are declared once': { certifies: 'audio' },
+ 'A saved map says which encoding it was painted under': { certifies: 'tilemap' },
+ 'An event payload has a shape': { certifies: 'ecs' },
+ 'A game can state what its own run has reached':
+ { notCertifiable: 'the playthrough seam every certification runs THROUGH, not a capability it certifies' },
+ 'The multiplayer example ships the server': { certifies: 'networking' },
+ 'The packaged native host answers the AOT conformance fixture':
+ { notCertifiable: 'a conformance fixture across two hosts; no game content decides it' },
+ 'An inventory of the decisions the engine takes':
+ { notCertifiable: 'an inventory OF decisions, read by check-decision-inventory' },
+
+ // — 0.60.0 —
+ 'A sprite frame draws at its own size': { certifies: 'animation' },
+ 'A flipbook editor that reads in frames': { notCertifiable: 'an editor panel; the editor suite owns it' },
+ 'A spine skeleton nobody can see costs an advance': { certifies: 'spine' },
+ 'A spine frame that can say what it cost': { certifies: 'spine' },
+ 'A skeleton an editor can pose': { notCertifiable: 'an editor preview surface; the editor suite owns it' },
+ 'A hot update reaches what was built': { certifies: 'hot-update' },
+ 'A live binding follows the asset': { certifies: 'asset-lifecycle' },
+ 'A persistent entity owns what it carries out of its scene': { certifies: 'scene-transition' },
+ 'A ref-bound asset is owned as a slot': { certifies: 'asset-lifecycle' },
+ 'A render-graph pass can name a resource the graph must not bind':
+ { notCertifiable: 'a graph authoring rule, read by check-frame-lifecycle' },
+ 'An offscreen preview is addressed by its handle':
+ { notCertifiable: 'an editor preview surface; the editor suite owns it' },
+};
+
+/** Numeric compare of two `x.y.z` strings. */
+function versionAtLeast(v, floor) {
+ const a = v.split('.').map(Number);
+ const b = floor.split('.').map(Number);
+ for (let i = 0; i < 3; i++) {
+ if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+ }
+ return true;
+}
+
+/**
+ * The shipped features the CHANGELOG names at or after the floor — the ground
+ * {@link SHIPPED} is answerable against. Headlines only: a bullet leads with a
+ * bolded sentence, and the prose under it is the same claim at length.
+ */
+export function shippedGround() {
+ const text = readFileSync(path.join(ROOT, 'CHANGELOG.md'), 'utf8');
+ const out = [];
+ let version = null;
+ let inAdded = false;
+ let bullet = null;
+ const flush = () => {
+ if (bullet === null) return;
+ const head = /^-\s+\*\*(.+?)\*\*/s.exec(bullet.replace(/\n/g, ' '));
+ if (head) out.push({ version, headline: head[1].replace(/\s+/g, ' ').trim() });
+ bullet = null;
+ };
+ for (const line of text.split('\n')) {
+ const release = /^## \[(\d+\.\d+\.\d+)\]/.exec(line);
+ if (release) { flush(); version = release[1]; inAdded = false; continue; }
+ if (/^## /.test(line)) { flush(); version = null; inAdded = false; continue; }
+ if (/^### /.test(line)) { flush(); inAdded = /^### Added/.test(line); continue; }
+ if (!inAdded || version === null || !versionAtLeast(version, CENSUS_FLOOR)) continue;
+ if (/^- /.test(line)) { flush(); bullet = line; } else if (bullet !== null) { bullet += `\n${line}`; }
+ }
+ flush();
+ return out;
+}
+
/**
* What the suite claims to cover. A capability here with no project behind it
* is a hole in the release argument, so the gate fails on one that is not in
@@ -54,6 +150,7 @@ export const CAPABILITIES = [
'spine', 'material', 'asset-lifecycle',
'model-import', 'model-animation', 'model-skinning',
'physics-3d', 'mesh-shadow', 'environment', 'level-of-detail', 'world-streaming',
+ 'ssao', 'navigation-3d', 'root-motion', 'animation-events', 'shader-readiness',
'tilemap', 'tile-collision',
'touch', 'safe-area', 'pause-resume',
'texture-atlas',
@@ -102,6 +199,16 @@ export const EVIDENCE = {
// its world is cut and by carrying something that asks for places.
'world-streaming': /\b(StreamedWorld|WorldStreamingSource)\b/,
environment: /\.esenv\b/,
+ // The post effect a scene turns on, not the pass that implements it.
+ ssao: /"type":\s*"ssao"/,
+ 'navigation-3d': /\b(NavVolume|NavLink|NavAgent3D)\b/,
+ 'root-motion': /\brootMotion\b/,
+ // Events authored ON a clip. The runtime always read them; what shipped is a
+ // format and an editor that can write them.
+ 'animation-events': /"events"\s*:\s*\[/,
+ // Nothing in a project's text can show it: the claim is that the first visible
+ // frame pays no compile, which only a run can settle. See NEEDS_RUN.
+ 'shader-readiness': null,
'asset-lifecycle': /\b(Assets|loadGroup|releaseGroup|preload)\b/,
tilemap: /\bTilemap(Layer)?\b/,
'tile-collision': /\b(collision|Collider|tileCollision)\b/,
@@ -134,6 +241,12 @@ export const EVIDENCE = {
* coverage — the same bargain check-project-settings strikes.
*/
export const KNOWN_GAPS = {
+ // Shipped in 0.61 and carried by no project — the 3D stack's composition debt.
+ // Work items, not dispensations: the staleness check below forces an entry out
+ // the moment a project certifies it.
+ 'root-motion': 'no golden project has a character moved by its animation; the 3D composition project owes it',
+ 'animation-events': 'no golden project authors events on a clip and acts on them; the 3D composition project owes it',
+ 'shader-readiness': 'no golden project watches the frame something first appears on; needs a runBy a release criterion schedules',
// Present in the engine and shown by non-golden samples, but never carried
// through the chain by a project the release argues from.
settings: 'Celestial Heights persists language, effects and key bindings and reads them back at boot; volume waits on the game having sound',
@@ -235,7 +348,7 @@ export const GOLDEN = [
},
{
id: 'third-person-3d',
- certifies: ['third-person', 'level-of-detail'],
+ certifies: ['third-person', 'level-of-detail', 'ssao', 'navigation-3d'],
targets: ['web'],
tier: 'pr',
// The character walks on the key it declares. What it DOES on the way is