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
docs(api): a creator can look up what each API promises them
yhh730eb7ff5d49
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex e680e2831..4bf9a6053 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -337,6 +337,11 @@ export default defineConfig({{ label: 'Gameplay', translations: { 'zh-CN': '玩法' }, slug: 'reference/components/gameplay' },],},+ {+ label: 'API Stability',+ translations: { 'zh-CN': 'API 稳定性' },+ slug: 'reference/api-stability',+ },typeDocSidebarGroup,// Doxygen output is merged in beside the Astro build, not routed by// it, and it isn't translated. A root-relative link would get BOTHdiff --git a/docs/astro/src/components/ApiStability.astro b/docs/astro/src/components/ApiStability.astronew file mode 100644index 000000000..007d6a84b--- /dev/null+++ b/docs/astro/src/components/ApiStability.astro@@ -0,0 +1,131 @@+---+// The tier inventory, derived from sdk/etc/*.api.md (tools/api-stability.mjs)+// so what this page claims is frozen cannot drift from what the guard enforces.+import snapshot from '@/data/apiStability.generated.json';++interface Symbol {+ name: string;+ kind: string;+ deprecated: boolean;+ entries: string[];+}++const zh = Astro.url.pathname.includes('/zh-cn/');+const t = (en: string, cn: string) => (zh ? cn : en);++const counts = snapshot.counts as Record<string, number>;+const pub = snapshot.public as Symbol[];+const beta = snapshot.beta as Symbol[];+---++<div class="st-counts">+ <div class="st-count st-public">+ <strong>{counts.public}</strong>+ <span>{t('Stable Candidate', '稳定候选')}</span>+ </div>+ <div class="st-count st-beta">+ <strong>{counts.beta}</strong>+ <span>{t('Beta', 'Beta')}</span>+ </div>+ <div class="st-count st-exp">+ <strong>{counts.experimental}</strong>+ <span>{t('Experimental', '实验性')}</span>+ </div>+</div>++<p class="st-note">+ {t(+ `${snapshot.total} exported symbols in total. Experimental is the default: a symbol reaches a+ stronger tier only when someone decides it has, so this page grows one deliberate step at a time.`,+ `共 ${snapshot.total} 个导出符号。实验性是默认值——一个符号只有在有人明确决定时才会升级,所以这份清单是一步步长出来的。`,+ )}+</p>++<h2 id="stable-candidate">{t('Stable Candidate', '稳定候选')}</h2>+<p>+ {t(+ 'We expect 1.0 not to break these. Each one is documented, pinned by a test, and used by a game we certify releases against; changing or removing one takes a deprecation release first.',+ '我们预计 1.0 不会破坏这些。每一个都有文档、有测试钉住、并被我们用来验收发布的游戏真实调用;要改动或移除,必须先经过一个弃用版本。',+ )}+</p>+<table>+ <thead>+ <tr><th>{t('Symbol', '符号')}</th><th>{t('Kind', '种类')}</th></tr>+ </thead>+ <tbody>+ {pub.map((s) => (+ <tr>+ <td><code>{s.name}</code>{s.deprecated && <span class="st-flag">{t('deprecated', '已弃用')}</span>}</td>+ <td>{s.kind}</td>+ </tr>+ ))}+ </tbody>+</table>++<h2 id="beta">Beta</h2>+<p>+ {t(+ 'Shipping and supported, but the shape may still adjust before 1.0. Build on them; expect to read the changelog.',+ '已发布并受支持,但形状在 1.0 前仍可能调整。可以用,但升级时请读 changelog。',+ )}+</p>+<table>+ <thead>+ <tr><th>{t('Symbol', '符号')}</th><th>{t('Kind', '种类')}</th></tr>+ </thead>+ <tbody>+ {beta.map((s) => (+ <tr>+ <td><code>{s.name}</code>{s.deprecated && <span class="st-flag">{t('deprecated', '已弃用')}</span>}</td>+ <td>{s.kind}</td>+ </tr>+ ))}+ </tbody>+</table>++<h2 id="experimental">{t('Experimental', '实验性')}</h2>+<p>+ {t(+ 'Everything else, which is most of the surface. It works and it is what the editor itself is built on, but no compatibility claim is attached: it may change or disappear in any release. Your editor shows the tier on hover, and sdk/etc/*.api.md in the repository is the full inventory.',+ '其余全部,也就是这个面的绝大部分。它们能用,编辑器本身就建立在它们之上,但不附带任何兼容性承诺:任何版本都可能改动或消失。编辑器里悬停即可看到分级,仓库中的 sdk/etc/*.api.md 是完整清单。',+ )}+</p>++<style>+ .st-counts {+ display: flex;+ flex-wrap: wrap;+ gap: 1rem;+ margin-block: 1.5rem;+ }+ .st-count {+ flex: 1 1 8rem;+ padding: 0.9rem 1rem;+ border: 1px solid var(--sl-color-hairline);+ border-radius: 0.5rem;+ border-top-width: 3px;+ }+ .st-count strong {+ display: block;+ font-size: 1.75rem;+ line-height: 1.1;+ }+ .st-count span {+ font-size: var(--sl-text-sm);+ color: var(--sl-color-gray-3);+ }+ .st-public { border-top-color: var(--sl-color-green); }+ .st-beta { border-top-color: var(--sl-color-blue); }+ .st-exp { border-top-color: var(--sl-color-gray-4); }+ .st-note {+ font-size: var(--sl-text-sm);+ color: var(--sl-color-gray-3);+ }+ .st-flag {+ margin-inline-start: 0.4rem;+ padding: 0.05rem 0.35rem;+ border-radius: 0.25rem;+ background: var(--sl-color-orange-low);+ font-size: var(--sl-text-xs);+ }+</style>diff --git a/docs/astro/src/content/docs/reference/api-stability.mdx b/docs/astro/src/content/docs/reference/api-stability.mdxnew file mode 100644index 000000000..6ff2b3df9--- /dev/null+++ b/docs/astro/src/content/docs/reference/api-stability.mdx@@ -0,0 +1,37 @@+---+title: API stability+description: "What each Estella API promises you, and which APIs are in each tier."+---++import ApiStability from '@/components/ApiStability.astro';++Estella is pre-1.0, and not all of its API is equally settled. Rather than ask you+to guess which parts are, every exported symbol carries exactly one stability tier+as a JSDoc tag on its declaration — so it ships in the `.d.ts` your project+compiles against, and your editor shows it when you hover.++| Tier | Tag | What it promises |+| --- | --- | --- |+| **Stable Candidate** | `@public` | We expect 1.0 not to break it. Removing or changing one takes a deprecation release first. |+| **Beta** | `@beta` | Shipping and supported; the shape may still adjust before 1.0. |+| **Experimental** | `@experimental` | No compatibility claim. It may change or disappear in any release. |+| **Internal** | `@internal` | Not for you to depend on. It is a build error for one to be exported at all. |++There is no stable-by-default. An untagged symbol is **Experimental**, so freezing+an API is something we decide, never something we forget to prevent.++A symbol only reaches Stable Candidate once three things are true: it is+documented, a test pins its behaviour, and one of the games we certify releases+against actually calls it. That bar is a build gate, not a habit — and so is the+promise itself, which is compared against the previous release tag on every push.++The full list below is generated from the same snapshots the guards read.++<ApiStability />++## What this does not cover++The tiers above describe the TypeScript API. Estella's 1.0 promise also covers the+project and asset formats, the WASM runtime contract, and the documented build CLI+— see [Versioning Policy](https://github.com/esengine/estella/blob/master/VERSIONING.md)+for what a breaking change means for each.diff --git a/docs/astro/src/content/docs/zh-cn/reference/api-stability.mdx b/docs/astro/src/content/docs/zh-cn/reference/api-stability.mdxnew file mode 100644index 000000000..ea8b3607c--- /dev/null+++ b/docs/astro/src/content/docs/zh-cn/reference/api-stability.mdx@@ -0,0 +1,34 @@+---+title: API 稳定性+description: "每个 Estella API 对你承诺了什么,以及哪些 API 属于哪一级。"+---++import ApiStability from '@/components/ApiStability.astro';++Estella 还在 1.0 之前,API 各部分的稳定程度并不一致。与其让你去猜哪些能依赖,+每个导出符号都在自己的声明上带一个稳定性标记 —— 它会随 `.d.ts` 一起进入你的项目,+在编辑器里悬停就能看到。++| 等级 | 标记 | 承诺 |+| --- | --- | --- |+| **稳定候选** | `@public` | 我们预计 1.0 不会破坏它。要改动或移除,必须先经过一个弃用版本。 |+| **Beta** | `@beta` | 已发布并受支持,但形状在 1.0 前仍可能调整。 |+| **实验性** | `@experimental` | 不作兼容性承诺,任何版本都可能改动或消失。 |+| **内部** | `@internal` | 请勿依赖。它被导出本身就是一个构建错误。 |++没有「默认稳定」这回事。未标记的符号一律是**实验性** —— 冻结一个 API 是我们主动做出的+决定,而不是忘了阻止的结果。++一个符号要升到稳定候选,必须同时满足三件事:有文档、有测试钉住它的行为、并且被我们+用来验收发布的那几个游戏真实调用。这道门槛是构建门禁而不是习惯;承诺本身也一样,+每次推送都会与上一个发布 tag 比对。++下面的清单由守卫读取的同一份快照生成。++<ApiStability />++## 这里没有覆盖的部分++以上分级描述的是 TypeScript API。Estella 的 1.0 承诺还包括项目与资源格式、WASM 运行时+契约,以及有文档的构建 CLI —— 每一项的「破坏性改动」如何定义,见+[版本策略](https://github.com/esengine/estella/blob/master/VERSIONING.md)。diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonnew file mode 100644index 000000000..e75b58eeb--- /dev/null+++ b/docs/astro/src/data/apiStability.generated.json@@ -0,0 +1,346 @@+{+ "note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",+ "counts": {+ "public": 6,+ "beta": 24,+ "experimental": 1594,+ "deprecated": 1+ },+ "total": 1624,+ "public": [+ {+ "name": "Commands",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Mut",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Query",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Res",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "defineComponent",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "defineSystem",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ }+ ],+ "beta": [+ {+ "name": "GraphNodeType",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "GraphType",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "MaterialGraph",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "MaterialGraphNode",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "NODE_SPECS",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "NativeBridge",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index.native"+ ]+ },+ {+ "name": "NativeFetchResult",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index.native"+ ]+ },+ {+ "name": "NativeInputListener",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index.native"+ ]+ },+ {+ "name": "NativePlatformAdapter",+ "kind": "class",+ "deprecated": false,+ "entries": [+ "index.native"+ ]+ },+ {+ "name": "NodeParamSpec",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "NodePort",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "NodeSpec",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "addNode",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "compileMaterialGraph",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "connect",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "createHeadlessApp",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "disconnect",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "installNativePlatform",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index.native"+ ]+ },+ {+ "name": "loadEsengineModule",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index.node"+ ]+ },+ {+ "name": "moveNode",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "newMaterialGraph",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "nodeAdapter",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index.node"+ ]+ },+ {+ "name": "removeNode",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "runHeadless",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ }+ ]+}diff --git a/tools/api-stability.mjs b/tools/api-stability.mjsnew file mode 100644index 000000000..3e3d25a39--- /dev/null+++ b/tools/api-stability.mjs@@ -0,0 +1,77 @@+#!/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';++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,+ 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.');diff --git a/tools/gates.mjs b/tools/gates.mjsindex ab7a802f6..36cc0ad7e 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -68,6 +68,7 @@ export const GATES = [{ id: 'minigame-host', run: 'node tools/check-minigame-host.mjs' },{ id: 'release-gate', run: 'node tools/check-release-gate.mjs' },{ id: 'component-reference', run: 'node tools/component-reference.mjs --check' },+ { id: 'api-stability-page', run: 'node tools/api-stability.mjs --check' },{ id: 'examples', run: 'node build-tools/cli.js check-examples' },{ id: 'prefabs', run: 'node build-tools/cli.js validate-prefabs' },];