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
docs(guides): the plugin system shipped with no user documentation
esengine6ec91d1e843b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b78b324cf..735f4e0a4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,36 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **Editor plugins.** Extend the editor with your own TypeScript: commands (with+ keybindings, palette and menu entries), dock panels, Inspector sections,+ viewport gizmos and tools, asset types, entity templates, settings, and+ Outliner/Content-Browser context-menu rows. Plugins live in+ `.esengine/plugins/<id>/` (or per-user, across projects), need **no build+ step** — the editor compiles them and re-compiles on save, re-activating the+ plugin and reopening its panels — and get full typings with nothing to install:+ the editor writes `@estella/editor-api`'s declarations into the project so they+ always match the running editor. A plugin registers through the same registries+ the editor's own features use, so a contributed command *is* a command and a+ contributed panel *is* a dock panel; scene edits go through the editor's command+ layer, so they are undoable and survive Play → Stop. Errors are attributed in+ the Output Log, timed in the profiler, and a repeatedly-failing plugin is+ disabled rather than allowed to break a surface. See the+ [Editor Plugins](https://esengine.github.io/estella/guides/editor-plugins/) guide.++### Security++- **Project platform profiles now require approval.** A `.esengine/platforms/*.mjs`+ packaging profile is imported into the editor's main process with full system+ access, and used to be loaded with no prompt the moment anything asked what+ platforms a project could package for — while the *less* privileged renderer+ plugins were gated. Both now pass one trust prompt and appear in one list+ (Window ▸ Plugins). An unapproved profile is not imported at all, and says so in+ the Package dialog instead of showing an unexplained not-ready target. The file+ format is unchanged; existing projects need no migration, only a one-time+ approval.+## [0.33.0] - 2026-07-26Shipping. Two targets stopped being foundations and became things you candiff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex d48d4e057..08f69fe50 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -131,6 +131,7 @@ export default defineConfig({{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },{ label: 'Mini-Game Platforms', translations: { 'zh-CN': '小游戏平台' }, slug: 'guides/minigame-platforms' },{ label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },+ { label: 'Editor Plugins', translations: { 'zh-CN': '编辑器插件' }, slug: 'guides/editor-plugins' },{ label: 'AI Agents (MCP)', translations: { 'zh-CN': 'AI 代理 (MCP)' }, slug: 'guides/mcp' },],},diff --git a/docs/astro/src/content/docs/guides/editor-plugins.mdx b/docs/astro/src/content/docs/guides/editor-plugins.mdxnew file mode 100644index 000000000..332231a33--- /dev/null+++ b/docs/astro/src/content/docs/guides/editor-plugins.mdx@@ -0,0 +1,258 @@+---+title: Editor Plugins+description: Extend the Estella editor with your own TypeScript — commands, panels, inspector sections, viewport gizmos and tools, asset types and context-menu actions — with no build step and hot reload while you write.+---++import { Aside, Steps, FileTree } from '@astrojs/starlight/components';++A plugin adds your own tools to the editor: a command in the Tools menu, a docked+panel, an extra section in the Inspector, a gizmo drawn in the viewport, a new+asset type. Plugins are TypeScript, they live in your project, and there is **no+build step** — the editor compiles them, and re-compiles the moment you save.++Everything a plugin registers goes through the same registries the editor's own+features use. A contributed command is a command; a contributed panel is a dock+panel with a tab, a close button and pop-out. There is no reduced "plugin version"+of anything.++## Your first plugin++<Steps>++1. Create the folder — the id is `<publisher>.<name>`:++ <FileTree>+ - .esengine/+ - plugins/+ - acme.level-tools/+ - plugin.json+ - src/+ - editor.ts+ </FileTree>++2. Write `plugin.json`:++ ```json+ {+ "id": "acme.level-tools",+ "name": { "en": "Level Tools", "zh-CN": "关卡工具" },+ "version": "1.0.0",+ "engines": { "editor": "^0.33" },+ "main": { "editor": "src/editor.ts" }+ }+ ```++3. Write `src/editor.ts`:++ ```ts+ import { definePlugin, type PluginContext } from '@estella/editor-api';++ export default definePlugin({+ activate(ctx: PluginContext) {+ ctx.commands.register({+ id: 'acme.level-tools.countEntities',+ title: { en: 'Count Entities', 'zh-CN': '统计实体' },+ menu: 'tools',+ run: () => ctx.ui.toast(`${ctx.scene.getSceneTree().length} root entities`),+ });+ },+ });+ ```++4. Open **Window ▸ Plugins**, find your plugin, and choose **Trust and load**.++</Steps>++Your command is now in the Tools menu and the command palette. Edit `editor.ts`+and save: the editor recompiles and re-activates it, and any panel it contributed+reopens on the new build.++<Aside type="caution" title="Trust">+A plugin runs with the same access the editor has — your project files and+anything the editor can reach. That is why nothing loads until you approve it, and+why you should only load plugins whose source you trust. The prompt lists what the+plugin declared, but declared capabilities describe *intent*: they are not a+sandbox.++Approval covers that version from that folder. A new version, or a different+folder claiming the same id, asks again.+</Aside>++## Typings++The editor writes `@estella/editor-api`'s typings into your project at+`.esengine/plugins/.types/editor-api.d.ts` every time it opens the project, so they+always match the editor you're running. Point your plugin's `tsconfig.json` at+them:++```json+{+ "compilerOptions": {+ "strict": true,+ "moduleResolution": "bundler",+ "paths": { "@estella/editor-api": ["../.types/editor-api.d.ts"] }+ },+ "include": ["src"]+}+```++Nothing to install, and no copy that can go stale.++## What a plugin can contribute++Every `register` returns a disposable, and everything is retracted automatically+when the plugin unloads — you rarely need to keep the handle.++### Commands++Land in the command palette, and optionally a menu. Label, shortcut hint,+enablement and checked state all come from this one declaration.++```ts+ctx.commands.register({+ id: 'acme.level-tools.bake',+ title: { en: 'Bake Occlusion' },+ keybinding: 'mod+alt+b',+ menu: 'tools',+ isEnabled: () => ctx.scene.getSelectionIds().length > 0,+ run: () => { /* … */ },+});+```++### Panels++`mount` gets a plain host element and returns its teardown. The editor owns the+tab, the error boundary and pop-out. Style against the editor's CSS variables+(`--bg`, `--text`, `--text-dim`, `--accent`, …) and the panel matches the+surrounding chrome in both light and dark.++```ts+ctx.panels.register({+ id: 'acme.level-tools.budget',+ title: { en: 'Level Budget' },+ placement: 'bottom',+ mount: (host) => {+ host.textContent = 'hello';+ return () => { /* teardown */ };+ },+});+```++You may use React — the editor injects its own instance, so hooks work and there+is no second copy:++```ts+import { createRoot } from 'react-dom/client';+```++### Inspector sections++Adds a section under a component (or for an asset type), built from rows the+editor renders with its own property UI — so it looks native with no styling.++```ts+ctx.inspector.register({+ kind: 'component',+ id: 'budget',+ component: 'Sprite',+ title: { en: 'Budget' },+ build: (entity, ui) => {+ ui.info({ en: 'Texture' }, String(ctx.scene.getFieldValue(entity, 'Sprite', 'texture') ?? '—'));+ ui.number('weight', { en: 'Weight' }, 1, { min: 0, max: 10 });+ },+ write: (entity, key, value) => { /* an edit to a row you built */ },+});+```++### Viewport gizmos++Drawn every frame, in **world coordinates** — the editor projects them, so a gizmo+follows the scene through pan and zoom, and a radius in world units scales with+it. Stroke widths and text stay in screen pixels.++```ts+ctx.overlays.register({+ id: 'acme.spawn-radius',+ render: (g) => {+ const id = ctx.scene.getSelection();+ if (id == null) return;+ const p = ctx.scene.getFieldValue(id, 'Transform', 'position');+ if (!Array.isArray(p)) return;+ g.circle({ x: p[0], y: p[1] }, 120, { color: 'var(--accent)', dashed: true });+ },+});+```++### Viewport tools++While *armed*, a tool gets first refusal on every pointer stroke. Returning `true`+from `onPointerDown` claims the stroke and its move/up. Picking any built-in tool+disarms it, so you can never get stuck in a plugin's tool.++```ts+ctx.tools.register({+ id: 'acme.measure',+ title: { en: 'Measure' },+ onPointerDown: (p, tc) => { tc.capture(p.pointerId); return true; },+ onPointerMove: (p) => { const w = ctx.viewport.viewportToWorld(p.x, p.y); },+ onPointerUp: (p, tc) => tc.release(p.pointerId),+});+ctx.tools.activate('acme.measure');+```++### The rest++- `ctx.settings.register(…)` — a row under **Settings ▸ Plugins ▸ your plugin**.+- `ctx.assets.registerType(…)` — a new asset type: extensions, tile badge,+ double-click action, and a **New ▸ …** entry.+- `ctx.entities.registerTemplate(…)` — a ready-made entity in the Create picker.+- `ctx.contextMenus.register(…)` — a row in the Outliner or Content Browser+ right-click menu, gated by the thing that was clicked.++## Editing the scene++Always go through `ctx.scene`. Those writes run through the editor's command+layer, which means they land in the undo history and survive Play → Stop. Reaching+around it to the live engine loses both.++```ts+ctx.scene.transact('Rename Markers', () => {+ for (const node of ctx.scene.getSceneTree()) {+ if (node.name === 'Entity') ctx.scene.renameEntity(node.id, 'Marker');+ }+});+```++Everything inside one `transact` is a single undo step, however many edits it+makes.++## When something goes wrong++Open **Window ▸ Plugins**. Every plugin the editor found is listed — including the+broken ones, with the reason: a manifest that failed to parse, a compile error, or+an id another plugin already claimed. Errors thrown by your plugin appear in the+**Output Log** tagged `plugin:<your-id>`, with a stack.++If a plugin keeps throwing, the editor disables it rather than letting it break a+surface on every render. Fix it and press **Reload**.++<Aside type="tip">+A plugin's own timings show up in the profiler under `plugin.<id>.<what>`, next to+the editor's own work — so a slow overlay or command is visible rather than+mysterious.+</Aside>++## Where plugins live++- **`<project>/.esengine/plugins/<id>/`** — versioned with the project and shared+ with your team. This is the usual place.+- **`<userData>/plugins/<id>/`** — your own tools, across every project. A project+ plugin with the same id takes precedence, and the shadowed one says so.++## Project platform profiles++A `.esengine/platforms/<id>.mjs` packaging profile (see+[Mini-Game Platforms](/guides/minigame-platforms/)) is imported into the editor's+main process with full system access. It is listed in the Plugins panel and needs+the same approval — until you approve it, its target shows as not ready in the+Package dialog.diff --git a/docs/astro/src/content/docs/zh-cn/guides/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor-plugins.mdxnew file mode 100644index 000000000..a93f81142--- /dev/null+++ b/docs/astro/src/content/docs/zh-cn/guides/editor-plugins.mdx@@ -0,0 +1,241 @@+---+title: 编辑器插件+description: 用你自己的 TypeScript 扩展 Estella 编辑器——命令、面板、检查器分区、视口 gizmo 与工具、资产类型、右键菜单项——无需构建步骤,边写边热重载。+---++import { Aside, Steps, FileTree } from '@astrojs/starlight/components';++插件把你自己的工具加进编辑器:工具菜单里的一条命令、一个停靠面板、检查器里+多出来的一段、视口里画的 gizmo、一种新的资产类型。插件是 TypeScript,放在你的+项目里,而且**不需要构建步骤**——编辑器负责编译,你一保存就重新编译。++插件注册的一切都走编辑器自己功能所用的同一套注册表。贡献的命令就是命令;贡献+的面板就是带标签页、关闭按钮和弹出功能的停靠面板。不存在任何东西的"插件简化版"。++## 你的第一个插件++<Steps>++1. 建目录——id 形如 `<发布者>.<名字>`:++ <FileTree>+ - .esengine/+ - plugins/+ - acme.level-tools/+ - plugin.json+ - src/+ - editor.ts+ </FileTree>++2. 写 `plugin.json`:++ ```json+ {+ "id": "acme.level-tools",+ "name": { "en": "Level Tools", "zh-CN": "关卡工具" },+ "version": "1.0.0",+ "engines": { "editor": "^0.33" },+ "main": { "editor": "src/editor.ts" }+ }+ ```++3. 写 `src/editor.ts`:++ ```ts+ import { definePlugin, type PluginContext } from '@estella/editor-api';++ export default definePlugin({+ activate(ctx: PluginContext) {+ ctx.commands.register({+ id: 'acme.level-tools.countEntities',+ title: { en: 'Count Entities', 'zh-CN': '统计实体' },+ menu: 'tools',+ run: () => ctx.ui.toast(`${ctx.scene.getSceneTree().length} 个根实体`),+ });+ },+ });+ ```++4. 打开**窗口 ▸ 插件**,找到你的插件,点**信任并加载**。++</Steps>++你的命令现在出现在工具菜单和命令面板里。改一下 `editor.ts` 再保存:编辑器会+重新编译并重新激活它,它贡献的面板也会以新构建重新打开。++<Aside type="caution" title="信任">+插件与编辑器拥有同等权限——你的项目文件,以及编辑器能触及的一切。所以在你批准+之前什么都不会加载,也所以你只应加载来源可信的插件。提示框会列出插件声明的能力,+但**声明的能力表达的是意图:它不是沙箱**。++批准只对应那个版本、那个目录。新版本,或另一个目录声称同一 id,都会重新询问。+</Aside>++## 类型定义++编辑器每次打开项目时,都会把 `@estella/editor-api` 的类型写进+`.esengine/plugins/.types/editor-api.d.ts`,因此它永远与你正在运行的编辑器一致。+在插件的 `tsconfig.json` 里指过去:++```json+{+ "compilerOptions": {+ "strict": true,+ "moduleResolution": "bundler",+ "paths": { "@estella/editor-api": ["../.types/editor-api.d.ts"] }+ },+ "include": ["src"]+}+```++无需安装任何东西,也不存在会过期的副本。++## 插件能贡献什么++每个 `register` 都返回一个 disposable,插件卸载时全部自动撤回——你通常不需要+自己保存这些句柄。++### 命令++进入命令面板,也可以进菜单。标签、快捷键提示、可用性与勾选态都来自这一处声明。++```ts+ctx.commands.register({+ id: 'acme.level-tools.bake',+ title: { en: 'Bake Occlusion', 'zh-CN': '烘焙遮挡' },+ keybinding: 'mod+alt+b',+ menu: 'tools',+ isEnabled: () => ctx.scene.getSelectionIds().length > 0,+ run: () => { /* … */ },+});+```++### 面板++`mount` 拿到一个普通的宿主元素,返回它的拆卸函数。标签页、错误边界和弹出窗口由+编辑器负责。用编辑器的 CSS 变量(`--bg`、`--text`、`--text-dim`、`--accent` …)+写样式,面板在明暗两种主题下都与周围的界面一致。++```ts+ctx.panels.register({+ id: 'acme.level-tools.budget',+ title: { en: 'Level Budget', 'zh-CN': '关卡预算' },+ placement: 'bottom',+ mount: (host) => {+ host.textContent = 'hello';+ return () => { /* 拆卸 */ };+ },+});+```++你可以用 React——编辑器会注入它自己的实例,所以 hooks 正常工作,也不会出现第二份+副本:++```ts+import { createRoot } from 'react-dom/client';+```++### 检查器分区++在某个组件下(或某种资产类型下)加一段,由编辑器用它自己的属性 UI 渲染你声明的+行——所以不用写样式就是原生外观。++```ts+ctx.inspector.register({+ kind: 'component',+ id: 'budget',+ component: 'Sprite',+ title: { en: 'Budget', 'zh-CN': '预算' },+ build: (entity, ui) => {+ ui.info({ en: 'Texture', 'zh-CN': '纹理' }, String(ctx.scene.getFieldValue(entity, 'Sprite', 'texture') ?? '—'));+ ui.number('weight', { en: 'Weight', 'zh-CN': '权重' }, 1, { min: 0, max: 10 });+ },+ write: (entity, key, value) => { /* 你建的某一行被编辑了 */ },+});+```++### 视口 gizmo++每帧绘制,坐标是**世界坐标**——由编辑器投影,所以 gizmo 会随平移缩放跟随场景,+以世界单位给的半径也会随之缩放。线宽和文字则保持屏幕像素。++```ts+ctx.overlays.register({+ id: 'acme.spawn-radius',+ render: (g) => {+ const id = ctx.scene.getSelection();+ if (id == null) return;+ const p = ctx.scene.getFieldValue(id, 'Transform', 'position');+ if (!Array.isArray(p)) return;+ g.circle({ x: p[0], y: p[1] }, 120, { color: 'var(--accent)', dashed: true });+ },+});+```++### 视口工具++处于 **armed** 状态时,工具对每一笔指针操作有优先接管权。`onPointerDown` 返回+`true` 即接管这一笔及其后续 move/up。选择任何内建工具都会解除 arming,所以你不会+被卡在插件的工具里。++```ts+ctx.tools.register({+ id: 'acme.measure',+ title: { en: 'Measure', 'zh-CN': '测距' },+ onPointerDown: (p, tc) => { tc.capture(p.pointerId); return true; },+ onPointerMove: (p) => { const w = ctx.viewport.viewportToWorld(p.x, p.y); },+ onPointerUp: (p, tc) => tc.release(p.pointerId),+});+ctx.tools.activate('acme.measure');+```++### 其余++- `ctx.settings.register(…)`——**设置 ▸ 插件 ▸ 你的插件**下的一行。+- `ctx.assets.registerType(…)`——一种新资产类型:扩展名、图块徽章、双击动作,+ 以及一条**新建 ▸ …**菜单项。+- `ctx.entities.registerTemplate(…)`——创建选择器里的一个现成实体。+- `ctx.contextMenus.register(…)`——大纲或内容浏览器右键菜单里的一行,可按被点击+ 的对象决定是否出现。++## 编辑场景++一律走 `ctx.scene`。这些写入经过编辑器的命令层,因此会进入撤销历史,并且能扛过+Play → Stop。绕开它直接改活的引擎,这两点都会失去。++```ts+ctx.scene.transact('Rename Markers', () => {+ for (const node of ctx.scene.getSceneTree()) {+ if (node.name === 'Entity') ctx.scene.renameEntity(node.id, 'Marker');+ }+});+```++一次 `transact` 里的全部改动是**一个**撤销步骤,不管它改了多少东西。++## 出问题的时候++打开**窗口 ▸ 插件**。编辑器找到的每个插件都在列表里——包括坏掉的,并附上原因:+清单解析失败、编译报错,或 id 被另一个插件占用。你的插件抛出的错误会出现在+**输出日志**里,带 `plugin:<你的-id>` 标记和堆栈。++如果一个插件反复抛错,编辑器会停用它,而不是让它每帧都弄坏某个界面。修好后点+**重新加载**。++<Aside type="tip">+插件自身的耗时会出现在性能分析器的 `plugin.<id>.<什么>` 下,与编辑器自己的工作+并排——所以慢的覆盖层或命令是看得见的,而不是一团迷雾。+</Aside>++## 插件放在哪++- **`<项目>/.esengine/plugins/<id>/`**——随项目版本管理,与团队共享。通常放这里。+- **`<userData>/plugins/<id>/`**——你个人的工具,跨所有项目。同 id 时项目里的那个+ 优先,被遮蔽的那个会说明原因。++## 项目平台配置++`.esengine/platforms/<id>.mjs` 打包配置(见+[小游戏平台](/zh-cn/guides/minigame-platforms/))会以完整系统权限被导入编辑器主+进程。它同样列在插件面板里、同样需要批准——在你批准之前,它对应的目标在打包对话框+里显示为未就绪。