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(api): every subsystem publishes a verdict, at the size a creator builds in

esengine46367c4363e9
diff --git a/docs/astro/src/components/ApiStability.astro b/docs/astro/src/components/ApiStability.astro
index 007d6a84b..4ddfca171 100644
--- a/docs/astro/src/components/ApiStability.astro
+++ b/docs/astro/src/components/ApiStability.astro
@@ -10,12 +10,31 @@ interface Symbol {
entries: string[];
}
+interface Subsystem {
+ id: string;
+ title: string;
+ titleZh: string;
+ tier: string;
+ why?: string;
+ whyZh?: string;
+ entry: 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[];
+const subsystems = snapshot.subsystems as Subsystem[];
+
+const TIER_LABEL: Record<string, [string, string]> = {
+ public: ['Stable Candidate', '稳定候选'],
+ beta: ['Beta', 'Beta'],
+ experimental: ['Experimental', '实验性'],
+};
+const ORDER = ['public', 'beta', 'experimental'];
+const ranked = [...subsystems].sort((a, b) => ORDER.indexOf(a.tier) - ORDER.indexOf(b.tier));
---
<div class="st-counts">
@@ -41,6 +60,35 @@ const beta = snapshot.beta as Symbol[];
)}
</p>
+<h2 id="by-subsystem">{t('By subsystem', '按子系统')}</h2>
+<p>
+ {t(
+ 'The same answer at the size you build in. Every verdict here is held against the tags its entry symbols carry, so this table cannot quietly disagree with them.',
+ '同一个答案,但按你真正在用的粒度给出。表里每条裁定都被它的入口符号的标签钉住,所以它不会悄悄和标签说不一样的话。',
+ )}
+</p>
+<table>
+ <thead>
+ <tr>
+ <th>{t('Subsystem', '子系统')}</th>
+ <th>{t('Tier', '分级')}</th>
+ <th>{t('Why', '理由')}</th>
+ </tr>
+ </thead>
+ <tbody>
+ {ranked.map((s) => (
+ <tr>
+ <td>{t(s.title, s.titleZh)}</td>
+ <td><span class={`st-pill st-pill-${s.tier}`}>{t(...TIER_LABEL[s.tier])}</span></td>
+ <td class="st-why">
+ {t(s.why ?? 'Frozen — the bar it had to clear is below.',
+ s.whyZh ?? '已冻结——它必须跨过的门槛见下。')}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+</table>
+
<h2 id="stable-candidate">{t('Stable Candidate', '稳定候选')}</h2>
<p>
{t(
@@ -121,6 +169,21 @@ const beta = snapshot.beta as Symbol[];
font-size: var(--sl-text-sm);
color: var(--sl-color-gray-3);
}
+ .st-pill {
+ display: inline-block;
+ padding: 0.05rem 0.45rem;
+ border-radius: 0.25rem;
+ font-size: var(--sl-text-xs);
+ white-space: nowrap;
+ border: 1px solid var(--sl-color-hairline);
+ }
+ .st-pill-public { border-color: var(--sl-color-green); }
+ .st-pill-beta { border-color: var(--sl-color-blue); }
+ .st-pill-experimental { border-color: var(--sl-color-gray-4); }
+ .st-why {
+ font-size: var(--sl-text-sm);
+ color: var(--sl-color-gray-3);
+ }
.st-flag {
margin-inline-start: 0.4rem;
padding: 0.05rem 0.35rem;
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index a4994da41..363c1d1fd 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -7,6 +7,290 @@
"deprecated": 3
},
"total": 1630,
+ "subsystems": [
+ {
+ "id": "ecs",
+ "title": "ECS",
+ "titleZh": "ECS",
+ "tier": "public",
+ "entry": [
+ "defineComponent",
+ "defineSystem",
+ "Query",
+ "Mut",
+ "Res",
+ "Commands",
+ "World"
+ ]
+ },
+ {
+ "id": "app-lifecycle",
+ "title": "App lifecycle",
+ "titleZh": "应用生命周期",
+ "tier": "public",
+ "entry": [
+ "Schedule",
+ "addSystemToSchedule",
+ "addStartupSystem",
+ "defineSystemSet",
+ "Time"
+ ]
+ },
+ {
+ "id": "transform",
+ "title": "Transform & hierarchy",
+ "titleZh": "变换与层级",
+ "tier": "public",
+ "entry": [
+ "Transform",
+ "Parent",
+ "Children",
+ "Name"
+ ]
+ },
+ {
+ "id": "drawing",
+ "title": "Sprites & text",
+ "titleZh": "精灵与文本",
+ "tier": "public",
+ "entry": [
+ "Sprite",
+ "Text",
+ "TextAlign"
+ ]
+ },
+ {
+ "id": "input",
+ "title": "Input actions",
+ "titleZh": "输入动作",
+ "tier": "public",
+ "why": "the action and binding vocabulary is frozen; the raw per-frame state under it is Beta — see InputState",
+ "whyZh": "动作与绑定的词汇表已冻结;它下面的每帧原始状态是 Beta —— 见 InputState",
+ "entry": [
+ "defineInputMap",
+ "Button",
+ "Axis1D",
+ "Axis2D",
+ "Key",
+ "GpButton",
+ "Stick"
+ ]
+ },
+ {
+ "id": "layout-units",
+ "title": "Layout units",
+ "titleZh": "布局单位",
+ "tier": "public",
+ "entry": [
+ "px",
+ "percent",
+ "Dimension"
+ ]
+ },
+ {
+ "id": "input-raw",
+ "title": "Raw input state",
+ "titleZh": "原始输入状态",
+ "tier": "beta",
+ "why": "per-frame touch state is reachable only as raw collections, with no accessor for started/ended and no write door — freezing it would freeze both gaps",
+ "whyZh": "每帧触摸状态只能通过原始集合拿到,started/ended 没有访问器,也没有写入门 —— 冻结它等于把这两个缺口一起冻进去",
+ "entry": [
+ "Input",
+ "InputState",
+ "TouchPoint"
+ ]
+ },
+ {
+ "id": "ui",
+ "title": "UI",
+ "titleZh": "UI",
+ "tier": "beta",
+ "why": "thirty-three of a hundred and fifteen UI symbols reach a certified game, and the newest part of the surface is the part a creator meets first — anchors, insets, theme tokens",
+ "whyZh": "115 个 UI 符号里只有 33 个到得了被认证的游戏,而这套面最新的部分恰恰是创作者最先碰的:锚点、inset、主题 token",
+ "entry": [
+ "UINode",
+ "UIVisual",
+ "spawnUIEntity",
+ "themeColors",
+ "UICameraInfo"
+ ]
+ },
+ {
+ "id": "scene",
+ "title": "Scenes",
+ "titleZh": "场景",
+ "tier": "beta",
+ "why": "one certified project drives scenes at all, against twenty-six SceneManagerState signatures",
+ "whyZh": "只有一个被认证的项目在驱动场景,而 SceneManagerState 有 26 个签名",
+ "entry": [
+ "SceneManager",
+ "SceneManagerState",
+ "SceneConfig",
+ "SceneContext",
+ "transitionTo"
+ ]
+ },
+ {
+ "id": "prefab",
+ "title": "Prefabs",
+ "titleZh": "预制体",
+ "tier": "beta",
+ "why": "instantiate has not moved, but its result and override shapes are the on-disk format's, so the names settled ahead of the shapes",
+ "whyZh": "instantiate 没有动过,但它的结果和覆盖形状属于磁盘格式,所以名字比形状先定下来",
+ "entry": [
+ "Prefabs",
+ "PrefabServer",
+ "SpawnOverride"
+ ]
+ },
+ {
+ "id": "assets",
+ "title": "Assets",
+ "titleZh": "资产",
+ "tier": "beta",
+ "why": "one certified project takes Res(Assets), for four of its members, and the host wiring — resolvers, registries, the manifest, device-loss recovery — has to leave the game-facing surface first",
+ "whyZh": "只有一个被认证的项目用 Res(Assets),且只用了 4 个成员;而宿主接线(resolver、registry、manifest、设备丢失恢复)必须先离开面向游戏的这一面",
+ "entry": [
+ "Assets",
+ "AssetsData"
+ ]
+ },
+ {
+ "id": "physics",
+ "title": "Physics",
+ "titleZh": "物理",
+ "tier": "beta",
+ "why": "the corpus reaches three of thirty-seven physics symbols",
+ "whyZh": "语料只触到 37 个物理符号里的 3 个",
+ "entry": [
+ "Physics",
+ "PhysicsEvents",
+ "CharacterController"
+ ]
+ },
+ {
+ "id": "camera",
+ "title": "Camera",
+ "titleZh": "相机",
+ "tier": "beta",
+ "why": "clearFlags is a bitmask whose C++ enum has no TypeScript spelling, and cullingMask names layers no exported constant identifies — two fields typed `number` for want of the vocabulary",
+ "whyZh": "clearFlags 是位掩码,而它的 C++ enum 在 TypeScript 侧没有拼写;cullingMask 指的图层没有任何导出常量能标识 —— 两个字段被打成 number 是因为缺词汇",
+ "entry": [
+ "Camera",
+ "CameraData"
+ ]
+ },
+ {
+ "id": "spine",
+ "title": "Spine",
+ "titleZh": "Spine",
+ "tier": "beta",
+ "why": "one certified project plays a skeleton; the runtime is a side module a project opts into",
+ "whyZh": "只有一个被认证的项目在播骨骼;运行时是项目自行选用的 side module",
+ "entry": [
+ "Spine",
+ "SpineAnimation"
+ ]
+ },
+ {
+ "id": "audio",
+ "title": "Audio",
+ "titleZh": "音频",
+ "tier": "experimental",
+ "why": "NO example in the repository uses audio, so nothing would notice a break in it. Beta would claim a support we cannot give until something certifies it",
+ "whyZh": "仓库里没有任何一个例子用音频,所以它坏了不会有人发现。在有东西认证它之前,Beta 会是一个我们给不出的支持承诺",
+ "entry": [
+ "Audio",
+ "AudioSource",
+ "AudioListener"
+ ]
+ },
+ {
+ "id": "animation",
+ "title": "Animation & timeline",
+ "titleZh": "动画与时间轴",
+ "tier": "experimental",
+ "why": "sprite-animation and cutscene exercise it and neither is in the certification corpus",
+ "whyZh": "sprite-animation 和 cutscene 在用它,而这两个都不在认证语料里",
+ "entry": [
+ "Animator",
+ "SpriteAnimator"
+ ]
+ },
+ {
+ "id": "tilemap",
+ "title": "Tilemap",
+ "titleZh": "瓦片地图",
+ "tier": "experimental",
+ "why": "certified end to end by two games, but the runtime surface has not been read for a tier yet",
+ "whyZh": "有两个游戏端到端认证了它,但它的运行时面还没有被拿来定级",
+ "entry": [
+ "TilemapLayer"
+ ]
+ },
+ {
+ "id": "particles",
+ "title": "Particles",
+ "titleZh": "粒子",
+ "tier": "experimental",
+ "why": "as tilemap — exercised by a certified game, not yet read for a tier",
+ "whyZh": "同瓦片地图 —— 有被认证的游戏在用,但还没被拿来定级",
+ "entry": [
+ "ParticleEmitter"
+ ]
+ },
+ {
+ "id": "video",
+ "title": "Video",
+ "titleZh": "视频",
+ "tier": "experimental",
+ "why": "the platform paths differ enough that the surface is still converging",
+ "whyZh": "各平台路径差异仍大,这套面还在收敛",
+ "entry": [
+ "Video"
+ ]
+ },
+ {
+ "id": "ai",
+ "title": "AI — navigation, FSM, behaviour trees",
+ "titleZh": "AI —— 导航、状态机、行为树",
+ "tier": "experimental",
+ "why": "deliberately after the rest: 0.50 freezes what a game is built OUT of, and the layers built ON that come once those are settled",
+ "whyZh": "刻意排在后面:0.50 冻的是「一个游戏由什么构成」,建立在其上的层要等下面这些定下来",
+ "entry": [
+ "Nav",
+ "NavAgent",
+ "StateMachineAgent",
+ "BehaviorTreeAgent",
+ "Perception"
+ ]
+ },
+ {
+ "id": "networking",
+ "title": "Networking & replication",
+ "titleZh": "网络与状态复制",
+ "tier": "experimental",
+ "why": "as AI — the high-level layer waits on the layers under it",
+ "whyZh": "同 AI —— 高层要等它下面的层",
+ "entry": [
+ "Net",
+ "Replicated"
+ ]
+ },
+ {
+ "id": "rendering",
+ "title": "Materials, lighting, post-processing",
+ "titleZh": "材质、光照、后处理",
+ "tier": "experimental",
+ "why": "as AI — and the render graph behind it is still moving",
+ "whyZh": "同 AI —— 而且它背后的 render graph 还在动",
+ "entry": [
+ "Material",
+ "Light2D",
+ "PostProcessStack"
+ ]
+ }
+ ],
"public": [
{
"name": "ActionDef",
diff --git a/tools/api-stability.mjs b/tools/api-stability.mjs
index 3e3d25a39..a07b88b4b 100644
--- a/tools/api-stability.mjs
+++ b/tools/api-stability.mjs
@@ -16,6 +16,7 @@ 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');
@@ -56,6 +57,10 @@ function build() {
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';
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
new file mode 100644
index 000000000..63b0c606a
--- /dev/null
+++ b/tools/apiSubsystems.mjs
@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file apiSubsystems.mjs — the tier of each part of Estella, at the size a
+ * creator thinks in.
+ *
+ * The per-symbol tiers answer "is `AudioSource` frozen". Nobody asks that. They
+ * ask "can I build my game's audio on this", and 1462 experimental symbols answer
+ * it the same way whether somebody weighed the subsystem or nobody looked at it —
+ * which is the exact ambiguity this release removed one level down.
+ *
+ * So each subsystem carries a verdict and the reason for it. `entry` is what
+ * carries the verdict in code: the gate reads their tags out of the snapshots and
+ * refuses a table that disagrees with them, so this cannot become a second answer.
+ */
+
+/**
+ * `tier` is the promise; `why` says what decided it, and is required for anything
+ * not frozen — "not frozen" is a decision and has to read like one. Both are
+ * published, so both carry a `*Zh`: the Chinese page renders Chinese or it is not
+ * a Chinese page.
+ */
+export const SUBSYSTEMS = [
+ {
+ id: 'ecs',
+ title: 'ECS',
+ titleZh: 'ECS',
+ tier: 'public',
+ entry: ['defineComponent', 'defineSystem', 'Query', 'Mut', 'Res', 'Commands', 'World'],
+ },
+ {
+ id: 'app-lifecycle',
+ title: 'App lifecycle',
+ titleZh: '应用生命周期',
+ tier: 'public',
+ entry: ['Schedule', 'addSystemToSchedule', 'addStartupSystem', 'defineSystemSet', 'Time'],
+ },
+ {
+ id: 'transform',
+ title: 'Transform & hierarchy',
+ titleZh: '变换与层级',
+ tier: 'public',
+ entry: ['Transform', 'Parent', 'Children', 'Name'],
+ },
+ {
+ id: 'drawing',
+ title: 'Sprites & text',
+ titleZh: '精灵与文本',
+ tier: 'public',
+ entry: ['Sprite', 'Text', 'TextAlign'],
+ },
+ {
+ id: 'input',
+ title: 'Input actions',
+ titleZh: '输入动作',
+ tier: 'public',
+ why: 'the action and binding vocabulary is frozen; the raw per-frame state under it is Beta — see InputState',
+ whyZh: '动作与绑定的词汇表已冻结;它下面的每帧原始状态是 Beta —— 见 InputState',
+ entry: ['defineInputMap', 'Button', 'Axis1D', 'Axis2D', 'Key', 'GpButton', 'Stick'],
+ },
+ {
+ id: 'layout-units',
+ title: 'Layout units',
+ titleZh: '布局单位',
+ tier: 'public',
+ entry: ['px', 'percent', 'Dimension'],
+ },
+ {
+ id: 'input-raw',
+ title: 'Raw input state',
+ titleZh: '原始输入状态',
+ tier: 'beta',
+ why: 'per-frame touch state is reachable only as raw collections, with no accessor for started/ended and no write door — freezing it would freeze both gaps',
+ whyZh: '每帧触摸状态只能通过原始集合拿到,started/ended 没有访问器,也没有写入门 —— 冻结它等于把这两个缺口一起冻进去',
+ entry: ['Input', 'InputState', 'TouchPoint'],
+ },
+ {
+ id: 'ui',
+ title: 'UI',
+ titleZh: 'UI',
+ tier: 'beta',
+ why: 'thirty-three of a hundred and fifteen UI symbols reach a certified game, and the newest part of the surface is the part a creator meets first — anchors, insets, theme tokens',
+ whyZh: '115 个 UI 符号里只有 33 个到得了被认证的游戏,而这套面最新的部分恰恰是创作者最先碰的:锚点、inset、主题 token',
+ entry: ['UINode', 'UIVisual', 'spawnUIEntity', 'themeColors', 'UICameraInfo'],
+ },
+ {
+ id: 'scene',
+ title: 'Scenes',
+ titleZh: '场景',
+ tier: 'beta',
+ why: 'one certified project drives scenes at all, against twenty-six SceneManagerState signatures',
+ whyZh: '只有一个被认证的项目在驱动场景,而 SceneManagerState 有 26 个签名',
+ entry: ['SceneManager', 'SceneManagerState', 'SceneConfig', 'SceneContext', 'transitionTo'],
+ },
+ {
+ id: 'prefab',
+ title: 'Prefabs',
+ titleZh: '预制体',
+ tier: 'beta',
+ why: 'instantiate has not moved, but its result and override shapes are the on-disk format\'s, so the names settled ahead of the shapes',
+ whyZh: 'instantiate 没有动过,但它的结果和覆盖形状属于磁盘格式,所以名字比形状先定下来',
+ entry: ['Prefabs', 'PrefabServer', 'SpawnOverride'],
+ },
+ {
+ id: 'assets',
+ title: 'Assets',
+ titleZh: '资产',
+ tier: 'beta',
+ why: 'one certified project takes Res(Assets), for four of its members, and the host wiring — resolvers, registries, the manifest, device-loss recovery — has to leave the game-facing surface first',
+ whyZh: '只有一个被认证的项目用 Res(Assets),且只用了 4 个成员;而宿主接线(resolver、registry、manifest、设备丢失恢复)必须先离开面向游戏的这一面',
+ entry: ['Assets', 'AssetsData'],
+ },
+ {
+ id: 'physics',
+ title: 'Physics',
+ titleZh: '物理',
+ tier: 'beta',
+ why: 'the corpus reaches three of thirty-seven physics symbols',
+ whyZh: '语料只触到 37 个物理符号里的 3 个',
+ entry: ['Physics', 'PhysicsEvents', 'CharacterController'],
+ },
+ {
+ id: 'camera',
+ title: 'Camera',
+ titleZh: '相机',
+ tier: 'beta',
+ why: 'clearFlags is a bitmask whose C++ enum has no TypeScript spelling, and cullingMask names layers no exported constant identifies — two fields typed `number` for want of the vocabulary',
+ whyZh: 'clearFlags 是位掩码,而它的 C++ enum 在 TypeScript 侧没有拼写;cullingMask 指的图层没有任何导出常量能标识 —— 两个字段被打成 number 是因为缺词汇',
+ entry: ['Camera', 'CameraData'],
+ },
+ {
+ id: 'spine',
+ title: 'Spine',
+ titleZh: 'Spine',
+ tier: 'beta',
+ why: 'one certified project plays a skeleton; the runtime is a side module a project opts into',
+ whyZh: '只有一个被认证的项目在播骨骼;运行时是项目自行选用的 side module',
+ entry: ['Spine', 'SpineAnimation'],
+ },
+ {
+ id: 'audio',
+ title: 'Audio',
+ titleZh: '音频',
+ tier: 'experimental',
+ why: 'NO example in the repository uses audio, so nothing would notice a break in it. Beta would claim a support we cannot give until something certifies it',
+ whyZh: '仓库里没有任何一个例子用音频,所以它坏了不会有人发现。在有东西认证它之前,Beta 会是一个我们给不出的支持承诺',
+ entry: ['Audio', 'AudioSource', 'AudioListener'],
+ },
+ {
+ id: 'animation',
+ title: 'Animation & timeline',
+ titleZh: '动画与时间轴',
+ tier: 'experimental',
+ why: 'sprite-animation and cutscene exercise it and neither is in the certification corpus',
+ whyZh: 'sprite-animation 和 cutscene 在用它,而这两个都不在认证语料里',
+ entry: ['Animator', 'SpriteAnimator'],
+ },
+ {
+ id: 'tilemap',
+ title: 'Tilemap',
+ titleZh: '瓦片地图',
+ tier: 'experimental',
+ why: 'certified end to end by two games, but the runtime surface has not been read for a tier yet',
+ whyZh: '有两个游戏端到端认证了它,但它的运行时面还没有被拿来定级',
+ entry: ['TilemapLayer'],
+ },
+ {
+ id: 'particles',
+ title: 'Particles',
+ titleZh: '粒子',
+ tier: 'experimental',
+ why: 'as tilemap — exercised by a certified game, not yet read for a tier',
+ whyZh: '同瓦片地图 —— 有被认证的游戏在用,但还没被拿来定级',
+ entry: ['ParticleEmitter'],
+ },
+ {
+ id: 'video',
+ title: 'Video',
+ titleZh: '视频',
+ tier: 'experimental',
+ why: 'the platform paths differ enough that the surface is still converging',
+ whyZh: '各平台路径差异仍大,这套面还在收敛',
+ entry: ['Video'],
+ },
+ {
+ id: 'ai',
+ title: 'AI — navigation, FSM, behaviour trees',
+ titleZh: 'AI —— 导航、状态机、行为树',
+ tier: 'experimental',
+ why: 'deliberately after the rest: 0.50 freezes what a game is built OUT of, and the layers built ON that come once those are settled',
+ whyZh: '刻意排在后面:0.50 冻的是「一个游戏由什么构成」,建立在其上的层要等下面这些定下来',
+ entry: ['Nav', 'NavAgent', 'StateMachineAgent', 'BehaviorTreeAgent', 'Perception'],
+ },
+ {
+ id: 'networking',
+ title: 'Networking & replication',
+ titleZh: '网络与状态复制',
+ tier: 'experimental',
+ why: 'as AI — the high-level layer waits on the layers under it',
+ whyZh: '同 AI —— 高层要等它下面的层',
+ entry: ['Net', 'Replicated'],
+ },
+ {
+ id: 'rendering',
+ title: 'Materials, lighting, post-processing',
+ titleZh: '材质、光照、后处理',
+ tier: 'experimental',
+ why: 'as AI — and the render graph behind it is still moving',
+ whyZh: '同 AI —— 而且它背后的 render graph 还在动',
+ entry: ['Material', 'Light2D', 'PostProcessStack'],
+ },
+];
diff --git a/tools/check-subsystem-tiers.mjs b/tools/check-subsystem-tiers.mjs
new file mode 100644
index 000000000..7fb7854ca
--- /dev/null
+++ b/tools/check-subsystem-tiers.mjs
@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-subsystem-tiers.mjs — the published verdict per subsystem is the
+ * one the code carries.
+ *
+ * A table of what is safe to build on is worth having and worth nothing if it can
+ * drift: the moment a symbol's tag moves and the table does not, the table is the
+ * confident wrong answer a creator reads instead of the right one nobody surfaces.
+ *
+ * So every subsystem's `entry` symbols are looked up in the snapshots and must
+ * carry the tier it claims — and each must still be an exported symbol, because a
+ * verdict resting on a name that no longer exists rests on nothing.
+ *
+ * node tools/check-subsystem-tiers.mjs
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ETC, ENTRIES } from './lib/sdkProgram.mjs';
+import { parseSnapshot, TIERS } from './lib/apiSnapshot.mjs';
+import { SUBSYSTEMS } from './apiSubsystems.mjs';
+
+/** Every symbol across every entry, keeping the strongest tier any entry gives it. */
+function surface() {
+ const rank = Object.fromEntries(TIERS.map((t, i) => [t, i]));
+ const out = 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 = out.get(name);
+ if (!seen) { out.set(name, s.tier); continue; }
+ if ((rank[s.tier] ?? 9) < (rank[seen] ?? 9)) out.set(name, s.tier);
+ }
+ }
+ return out;
+}
+
+const api = surface();
+const problems = [];
+const seen = new Set();
+
+for (const sub of SUBSYSTEMS) {
+ if (seen.has(sub.id)) problems.push(`"${sub.id}" is listed twice`);
+ seen.add(sub.id);
+ if (!sub.title || !sub.titleZh) {
+ problems.push(`"${sub.id}" is missing a title in one locale — half a translation is English leaking onto the Chinese page`);
+ }
+ if (!TIERS.includes(sub.tier)) {
+ problems.push(`"${sub.id}" claims tier "${sub.tier}" (have: ${TIERS.join(', ')})`);
+ continue;
+ }
+ // Frozen speaks for itself; anything else is a decision, and a decision with
+ // no reason beside it reads as an oversight — which is the whole disease.
+ if (sub.tier !== 'public' && !(sub.why?.trim() && sub.whyZh?.trim())) {
+ problems.push(`"${sub.id}" is ${sub.tier} without a reason in both locales — say what decided it, twice`);
+ }
+ if (!sub.entry?.length) {
+ problems.push(`"${sub.id}" names no entry symbols — then nothing in the code carries its verdict`);
+ continue;
+ }
+ for (const name of sub.entry) {
+ const tier = api.get(name);
+ if (!tier) problems.push(`"${sub.id}" rests on "${name}", which no entry exports`);
+ else if (tier !== sub.tier) {
+ problems.push(`"${sub.id}" is published as ${sub.tier} but "${name}" is @${tier}`);
+ }
+ }
+}
+
+if (problems.length) {
+ console.error('check-subsystem-tiers: the published verdicts and the tags disagree.\n');
+ for (const p of problems) console.error(` ${p}`);
+ console.error('\nMove the tag, or move the verdict — but they are one answer.');
+ process.exit(1);
+}
+
+const by = (t) => SUBSYSTEMS.filter((s) => s.tier === t).length;
+console.log(`check-subsystem-tiers: ${SUBSYSTEMS.length} subsystem(s) — `
+ + `${by('public')} frozen, ${by('beta')} beta, ${by('experimental')} experimental, each backed by its tags.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 2179d5243..dd7ae3efd 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -74,6 +74,9 @@ export const GATES = [
{ 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' },
+ // The per-symbol tiers say what is frozen; this says what a creator can build
+ // on, and refuses a published verdict the tags do not carry.
+ { id: 'subsystem-tiers', run: 'node tools/check-subsystem-tiers.mjs' },
{ id: 'examples', run: 'node build-tools/cli.js check-examples' },
{ id: 'prefabs', run: 'node build-tools/cli.js validate-prefabs' },
];
diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjs
index bca7d70f4..5d3b6e9eb 100644
--- a/tools/releaseGate.mjs
+++ b/tools/releaseGate.mjs
@@ -187,6 +187,15 @@ export const CRITERIA = [
answeredBy: 'node tools/check-plugin-api-contract.mjs',
needs: ['tools/check-plugin-api-contract.mjs', 'desktop/src/plugins/types.ts'],
},
+ {
+ id: 'every-subsystem-has-a-verdict',
+ says: 'every part of the engine publishes a tier at the size a creator builds in, and the tags carry it',
+ // The per-symbol tiers are enforced above. This is the same answer at the
+ // size somebody actually asks it: 1462 experimental symbols read the same
+ // whether a subsystem was weighed or nobody looked.
+ answeredBy: 'node tools/check-subsystem-tiers.mjs',
+ needs: ['tools/apiSubsystems.mjs', 'tools/check-subsystem-tiers.mjs'],
+ },
{
id: 'creator-can-say-what-is-safe',
says: 'the docs name the four tiers and which APIs are in each, in both languages',