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
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.astroindex 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.jsonindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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',