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(plugins): the editor plugin API answers which side of 1.0 it is on
esengine3657d9dde930
diff --git a/VERSIONING.md b/VERSIONING.mdindex eea05480e..2b2dc803d 100644--- a/VERSIONING.md+++ b/VERSIONING.md@@ -36,6 +36,47 @@ release: internal C++ headers under `src/`, unexported SDK internals, editorinternals, the embedded origin signatures (see [PROVENANCE.md](PROVENANCE.md)),private fields, and anything marked `@internal` or `@experimental`.+## The Editor Plugin API++The editor's plugin API — `@estella/editor-api`, the shapes in+`desktop/src/plugins/types.ts` that the editor writes into your project as+`.esengine/plugins/.types/editor-api.d.ts` — is **not** one of the four surfaces+above. It is **experimental**, and it is not covered by the MAJOR-line promise:+it will keep changing after 1.0.++This is a decision, not an omission. Three reasons:++- **The extension points are still converging.** The design is that a plugin+ registers through the same registries the editor's own features use, with one+ ownership mechanism behind all of them. Finishing that convergence changes the+ shape of contribution points, and freezing now would freeze the half-converged+ spelling.+- **The trust model is pre-isolation.** A plugin runs as trusted code inside the+ editor's renderer, at the same privilege as your project's game code. A real+ third-party ecosystem needs process isolation, and isolation makes an API+ asynchronous — so freezing today's synchronous surface would be promising the+ shape that has to change.+- **Nothing holds it up.** A symbol reaches `@public` in the SDK only once a game+ we certify releases against calls it. No shipped plugin exercises these shapes,+ so there is no evidence pinning them, and a promise with nothing holding it is+ the kind that gets broken by the first refactor.++What you **can** rely on while it is experimental:++- **`engines.editor` is honoured.** A plugin declares the editor range it works+ with, and one outside that range is refused with a stated reason rather than+ half-loaded. A breaking change therefore costs a plugin author a version bump —+ never a user a broken editor.+- **Breaking changes are written down.** Every one appears in the CHANGELOG under+ an **Editor plugin API** heading, with what to change.+- **Removal is deprecated first.** A contribution point being withdrawn keeps+ working, and says so, for at least one MINOR release.++The route out of experimental is the same bar the SDK uses: a contribution point+earns a compatibility promise once a shipped plugin exercises it. Parts of this+surface will be frozen that way, individually, rather than the whole of it at+once by a version number.+## Stability tiersSurface 1 is large, and not all of it is equally settled. Every exported symboldiff --git a/desktop/src/plugins/types.ts b/desktop/src/plugins/types.tsindex 87f1ee75d..e361291ac 100644--- a/desktop/src/plugins/types.ts+++ b/desktop/src/plugins/types.ts@@ -14,6 +14,26 @@* particular exposes the model write door (undoable, transactional) and omits the* verification/headless machinery on the internal control surface, which plugins* have no business driving.+ *+ * ---------------------------------------------------------------------------+ * STABILITY: EXPERIMENTAL — this surface is NOT part of Estella's 1.x+ * compatibility contract, and will keep changing after 1.0. See the+ * "Editor Plugin API" section of VERSIONING.md for the whole policy.+ *+ * What you can rely on instead:+ * - `engines.editor` is honoured. A plugin outside its declared range is+ * refused with a reason and never half-loaded, so a change here costs you a+ * version bump — never a user a broken editor.+ * - Every breaking change is in the CHANGELOG under "Editor plugin API",+ * with what to change.+ * - A contribution point is deprecated for one MINOR before it is removed.+ *+ * Why it is not frozen: the contribution registries are still converging onto+ * one ownership mechanism; a plugin runs as TRUSTED code in the editor's+ * renderer, and the isolation a third-party ecosystem needs would make this API+ * asynchronous; and no shipped plugin yet holds any of these shapes up, which is+ * the same evidence the SDK requires before it freezes anything.+ * ---------------------------------------------------------------------------*//** A human string a plugin supplies, per locale (falling back to `en`). */diff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdxindex ba8eba895..0f489a190 100644--- a/docs/astro/src/content/docs/extending/editor-plugins.mdx+++ b/docs/astro/src/content/docs/extending/editor-plugins.mdx@@ -80,6 +80,29 @@ plugin pins it to the editor doing the creating, so copying an older range in frsomewhere else is how a plugin arrives already marked *incompatible*.</Aside>+## What this API promises++The plugin API is **experimental**, and it is not part of Estella's 1.x+compatibility contract — it will keep changing after 1.0. That is a decision, and+[VERSIONING.md](https://github.com/esengine/estella/blob/master/VERSIONING.md)+states it alongside the SDK's own [stability tiers](/docs/reference/api-stability/):+the extension points are still converging on one mechanism, a plugin runs as+trusted code in the editor's renderer rather than in isolation, and no shipped+plugin yet holds any of these shapes up.++Three things you can rely on while that is true:++- **`engines.editor` is honoured.** A plugin outside its declared range is refused+ with a stated reason and never half-loaded, so a change on our side costs you a+ version bump — never a user a broken editor.+- **Breaking changes are written down**, in the CHANGELOG under **Editor plugin+ API**, with what to change.+- **Removal is deprecated first** — a contribution point being withdrawn keeps+ working, and says so, for at least one minor release.++Parts of this surface will be frozen individually, as shipped plugins come to+exercise them, rather than all at once by a version number.+## Seeing what a plugin contributedEvery running plugin has a **Contributes** row in the Plugins panel. Expand it fordiff --git a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdxindex 21ec35957..32809bc29 100644--- a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx+++ b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx@@ -72,6 +72,26 @@ export default definePlugin({所以从别处抄一个旧区间过来,插件一装上就是"版本不兼容"。</Aside>+## 这套 API 承诺什么++插件 API 是 **experimental(实验性)**,**不在** Estella 1.x 的兼容契约里——1.0+之后它还会继续变。这是一个明确的裁定,+[VERSIONING.md](https://github.com/esengine/estella/blob/master/VERSIONING.md)+和 SDK 自己的[稳定性等级](/docs/zh-cn/reference/api-stability/)写在一处:贡献点还在向+同一套机制收敛;插件是跑在编辑器渲染进程里的**受信代码**而非隔离沙箱;而且还没有+任何已发布的插件在撑住这些形状。++在这个前提下,有三件事你可以依赖:++- **`engines.editor` 一定被尊重。** 超出声明区间的插件会带着理由被拒绝加载,绝不+ 半加载。所以我们这边的变更,代价是你升一个版本号——绝不会是用户的编辑器坏掉。+- **破坏性变更一定写下来**,在 CHANGELOG 的 **Editor plugin API** 标题下,连同该+ 怎么改。+- **移除一定先弃用**——要撤掉的贡献点至少还能用一个次版本,并且会说明。++这套面会**逐个**冻结——随着真有已发布的插件在用它们——而不是靠一个版本号一次性+全冻。+## 看插件贡献了什么插件面板里每个运行中的插件都有一条**贡献**,展开就是它此刻注册的全部东西——diff --git a/tools/check-comment-style.mjs b/tools/check-comment-style.mjsindex e7f33f0b1..332e5b919 100644--- a/tools/check-comment-style.mjs+++ b/tools/check-comment-style.mjs@@ -115,6 +115,33 @@ const NOT_PROSE = /^\s*(\/\*+\s*$|\*\/|\/\/\s*[=-]+\s*$|\*\s*$|\/\/\s*$)|@(param/** A Doxygen file header states why the file exists; that is its job. */const FILE_HEADER = /@file\b/;+const headerSpanCache = new Map();++/**+ * Whether a line falls inside the file's `@file` header. Reading the diff means a+ * paragraph added to the MIDDLE of a header arrives without the `@file` line, so+ * the exemption has to be looked up on disk or the header's own budget is charged+ * to whoever edits it.+ */+function insideFileHeader(file, line) {+ if (!headerSpanCache.has(file)) {+ let span = null;+ try {+ const lines = readFileSync(path.join(ROOT, file), 'utf8').split('\n');+ const open = lines.findIndex((t) => /^\s*\/\*\*/.test(t));+ if (open >= 0) {+ const close = lines.findIndex((t, i) => i >= open && /\*\//.test(t));+ if (close >= 0 && lines.slice(open, close + 1).some((t) => FILE_HEADER.test(t))) {+ span = [open + 1, close + 1];+ }+ }+ } catch { /* vanished, or unreadable — no exemption */ }+ headerSpanCache.set(file, span);+ }+ const span = headerSpanCache.get(file);+ return span !== null && line >= span[0] && line <= span[1];+}+function scan(byFile) {const findings = [];for (const [file, lines] of byFile) {@@ -123,7 +150,8 @@ function scan(byFile) {const flushBlock = () => {if (block.length === 0) return;const prose = block.filter(([, t]) => !NOT_PROSE.test(t));- const isHeader = block.some(([, t]) => FILE_HEADER.test(t));+ const isHeader = block.some(([, t]) => FILE_HEADER.test(t))+ || insideFileHeader(file, block[0][0]);// A block edited inside an existing `/** */` shows up in the diff without its// opener, so a run of ` * ` continuation lines counts as a doc block too.const isDoc = block.some(([, t]) => /^\s*\/\*\*/.test(t))diff --git a/tools/check-plugin-api-contract.mjs b/tools/check-plugin-api-contract.mjsnew file mode 100644index 000000000..f876957da--- /dev/null+++ b/tools/check-plugin-api-contract.mjs@@ -0,0 +1,167 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-plugin-api-contract.mjs — the editor plugin API says what it is.+ *+ * The worst state for an extension API is not "unstable" — it is unstated: authors+ * read it as settled, maintainers treat it as internal, and neither finds out+ * until something breaks. 0.50 settles the question the other way (experimental,+ * outside the 1.x contract) and this is what stops that answer from decaying.+ *+ * A verdict decays in one of two ways, so both are checked. It can go MISSING from+ * somewhere a reader looks: the shipped `.d.ts`, the policy, or the docs — three+ * audiences, and a promise absent from one of them is not made. Or it can go+ * INCONSISTENT: the promises the shipped typings offer drift from the ones the+ * policy commits to, which is worse than silence because both look authoritative.+ *+ * So {@link PROMISES} is the one list, and each entry must be findable in all+ * three places.+ *+ * node tools/check-plugin-api-contract.mjs+ */+import { readFileSync } from 'node:fs';+import { join, dirname, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');++/**+ * Where the verdict has to hold, who reads each one, and the passage it has to+ * hold IN. Scoping is load-bearing: VERSIONING.md already promises "at least one+ * MINOR release" about the SDK, so a whole-file search reads the plugin promise as+ * kept by prose about something else.+ */+const SURFACES = {+ typings: {+ path: 'desktop/src/plugins/types.ts',+ who: 'the plugin author, in the .d.ts the editor writes into their project',+ from: /^ \* STABILITY:/m,+ to: /^ \*\/$/m,+ },+ policy: {+ path: 'VERSIONING.md',+ who: 'anyone deciding whether to build on this',+ from: /^## The Editor Plugin API$/m,+ to: /^## /m,+ },+ docs: {+ path: 'docs/astro/src/content/docs/extending/editor-plugins.mdx',+ who: 'a reader of the guide',+ from: /^## What this API promises$/m,+ to: /^## /m,+ },+ docsZh: {+ path: 'docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx',+ who: 'a reader of the Chinese guide',+ from: /^## 这套 API 承诺什么$/m,+ to: /^## /m,+ },+};++/**+ * The verdict itself. Two claims, not one: that the tier is experimental, and+ * that this is what places it outside the compatibility contract — a document+ * saying only the first leaves the second to be assumed either way.+ */+const VERDICT = [+ { id: 'tier', of: { typings: /STABILITY: EXPERIMENTAL/, policy: /\*\*experimental\*\*/i, docs: /\*\*experimental((实验性))?\*\*/i } },+ {+ id: 'outside-the-contract',+ of: {+ typings: /NOT part of Estella's 1\.x\s+\*?\s*compatibility contract/,+ policy: /not covered by the MAJOR-line promise/,+ docs: /(not part of Estella's 1\.x|Estella 1\.x 的兼容契约)/,+ },+ },+];++/**+ * What is promised in exchange. Each is a real, cheap-to-keep commitment, and+ * each must reach all three audiences — an author who never learns that+ * `engines.editor` protects them reads "experimental" as "unusable".+ */+const PROMISES = [+ {+ id: 'engines-range-honoured',+ says: 'a plugin outside its declared engines.editor range is refused, never half-loaded',+ of: { typings: /engines\.editor/, policy: /`engines\.editor` is honoured/, docs: /engines\.editor/ },+ },+ {+ id: 'breaking-changes-recorded',+ says: 'every breaking change is in the CHANGELOG under an Editor plugin API heading',+ of: { typings: /CHANGELOG under "Editor plugin API"/, policy: /\*\*Editor plugin API\*\* heading/, docs: /Editor plugin\s+\*?\s*API\*?\*?/ },+ },+ {+ id: 'removal-deprecates-first',+ says: 'a contribution point is deprecated for one MINOR before removal',+ of: { typings: /deprecated for one MINOR/, policy: /at least one MINOR release/, docs: /(one minor release|一个次版本)/ },+ },+];++/** A surface's whole text, and just the passage the claims must be made in. */+const whole = {};+const passage = {};+for (const [key, s] of Object.entries(SURFACES)) {+ const text = readFileSync(join(ROOT, s.path), 'utf8').replace(/\r\n?/g, '\n');+ whole[key] = text;+ const start = s.from.exec(text);+ if (!start) { passage[key] = ''; continue; }+ // `to` is sought after the marker, so a heading cannot end its own section;+ // the marker itself is then kept, since it carries the claim in the typings.+ const after = text.slice(start.index + start[0].length);+ const end = s.to.exec(after);+ passage[key] = start[0] + (end ? after.slice(0, end.index) : after);+}++/** Both locales read as `docs`: a claim made in one language only is not published. */+const LOCALES = { docs: ['docs', 'docsZh'] };+const audiences = (surface) => LOCALES[surface] ?? [surface];++const failures = [];++for (const [kind, claims] of [['verdict', VERDICT], ['promise', PROMISES]]) {+ for (const claim of claims) {+ for (const [surface, pattern] of Object.entries(claim.of)) {+ for (const where of audiences(surface)) {+ if (pattern.test(passage[where])) continue;+ failures.push(`${kind} '${claim.id}' is not stated in ${SURFACES[where].path}`+ + `\n ${SURFACES[where].who} would not learn it${claim.says ? ` — ${claim.says}` : ''}`);+ }+ }+ }+}++/**+ * The typings ship as TEXT, copied verbatim into the author's project. An import+ * would resolve in our tree and dangle in theirs, so the file being import-free+ * is load-bearing rather than a style preference.+ */+const imports = whole.typings.split('\n')+ .map((l, i) => [i + 1, l])+ .filter(([, l]) => /^\s*(import\b|export\s+(\*|\{[^}]*\})\s+from\b)/.test(l));+for (const [line, l] of imports) {+ failures.push(`${SURFACES.typings.path}:${line} imports — the file ships verbatim as the author's .d.ts, so it must stay self-contained`+ + `\n ${l.trim()}`);+}++/**+ * `@public` here would be a freeze nothing enforces: the SDK's tiers are backed+ * by a snapshot, a baseline and the freeze bar, and none of those look at this+ * file. Freezing part of this surface means giving it that machinery first.+ */+for (const [i, l] of whole.typings.split('\n').entries()) {+ if (/^\s*\*\s*@public\b/.test(l)) {+ failures.push(`${SURFACES.typings.path}:${i + 1} claims @public — this surface is experimental, and no baseline guard reads this file`);+ }+}++if (failures.length === 0) {+ console.log(`check-plugin-api-contract: the verdict and ${PROMISES.length} promise(s) hold in all ${Object.keys(SURFACES).length} places.`);+ process.exit(0);+}++for (const f of failures) console.error(` ${f}`);+console.error(`\ncheck-plugin-api-contract: ${failures.length} finding(s).`);+console.error('The editor plugin API is experimental and outside the 1.x contract — every reader has to be told, and told the same thing.');+process.exit(1);diff --git a/tools/gates.mjs b/tools/gates.mjsindex 905550b41..2179d5243 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -39,6 +39,10 @@ export const GATES = [{ id: 'api-surface-baseline', run: 'node tools/api-surface.mjs --check-baseline' },{ id: 'freeze-bar', run: 'node tools/check-freeze-bar.mjs' },{ id: 'tier-leaks', run: 'node tools/check-tier-leaks.mjs' },+ // The SDK's tiers are enforced by the three gates above. The editor plugin API+ // has no snapshot to enforce, so what is enforced there is the ANSWER: that it+ // is experimental, said the same way in every place someone reads it.+ { id: 'plugin-api-contract', run: 'node tools/check-plugin-api-contract.mjs' },// Everything below reads what this emits: the declaration snapshot, the// editor's own type-check and the examples all resolve `esengine` from dist.{ id: 'sdk-build', run: 'pnpm --filter ./sdk build' },diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjsindex 0d5d34591..bca7d70f4 100644--- a/tools/releaseGate.mjs+++ b/tools/releaseGate.mjs@@ -178,6 +178,15 @@ export const CRITERIA = [answeredBy: 'node tools/api-surface.mjs --check-dts',needs: ['tools/api-surface.mjs', 'tools/lib/sdkProgram.mjs'],},+ {+ id: 'plugin-api-answers-for-itself',+ says: 'the editor plugin API states which side of the 1.x contract it is on, everywhere it is read',+ // The question 0.50 had to answer, and the answer is "experimental, outside+ // the contract". What fails a release is not the answer but its absence from+ // one of the places somebody acts on it.+ answeredBy: 'node tools/check-plugin-api-contract.mjs',+ needs: ['tools/check-plugin-api-contract.mjs', 'desktop/src/plugins/types.ts'],+ },{id: 'creator-can-say-what-is-safe',says: 'the docs name the four tiers and which APIs are in each, in both languages',