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(editor): a plugin can put a button on the rail
yhh04cf45c522c4
diff --git a/desktop/src/i18n/messages/plugins.ts b/desktop/src/i18n/messages/plugins.tsindex dfa0d40a1..c147390d2 100644--- a/desktop/src/i18n/messages/plugins.ts+++ b/desktop/src/i18n/messages/plugins.ts@@ -78,6 +78,7 @@ export const pluginMessages = defineMessages({'plug.kind.importer': { en: 'Importer', zh: '导入器' },'plug.kind.entityTemplate': { en: 'Entity', zh: '实体' },'plug.kind.contextMenu': { en: 'Menu item', zh: '菜单项' },+ 'plug.kind.activityBar': { en: 'Rail button', zh: '侧栏按钮' },'plug.kind.agentTool': { en: 'Agent tool', zh: 'Agent 工具' },// — New plugin. The editor writes the folder because the SHAPE of a plugin isdiff --git a/desktop/src/layout/ActivityBar.tsx b/desktop/src/layout/ActivityBar.tsxindex 6535df546..2063d4a87 100644--- a/desktop/src/layout/ActivityBar.tsx+++ b/desktop/src/layout/ActivityBar.tsx@@ -3,7 +3,8 @@// Far-left icon rail (activity bar). Switches the editing mode, reveals docked// panels, and toggles the Content Drawer — the summoned quick-access surface.import { useSyncExternalStore } from 'react';-import { ListTree, SlidersHorizontal, FolderOpen, Terminal, Clapperboard, Gauge, Settings, Sparkles } from 'lucide-react';+import { ListTree, SlidersHorizontal, FolderOpen, Terminal, Clapperboard, Gauge, Settings, Sparkles, Plug } from 'lucide-react';+import { activityBarRegistry } from '@/plugins/activityBar';import { useEditorStore } from '@/store/editorStore';import { useEditorMode } from '@/store/editorModeStore';import { useSelection } from '@/store/selectionStore';@@ -30,6 +31,9 @@ export function ActivityBar() {// The mode rail is derived from the registry, so a contributed mode appears// (and a retracted one disappears) without a reload.const modes = useSyncExternalStore(editorModeRegistry.subscribe.bind(editorModeRegistry), editorModes);+ // Plugin buttons join the panel group rather than the modes: what a plugin+ // reveals is a surface of its own, and the modes are what the editor edits.+ const contributed = useSyncExternalStore(activityBarRegistry.subscribe, activityBarRegistry.all);return (<div className="activity">@@ -96,6 +100,13 @@ export function ActivityBar() {><Gauge size={19} strokeWidth={1.7} /></button>+ {contributed.map((item) => (+ <button key={item.id} type="button" className="act" title={item.title} onClick={item.run}>+ {item.icon+ ? <span className="act-glyph" dangerouslySetInnerHTML={{ __html: item.icon }} />+ : <Plug size={19} strokeWidth={1.7} />}+ </button>+ ))}<span className="act-spacer" />diff --git a/desktop/src/panels/PluginsPanel.tsx b/desktop/src/panels/PluginsPanel.tsxindex 9aef809a2..a68799c26 100644--- a/desktop/src/panels/PluginsPanel.tsx+++ b/desktop/src/panels/PluginsPanel.tsx@@ -64,6 +64,7 @@ const KIND_LABEL: Record<ContributionKind, MsgKey> = {importer: 'plug.kind.importer',entityTemplate: 'plug.kind.entityTemplate',contextMenu: 'plug.kind.contextMenu',+ activityBar: 'plug.kind.activityBar',agentTool: 'plug.kind.agentTool',};diff --git a/desktop/src/plugins/PluginHost.ts b/desktop/src/plugins/PluginHost.tsindex 59d19b546..100f24f2e 100644--- a/desktop/src/plugins/PluginHost.ts+++ b/desktop/src/plugins/PluginHost.ts@@ -34,6 +34,7 @@ import { assetTypeRegistry } from '@/project/assetTypes';import { overlayRegistry } from './overlays';import { inspectorRegistry } from './inspector';import { contextMenuRegistry } from './contextMenus';+import { activityBarRegistry } from './activityBar';import { LogStore } from '@/store/LogStore';import { Toasts } from '@/store/Toasts';import { PerfMonitor } from '@/engine/PerfMonitor';@@ -101,6 +102,7 @@ const CONTRIBUTION_REGISTRIES = [inspectorRegistry,assetTypeRegistry,contextMenuRegistry,+ activityBarRegistry,];interface LoadedPlugin {diff --git a/desktop/src/plugins/activityBar.ts b/desktop/src/plugins/activityBar.tsnew file mode 100644index 000000000..28904dbb3--- /dev/null+++ b/desktop/src/plugins/activityBar.ts@@ -0,0 +1,42 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file activityBar.ts+ * @brief Contributed buttons on the far-left icon rail.+ *+ * The rail's own buttons are written into the component, because the editor's+ * modes and panels are not a set that changes. A plugin's is, so it arrives here+ * and the rail renders both — which is what the audio mixer needed the day it+ * became a plugin and lost the entry point it had shipped with for a year.+ */+import { ContributionRegistry, type Disposable, type Owner } from '@/contrib/ContributionRegistry';++/** A rail button as the component draws it: label localized, glyph already vetted. */+export interface ActivityBarItem {+ id: string;+ title: string;+ /** Inline SVG, or null for the glyph every contributed thing wears. */+ icon: string | null;+ run(): void;+}++const contrib = new ContributionRegistry<ActivityBarItem>('activity bar item');++export const activityBarRegistry = {+ register: (owner: Owner, item: ActivityBarItem): Disposable => contrib.register(owner, item),+ disposeOwner: (owner: Owner): void => contrib.disposeOwner(owner),+ all: (): readonly ActivityBarItem[] => contrib.all(),+ subscribe: (fn: () => void): (() => void) => contrib.subscribe(fn),+};++/**+ * The icon a plugin supplied, or null when it is not an `<svg>` element.+ *+ * A shape check, not a sandbox — a plugin is trusted code in this renderer and+ * reaches the DOM directly anyway. What it buys is a legible failure: a wrong+ * value draws the fallback instead of a stray element in the rail.+ */+export function railIcon(icon: string | undefined): string | null {+ const svg = (icon ?? '').trim();+ return /^<svg[\s>]/i.test(svg) && /<\/svg>$/i.test(svg) ? svg : null;+}diff --git a/desktop/src/plugins/context.ts b/desktop/src/plugins/context.tsindex a33bc3d70..b958970d5 100644--- a/desktop/src/plugins/context.ts+++ b/desktop/src/plugins/context.ts@@ -24,6 +24,7 @@ import { assetTypeRegistry, CONTRIBUTED_ASSET_ICON } from '@/project/assetTypes'import { entitySourceRegistry, prefabFromSpecs } from '@/engine/entitySources';import { overlayRegistry, viewportProjection } from './overlays';import { inspectorRegistry } from './inspector';+import { activityBarRegistry, railIcon } from './activityBar';import { contextMenuRegistry } from './contextMenus';import { importerRegistry, runImporters } from './importers';import { localizePlugin as localize } from './localize';@@ -44,7 +45,7 @@ import type { PointerInput as CorePointerInput } from '@/tools/EditorTool';import type { PluginManifest, PluginCapability } from './manifest';import { agentToolProblem, registerAgentTool, publishAgentTools } from './agentTools';import type {- AgentToolContribution, AssetImporterContribution,+ ActivityBarContribution, AgentToolContribution, AssetImporterContribution,AssetTypeContribution, CommandContribution, ContextMenuContribution, Disposable, EditorEvents,EditorPlugin, EditorProjectApi, EditorSceneApi, EntityTemplateContribution, FieldValue,InspectorContribution, OverlayContribution, PanelContribution, PluginContext,@@ -212,6 +213,7 @@ export type ContributionKind =| 'importer'| 'entityTemplate'| 'contextMenu'+ | 'activityBar'| 'agentTool';/** One thing a plugin added, as the Plugins panel shows it. */@@ -472,6 +474,19 @@ export function buildPluginContext(return { dispose: () => { handle.dispose(); publishAgentTools(); } };};+ const registerActivityBarItem = (item: ActivityBarContribution): Disposable =>+ noted(+ 'activityBar',+ scoped(item.id),+ localize(item.title),+ activityBarRegistry.register(owner, {+ id: scoped(item.id),+ title: localize(item.title),+ icon: railIcon(item.icon),+ run: () => guard(`activity bar ${item.id}`, () => item.run(), undefined),+ }),+ );+const registerContextMenuItem = (item: ContextMenuContribution): Disposable =>noted('contextMenu',@@ -501,6 +516,7 @@ export function buildPluginContext(register: registerPluginPanel,open: (pid) => dockApi.openPanel(pid),},+ activityBar: { register: registerActivityBarItem },settings: {register: registerSetting,get: <T extends boolean | number | string>(sid: string) => useSettings.getState().getValue(scoped(sid)) as T | undefined,diff --git a/desktop/src/plugins/types.ts b/desktop/src/plugins/types.tsindex d83f63a19..6aaed6b2a 100644--- a/desktop/src/plugins/types.ts+++ b/desktop/src/plugins/types.ts@@ -106,6 +106,30 @@ export interface PanelContribution {mount(host: HTMLElement): () => void;}+// — Activity bar ——————————————————————————————————————————————————————————————++/**+ * A button on the far-left icon rail, beside the ones that reveal the editor's+ * own panels — one click to the surface a plugin owns, rather than a menu.+ *+ * The rail is short and shared. Contribute one button, for the thing your plugin+ * IS; a second belongs in the Tools menu, where a command already goes.+ */+export interface ActivityBarContribution {+ /** Under your plugin id, e.g. `acme.level-tools.rail`. */+ id: string;+ /** Tooltip — the rail shows no text. */+ title: LocalizedString;+ /**+ * Inline `<svg>` for the glyph, drawn at 19px. `stroke="currentColor"` (or+ * `fill`) makes it follow the rail through hover and both themes. Anything+ * else falls back to the plug every contributed thing wears — which two+ * plugins would then collide on, so ship an icon.+ */+ icon?: string;+ run(): void;+}+export interface SettingContributionBase {/** Under your plugin id, e.g. `acme.level-tools.warnAt`. Read it back with* {@link PluginContext.settings}.get, which takes the same id you wrote. */@@ -575,6 +599,9 @@ export interface PluginContext {/** Open (or bring forward) a panel by id. */open(id: string): void;};+ readonly activityBar: {+ register(item: ActivityBarContribution): Disposable;+ };readonly settings: {register(setting: SettingContribution): Disposable;/** Current value of one of YOUR settings. */diff --git a/desktop/src/theme/chrome.css b/desktop/src/theme/chrome.cssindex 64723dfad..541a49cbf 100644--- a/desktop/src/theme/chrome.css+++ b/desktop/src/theme/chrome.css@@ -249,6 +249,11 @@from { transform: translateY(-50%) scaleY(0.2); opacity: 0; }to { transform: translateY(-50%) scaleY(1); opacity: 1; }}+/* A contributed glyph is the plugin's own SVG: size it to the rail's own 19px+ and let it inherit the button's colour, so it lives through hover and both+ themes exactly as a built-in does. */+.act-glyph { display: grid; place-items: center; }+.act-glyph svg { width: 19px; height: 19px; display: block; }.act-spacer { flex: 1; }.act-sep { width: 20px; height: 1px; background: var(--border); margin: 4px 0; flex-shrink: 0; }diff --git a/desktop/tests/plugin-contributions.test.ts b/desktop/tests/plugin-contributions.test.tsindex cc8c44e50..c586e6ad5 100644--- a/desktop/tests/plugin-contributions.test.ts+++ b/desktop/tests/plugin-contributions.test.ts@@ -12,6 +12,7 @@*/import { describe, it, expect, vi, afterEach } from 'vitest';import { createSectionBuilder, isInfoRow, inspectorRegistry } from '@/plugins/inspector';+import { activityBarRegistry, railIcon } from '@/plugins/activityBar';import { contextMenuRegistry, contributedContextRows } from '@/plugins/contextMenus';import { assetTypeRegistry, assetTypeOf, assetTypeDef, ASSET_TYPES } from '@/project/assetTypes';import { toolRegistry } from '@/tools/toolRegistry';@@ -24,7 +25,7 @@ const PLUGIN = 'plugin:acme';const id = (v: LocalizedString) => (typeof v === 'string' ? v : v.en);afterEach(() => {- for (const registry of [inspectorRegistry, contextMenuRegistry, assetTypeRegistry, toolRegistry]) {+ for (const registry of [inspectorRegistry, contextMenuRegistry, assetTypeRegistry, toolRegistry, activityBarRegistry]) {registry.disposeOwner(PLUGIN);}});@@ -76,6 +77,35 @@ describe('inspector section builder', () => {});});+// — Activity bar ——————————————————————————————————————————————————————————————++describe('the rail glyph', () => {+ it('takes an svg element and nothing else', () => {+ expect(railIcon('<svg viewBox="0 0 24 24"><path d="M0 0h24"/></svg>')).toContain('<path');+ expect(railIcon(' <SVG></SVG> ')).toBe('<SVG></SVG>');+ // A wrong value draws the fallback rather than putting a stray element —+ // or a half-written one — into the rail.+ expect(railIcon(undefined)).toBeNull();+ expect(railIcon('')).toBeNull();+ expect(railIcon('mixer.png')).toBeNull();+ expect(railIcon('<img src="x">')).toBeNull();+ expect(railIcon('<svg><path d="M0 0h24"/>')).toBeNull();+ // `<svgfoo>` is not an svg, and the shape check must not read it as one.+ expect(railIcon('<svgx></svgx>')).toBeNull();+ });+});++describe('activity bar registry', () => {+ it('keeps a plugin`s buttons in registration order and retracts them with the plugin', () => {+ activityBarRegistry.register(PLUGIN, { id: 'a', title: 'A', icon: null, run: () => {} });+ activityBarRegistry.register(PLUGIN, { id: 'b', title: 'B', icon: null, run: () => {} });+ expect(activityBarRegistry.all().map((i) => i.id)).toEqual(['a', 'b']);++ activityBarRegistry.disposeOwner(PLUGIN);+ expect(activityBarRegistry.all()).toEqual([]);+ });+});+describe('inspector registry', () => {it('resolves sections by component and by asset type, not across', () => {inspectorRegistry.register(PLUGIN, {diff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdxindex 8c3af0c70..4d250eb4c 100644--- a/docs/astro/src/content/docs/extending/editor-plugins.mdx+++ b/docs/astro/src/content/docs/extending/editor-plugins.mdx@@ -244,6 +244,29 @@ is no second copy:import { createRoot } from 'react-dom/client';```+### A button on the rail++A panel reachable only through a menu is a panel nobody opens. One button on the+far-left rail, beside the ones that reveal the editor's own panels:++```ts+ctx.activityBar.register({+ id: 'acme.level-tools.rail',+ title: { en: 'Level Budget' },+ // Inline SVG, drawn at 19px. `currentColor` is what makes it follow the rail+ // through hover and both themes.+ icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7">'+ + '<path d="M4 20V10M10 20V4M16 20v-8M22 20H2"/></svg>',+ run: () => ctx.panels.open('acme.level-tools.budget'),+});+```++Leave `icon` out and you get the plug every contributed thing wears — which is+also what two plugins would collide on, so ship one.++The rail is short and shared. Contribute a button for the thing your plugin **is**;+anything else is a command, and the Tools menu is where commands go.+### Inspector sectionsAdds a section under a component (or for an asset type), built from rows thediff --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 2fbee3352..9ce7fa0ec 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@@ -222,6 +222,28 @@ ctx.panels.register({import { createRoot } from 'react-dom/client';```+### 左侧栏上的一个按钮++只能从菜单里翻出来的面板等于没人开。在最左边那条图标栏上加一个按钮,和编辑器自+己那些面板按钮并排:++```ts+ctx.activityBar.register({+ id: 'acme.level-tools.rail',+ title: { en: 'Level Budget', 'zh-CN': '关卡预算' },+ // 内联 SVG,按 19px 绘制。用 currentColor 它才会跟着侧栏走悬停和明暗主题。+ icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7">'+ + '<path d="M4 20V10M10 20V4M16 20v-8M22 20H2"/></svg>',+ run: () => ctx.panels.open('acme.level-tools.budget'),+});+```++不给 `icon` 就用所有贡献物共用的那个插头图标——两个插件也就都长成插头,所以自己+带一个。++这条栏又短又是公用的。**你的插件是什么**,就为那件事贡献一个按钮;别的都是命令,+命令的去处是「工具」菜单。+### 检查器分区在某个组件下(或某种资产类型下)加一段,由编辑器用它自己的属性 UI 渲染你声明的diff --git a/plugins/audio-mixer/src/editor.tsx b/plugins/audio-mixer/src/editor.tsxindex 0da020c87..1af40f85c 100644--- a/plugins/audio-mixer/src/editor.tsx+++ b/plugins/audio-mixer/src/editor.tsx@@ -4,7 +4,7 @@ import { createRoot } from 'react-dom/client';import { definePlugin, type PluginContext } from '@estella/editor-api';import { Mixer } from './Mixer';import { PANEL_TITLE } from './strings';-import { CSS } from './style';+import { CSS, RAIL_ICON } from './style';export default definePlugin({activate(ctx: PluginContext) {@@ -31,5 +31,12 @@ export default definePlugin({menu: 'window',run: () => ctx.panels.open('estella.audio-mixer.panel'),});++ ctx.activityBar.register({+ id: 'estella.audio-mixer.rail',+ title: PANEL_TITLE,+ icon: RAIL_ICON,+ run: () => ctx.panels.open('estella.audio-mixer.panel'),+ });},});diff --git a/plugins/audio-mixer/src/style.ts b/plugins/audio-mixer/src/style.tsindex 5e254d090..c5ec1c321 100644--- a/plugins/audio-mixer/src/style.ts+++ b/plugins/audio-mixer/src/style.ts@@ -49,3 +49,9 @@ export const CSS = `}.mixer-add:hover { color: var(--text); border-color: var(--acc); }`;++/** The rail glyph: three faders at three settings. `currentColor`, so the rail+ * owns hover and theme. */+export const RAIL_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"+ stroke-width="1.7" stroke-linecap="round"><path d="M6 3v18M12 3v18M18 3v18"/><path+ d="M3 8h6M9 15h6M15 6h6"/></svg>`;