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(golden): certifying a capability now means exercising it

esengine9effb3f36f56
diff --git a/tools/check-golden.mjs b/tools/check-golden.mjs
index 2ecef77f8..698616a2f 100644
--- a/tools/check-golden.mjs
+++ b/tools/check-golden.mjs
@@ -15,7 +15,7 @@
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import path from 'node:path';
import {
- GOLDEN, CAPABILITIES, KNOWN_GAPS, TIERS, TARGETS,
+ GOLDEN, CAPABILITIES, KNOWN_GAPS, EVIDENCE, TIERS, TARGETS,
atTier, uncoveredCapabilities, nonGoldenExamples, projectDir, parityFor, interactFor,
} from './goldenProjects.mjs';
import { CRITERIA } from './releaseGate.mjs';
@@ -23,6 +23,30 @@ 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();
+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 if (/\.(ts|esscene|esprefab|esproject|json)$/.test(e.name)) {
+ 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',
@@ -99,6 +123,14 @@ for (const g of GOLDEN) {
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.
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index b049a66b6..fcbb83a8a 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -66,6 +66,50 @@ export const CAPABILITIES = [
'settings', 'controller', 'achievements', 'ui-inventory',
];
+/**
+ * What EXERCISING a capability looks like, as a pattern a project's sources or
+ * scene data must match. Without one, `certifies` is a word nothing reads:
+ * space-shooter certified `audio` with no sound in it and coverage passed.
+ * `null` = the claim is about the PACKAGE, so no source could show it.
+ */
+export const EVIDENCE = {
+ physics: /\b(RigidBody|BoxCollider|CircleCollider|CapsuleCollider|physicsPlugin|CharacterController)\b/,
+ input: /\b(Input|defineInputMap|isKeyDown|InputState)\b/,
+ animation: /\b(SpriteAnimator|Animator|spriteAnim|Flipbook|TimelinePlayer|AnimClip)\b/,
+ ecs: /\b(defineComponent|defineSystem)\b/,
+ particles: /\bParticleEmitter\b/,
+ audio: /\b(AudioSource|AudioListener|AudioBus|playSound|audioPlugin|Mixer)\b/,
+ 'ui-layout': /\b(UINode|Canvas|spawnUIEntity|FlexContainer)\b/,
+ text: /\bText\b/,
+ localization: /\b(Localization|i18nKey|setLocale)\b/,
+ spine: /\bSpine(Animation)?\b/,
+ material: /\b(Material|material)\b/,
+ 'asset-lifecycle': /\b(Assets|loadGroup|releaseGroup|preload)\b/,
+ tilemap: /\bTilemap(Layer)?\b/,
+ 'tile-collision': /\b(collision|Collider|tileCollision)\b/,
+ touch: /\b(touches|touchesStarted|touchAvailable|GestureDetector)\b/,
+ 'safe-area': /\bSafeArea\b/,
+ 'pause-resume': /\b(setPaused|Time|scale|onSuspend)\b/,
+ // The atlas directory is the evidence, and the `atlas` run block above already
+ // reads it — a text pattern would only find the word.
+ 'texture-atlas': null,
+ 'single-file': null,
+ 'startup-size': null,
+ 'hot-update': /\b(checkForUpdate|applyUpdate)\b/,
+ rollback: /\b(applyUpdate|rollback)\b/,
+ networking: /\b(Net|Replicated|NetId)\b/,
+ persistence: /\b(SaveManager|Storage|SaveEnvelope)\b/,
+ 'save-versioning': /\b(SaveMigration|migrations)\b/,
+ navigation: /\b(Nav|NavAgent|NavGrid|setNavDestination)\b/,
+ 'behavior-tree': /\b(BehaviorTreeAgent|behaviortree)\b|\.esbt\b/,
+ 'scene-transition': /\b(transitionTo|switchTo|SceneManager)\b/,
+ 'y-sort': /\bySortLayers\b/,
+ settings: /\b(Storage|settings)\b/,
+ controller: /\b(GamepadButton|GpButton|Stick|isGamepadConnected)\b/,
+ achievements: /\bAchievements\b/,
+ 'ui-inventory': /\b(ListView|createListView|ArrayDataSource)\b/,
+};
+
/**
* Capabilities the corpus does NOT cover yet, each with the reason. Declared so
* the hole is visible in the gate's output instead of being mistaken for
@@ -78,6 +122,11 @@ export const KNOWN_GAPS = {
// Measured: hello-world exports a 2.82MB single file, video-puzzle 3.22MB — so
// the floor is the runtime, not the game, and no project reaches the 2MB cap.
'startup-size': 'the playable runtime floor (~2.8MB) exceeds the 2MB default profile cap; see REARCH_EXPORT',
+ // The three EVIDENCE found being claimed by a project that did not exercise
+ // them. Each is now a hole somebody has to read rather than a word in a list.
+ audio: 'NO example in the repository uses audio at all — not a golden one, not a sample. The pillar ships (buses, ducking, the cooked MP3 path, the Mixer panel) with nothing certifying any of it',
+ animation: 'sprite-animation and cutscene exercise it, and neither is in the corpus; platformer claimed it and contains no animation',
+ material: 'effects-gallery is the only example with a material, and it is not in the corpus; spine-demo claimed it and has none',
};
/**
@@ -94,7 +143,7 @@ export const KNOWN_GAPS = {
export const GOLDEN = [
{
id: 'platformer',
- certifies: ['physics', 'input', 'animation'],
+ certifies: ['physics', 'input'],
targets: ['web', 'desktop', 'android'],
tier: 'pr',
interact: { keys: ['ArrowRight'], frames: 40 },
@@ -115,7 +164,7 @@ export const GOLDEN = [
},
{
id: 'space-shooter',
- certifies: ['ecs', 'particles', 'audio', 'texture-atlas'],
+ certifies: ['ecs', 'texture-atlas'],
targets: ['web', 'desktop', 'android'],
tier: 'pr',
interact: { keys: ['ArrowLeft'], frames: 40 },
@@ -144,7 +193,7 @@ export const GOLDEN = [
},
{
id: 'spine-demo',
- certifies: ['spine', 'material', 'asset-lifecycle'],
+ certifies: ['spine'],
targets: ['web', 'desktop', 'android', 'ios'],
tier: 'nightly',
interactGap: 'a showcase that cycles its own animations; nothing to press',
@@ -158,7 +207,7 @@ export const GOLDEN = [
},
{
id: 'hot-update-demo',
- certifies: ['hot-update', 'rollback'],
+ certifies: ['hot-update', 'rollback', 'asset-lifecycle'],
targets: ['web', 'android'],
tier: 'nightly',
interactGap: 'swaps an asset on a timer; no input path',
@@ -191,7 +240,7 @@ export const GOLDEN = [
'tilemap', 'tile-collision', 'navigation', 'behavior-tree',
'scene-transition', 'y-sort', 'localization', 'ui-layout', 'text',
'persistence', 'ui-inventory', 'achievements', 'touch', 'controller',
- 'pause-resume', 'safe-area',
+ 'pause-resume', 'safe-area', 'particles',
],
targets: ['web', 'desktop'],
// Nightly, not pr: a project earns the release gate by having run, and this