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
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file api-stability.mjs — the tier inventory the docs publish, from the snapshots.
*
* A hand-written list of what is frozen is a second answer to a question
* sdk/etc already answers, and the two would part company the first time
* someone tagged a symbol without remembering the page. So the page is
* generated from the snapshots and gated, the way the component reference is.
*
* node tools/api-stability.mjs --check exit 1 if the page is behind
* node tools/api-stability.mjs --update regenerate it
*/
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { ROOT, ETC, ENTRIES } from './lib/sdkProgram.mjs';
import { parseSnapshot } from './lib/apiSnapshot.mjs';
import { SUBSYSTEMS } from './apiSubsystems.mjs';
const OUT = join(ROOT, 'docs/astro/src/data/apiStability.generated.json');
const mode = process.argv[2];
if (mode !== '--check' && mode !== '--update') {
console.error('usage: node tools/api-stability.mjs --check | --update');
process.exit(2);
}
/** Every symbol across every entry, unioned, with the entries it appears in. */
function inventory() {
const symbols = new Map();
for (const entryName of Object.keys(ENTRIES)) {
const file = join(ETC, `${entryName}.api.md`);
if (!existsSync(file)) continue;
for (const [name, s] of parseSnapshot(readFileSync(file, 'utf8'))) {
const seen = symbols.get(name);
if (seen) { seen.entries.push(entryName); continue; }
symbols.set(name, { name, kind: s.kind, tier: s.tier, deprecated: s.deprecated, entries: [entryName] });
}
}
return symbols;
}
function build() {
const symbols = [...inventory().values()];
const of = (tier) => symbols
.filter((s) => s.tier === tier)
.sort((a, b) => (a.name < b.name ? -1 : 1))
.map(({ name, kind, deprecated, entries }) => ({ name, kind, deprecated, entries }));
const counts = { public: 0, beta: 0, experimental: 0, deprecated: 0 };
for (const s of symbols) {
if (counts[s.tier] !== undefined) counts[s.tier]++;
if (s.deprecated) counts.deprecated++;
}
return JSON.stringify({
note: 'Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.',
counts,
total: symbols.length,
// The table a creator actually reads: check-subsystem-tiers holds each
// verdict against the tags its entry symbols carry.
subsystems: SUBSYSTEMS.map(({ id, title, titleZh, tier, why, whyZh, entry }) =>
({ id, title, titleZh, tier, why, whyZh, entry })),
public: of('public'),
beta: of('beta'),
}, null, 2) + '\n';
}
const report = build();
if (mode === '--update') {
writeFileSync(OUT, report);
console.log(`wrote ${OUT}`);
process.exit(0);
}
const existing = existsSync(OUT) ? readFileSync(OUT, 'utf8').replace(/\r\n?/g, '\n') : '';
if (existing !== report) {
console.error('api-stability: the published tier inventory is behind sdk/etc.');
console.error('Run: node tools/api-stability.mjs --update');
process.exit(1);
}
console.log('api-stability: the published tier inventory matches the snapshots.');