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(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.ts
index 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 is
diff --git a/desktop/src/layout/ActivityBar.tsx b/desktop/src/layout/ActivityBar.tsx
index 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.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.css
index 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.ts
index 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.mdx
index 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 sections
Adds a section under a component (or for an asset type), built from rows the
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 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.tsx
index 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.ts
index 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>`;