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 apiEvidence.mjs — the three things that hold a promise about a symbol up.
*
* A stability claim is only worth the evidence under it: documentation, because
* the freeze is the moment the contract stops being readable from the code; a
* test, because a shape nothing pins moves with the first thing that touches it;
* and a real game, because a symbol no chain ever calls has never been tried.
*
* One definition, because two now ask: `check-freeze-bar` about a @public symbol
* and `check-tier-bar` about the entry a subsystem publishes its verdict on. Two
* copies would be two bars called by one name.
*/
import { readFileSync, readdirSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { SDK, ts, ENTRIES, createSdkProgram, leadingDoc, docProseLines } from './sdkProgram.mjs';
import { GOLDEN, projectDir } from '../goldenProjects.mjs';
/** Snapshot kinds a game calls at runtime; the rest are shapes. */
export const VALUE_KINDS = new Set(['class', 'enum', 'function', 'const', 'value', 'namespace']);
function walk(dir, onFile, skip) {
let entries;
try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
for (const e of entries) {
const p = join(dir, e.name);
if (skip(p, e.name)) continue;
if (e.isDirectory()) walk(p, onFile, skip);
else onFile(p);
}
}
/** A leading doc block carrying at least one line that is not a tag. */
export function hasDocProse(decl) {
return docProseLines(leadingDoc(decl)).length > 0;
}
/** A `describe('X', …)` title is prose that happens to sit inside a string. */
const TITLE = /\b(?:describe|it|test|bench)(?:\.\w+)*\s*\(\s*(['"`])(?:[^\\]|\\.)*?\1/g;
/**
* Every identifier a test names IN CODE. Comments and test titles are stripped
* first: a symbol whose only appearance is `describe('TextOverflow', …)` has
* nothing pinning its shape, and that one was @public.
*
* A string that is not a title still counts — naming a component by its string
* is how several APIs are called, and a rename breaks that as loudly.
*/
export function testedIdentifiers() {
const seen = new Set();
const skip = (p, name) => name === 'node_modules' || name === 'dist';
walk(join(SDK, 'src'), collect, skip);
walk(join(SDK, 'tests'), collect, skip);
function collect(p) {
if (!/\.test\.ts$/.test(p)) return;
const code = readFileSync(p, 'utf8')
.replace(/\/\*[\s\S]*?\*\//g, ' ')
.split('\n').map((l) => l.replace(/(^|[^:'"`\\\w])\/\/.*$/, '$1')).join('\n')
.replace(TITLE, (m, q) => m.slice(0, m.indexOf(q)) + q + q);
for (const id of code.match(/[A-Za-z_$][\w$]*/g) ?? []) seen.add(id);
}
return seen;
}
// Every entry, not just the root one: the SDK ships nine, and a symbol reached
// through `esengine/spine` is as exercised as one reached through `esengine`.
const ESENGINE_IMPORT = /import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]esengine(?:\/[^'"]+)?['"]/g;
/** Symbols each golden project imports from an `esengine` entry, as `name -> [projectId]`. */
export function exercisedByGolden() {
const out = new Map();
for (const g of GOLDEN) {
const dir = projectDir(g.id);
if (!existsSync(dir)) continue;
walk(dir, (p) => {
if (!/\.ts$/.test(p) || /\.d\.ts$/.test(p)) return;
const src = readFileSync(p, 'utf8');
for (const m of src.matchAll(ESENGINE_IMPORT)) {
for (const raw of m[1].split(',')) {
const name = raw.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim();
if (!name) continue;
if (!out.has(name)) out.set(name, new Set());
out.get(name).add(g.id);
}
}
}, (p, name) => name === '.esengine' || name === 'node_modules' || name === 'dist');
}
return out;
}
/**
* Where each of `wanted` is declared, across every SDK entry, aliases resolved.
* A name that resolves to nothing is absent from the map — a caller has to treat
* that as "cannot tell", not as "meets the bar".
*/
export function declarationsOf(wanted, program, checker) {
const out = new Map();
for (const entryPath of Object.values(ENTRIES)) {
const sourceFile = program.getSourceFile(join(SDK, entryPath));
const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
if (!moduleSymbol) continue;
for (const symbol of checker.getExportsOfModule(moduleSymbol)) {
if (out.has(symbol.name) || !wanted.has(symbol.name)) continue;
const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
const decl = resolved.declarations?.[0];
if (decl) out.set(symbol.name, decl);
}
}
return out;
}
export { createSdkProgram };
/** Frozen, and its only users write it into a scene rather than importing it —
* so the corpus holds MORE of it than before and `exercised` sees none. */
const AUTHORED_INSTEAD = (what) => `${what} — the corpus writes it in scenes, which \`exercised\` does not read`;
/**
* Symbols the evidence above cannot see, and why. Each is handed to a system body
* by a declared parameter, or built by the engine on a game's behalf: a golden
* project runs one every frame and no import list ever names it. A bar asking
* about these is blind, not unmet, which is a different answer.
*/
const RECEIVED = 'received from a declared parameter, never imported — golden projects run it, no import list names it';
const HANDED_BACK = 'answered by a frozen factory, never imported — a game names the factory, not this';
export const BLIND = {
// Same blindness, from the other direction: the map's rebind scan builds one
// when a player binds a mouse button, so a certified game runs it without any
// import list ever naming it.
MouseButton: 'built by InputMap\'s rebind scan on the game\'s behalf — run by a golden project, named by none',
// Same shape of blindness: the engine maintains this one from Parent, so a
// game reads it and every golden project's layout walks it every frame, but
// nothing imports the name.
Children: 'engine-maintained from Parent — walked every frame, named in no import list',
// A newer blindness, and one that grows as the corpus moves from building
// things in code to AUTHORING them: `exercised` reads a golden project's
// TypeScript, and a scene writes these as plain numbers.
percent: AUTHORED_INSTEAD('the code spelling of a unit every authored UINode carries'),
SpriteMaskInteraction: AUTHORED_INSTEAD("the enum behind Sprite.maskInteraction, which space-shooter's hull bar now sets in its scene"),
SpriteDrawMode: AUTHORED_INSTEAD("the enum behind Sprite.drawMode, which space-shooter's starfield now sets in its scene to tile rather than stretch"),
CommandsInstance: RECEIVED,
EntityCommands: RECEIVED,
EventReaderInstance: RECEIVED,
QueryInstance: RECEIVED,
RemovedQueryInstance: RECEIVED,
ResMutInstance: RECEIVED,
};