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.

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.mjs
index 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 BOTH
diff --git a/docs/astro/src/components/ApiStability.astro b/docs/astro/src/components/ApiStability.astro
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.json
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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' },
];