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(plugins): the editor plugin API answers which side of 1.0 it is on

esengine3657d9dde930
diff --git a/VERSIONING.md b/VERSIONING.md
index eea05480e..2b2dc803d 100644
--- a/VERSIONING.md
+++ b/VERSIONING.md
@@ -36,6 +36,47 @@ release: internal C++ headers under `src/`, unexported SDK internals, editor
internals, 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 tiers
Surface 1 is large, and not all of it is equally settled. Every exported symbol
diff --git a/desktop/src/plugins/types.ts b/desktop/src/plugins/types.ts
index 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.mdx
index 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 fr
somewhere 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 contributed
Every running plugin has a **Contributes** row in the Plugins panel. Expand it for
diff --git a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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',