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): Audio Mixer panel - the project mix is a bottom-dock tab

esenginee88fdc92ebf7
diff --git a/desktop/index.html b/desktop/index.html
index f3e262de3..f4fd70986 100644
--- a/desktop/index.html
+++ b/desktop/index.html
@@ -4,7 +4,7 @@
<meta charset="UTF-8" />
<meta
http-equiv="Content-Security-Policy"
- content="default-src 'self'; script-src 'self' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: estella:; font-src 'self' data:; connect-src 'self' ws: estella:; worker-src 'self' blob:; frame-src 'self' estella:;"
+ content="default-src 'self'; script-src 'self' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: estella:; media-src 'self' estella:; font-src 'self' data:; connect-src 'self' ws: estella:; worker-src 'self' blob:; frame-src 'self' estella:;"
/>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Estella Editor</title>
diff --git a/desktop/src/i18n/messages/index.ts b/desktop/src/i18n/messages/index.ts
index 6fe9d56ec..4506409d8 100644
--- a/desktop/src/i18n/messages/index.ts
+++ b/desktop/src/i18n/messages/index.ts
@@ -33,6 +33,7 @@ import { sequencerMessages } from './sequencer';
import { nodegraphMessages } from './nodegraph';
import { tileMessages } from './tile';
import { flipbookMessages } from './flipbook';
+import { mixerMessages } from './mixer';
import { materialMessages } from './material';
import { projectMessages } from './project';
@@ -53,6 +54,7 @@ export const messageModules = {
nodegraph: nodegraphMessages,
tile: tileMessages,
flipbook: flipbookMessages,
+ mixer: mixerMessages,
material: materialMessages,
project: projectMessages,
} as const;
@@ -73,6 +75,7 @@ export const editorMessages = {
...nodegraphMessages,
...tileMessages,
...flipbookMessages,
+ ...mixerMessages,
...materialMessages,
...projectMessages,
} as const;
diff --git a/desktop/src/i18n/messages/mixer.ts b/desktop/src/i18n/messages/mixer.ts
new file mode 100644
index 000000000..efc119d7f
--- /dev/null
+++ b/desktop/src/i18n/messages/mixer.ts
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file mixer.ts — Audio Mixer panel: bus strips, effects, ducking.
+ */
+import { defineMessages } from './types';
+
+export const mixerMessages = defineMessages({
+ 'mix.panelTitle': { en: 'Audio Mixer', zh: '音频混音器' },
+ 'mix.noProject': { en: 'Open a project to edit its mixer.', zh: '打开项目后编辑其混音器。' },
+ 'mix.mute': { en: 'Mute', zh: '静音' },
+ 'mix.addBus': { en: 'Add Bus', zh: '添加总线' },
+ 'mix.removeBus': { en: 'Remove bus', zh: '移除总线' },
+ 'mix.duckBy': { en: 'Duck by', zh: '被压低于' },
+ 'mix.duckNone': { en: '(none)', zh: '(无)' },
+ 'mix.duckAmount': { en: 'Duck level while the trigger bus is active', zh: '触发总线活跃时压低到的音量' },
+
+ 'mix.fx.add': { en: '+ Effect', zh: '+ 效果' },
+ 'mix.fx.filter': { en: 'Filter', zh: '滤波器' },
+ 'mix.fx.filterKind': { en: 'Filter type', zh: '滤波类型' },
+ 'mix.fx.reverb': { en: 'Reverb', zh: '混响' },
+ 'mix.fx.compressor': { en: 'Compressor', zh: '压缩器' },
+ 'mix.fx.seconds': { en: 'Tail s', zh: '尾音秒' },
+ 'mix.fx.wet': { en: 'Wet', zh: '湿声' },
+ 'mix.fx.ratio': { en: 'Ratio', zh: '压缩比' },
+ 'mix.fx.remove': { en: 'Remove effect', zh: '移除效果' },
+});
diff --git a/desktop/src/layout/ActivityBar.tsx b/desktop/src/layout/ActivityBar.tsx
index 15069415c..c78f85bec 100644
--- a/desktop/src/layout/ActivityBar.tsx
+++ b/desktop/src/layout/ActivityBar.tsx
@@ -86,6 +86,14 @@ export function ActivityBar() {
>
<Gauge size={19} strokeWidth={1.7} />
</button>
+ <button
+ type="button"
+ className="act"
+ title={t('mix.panelTitle')}
+ onClick={() => dockApi.revealAndExpand('audiomixer')}
+ >
+ <SlidersHorizontal size={19} strokeWidth={1.7} />
+ </button>
<span className="act-spacer" />
diff --git a/desktop/src/layout/DockLayout.tsx b/desktop/src/layout/DockLayout.tsx
index 325e02c82..7e5a4702e 100644
--- a/desktop/src/layout/DockLayout.tsx
+++ b/desktop/src/layout/DockLayout.tsx
@@ -20,6 +20,7 @@ import { GamePanel, GameClientPanel } from '@/panels/GamePanel';
import { Sequencer } from '@/panels/Sequencer';
import { TilesetEditor } from '@/panels/TilesetEditor';
import { FlipbookEditor } from '@/panels/FlipbookEditor';
+import { AudioMixerPanel } from '@/panels/AudioMixerPanel';
import { TilemapPainter } from '@/panels/TilemapPainter';
import { UIWidgetsPanel } from '@/panels/UIWidgetsPanel';
import { MaterialGraphEditor } from '@/panels/MaterialGraphEditor';
@@ -47,6 +48,7 @@ const components: Record<string, FC<IDockviewPanelProps>> = {
sequencer: () => panel('sequencer', <Sequencer />),
tileset: () => panel('tileset', <TilesetEditor />),
flipbook: () => panel('flipbook', <FlipbookEditor />),
+ audiomixer: () => panel('audiomixer', <AudioMixerPanel />),
tilemap: () => panel('tilemap', <TilemapPainter />),
uiWidgets: () => panel('uiWidgets', <UIWidgetsPanel />),
materialgraph: () => panel('materialgraph', <MaterialGraphEditor />),
@@ -114,6 +116,7 @@ function buildDefaultLayout(api: DockviewReadyEvent['api']) {
const BOTTOM_TABS: { id: string; component: string; title: string; refs: string[] }[] = [
{ id: 'sequencer', component: 'sequencer', title: t('layout.panel.sequencer'), refs: ['content', 'log'] },
{ id: 'profiler', component: 'profiler', title: t('layout.panel.profiler'), refs: ['log', 'content'] },
+ { id: 'audiomixer', component: 'audiomixer', title: t('mix.panelTitle'), refs: ['log', 'content'] },
];
function ensureBottomTabs(api: DockviewReadyEvent['api']) {
@@ -145,6 +148,7 @@ const PANEL_TITLES: Record<string, () => string> = {
game: () => t('layout.panel.game'),
tileset: () => t('tile.panelTileset'),
flipbook: () => t('fb.panelTitle'),
+ audiomixer: () => t('mix.panelTitle'),
tilemap: () => t('panel.tilemap'),
'ui-widgets': () => t('panel.uiWidgets'),
materialgraph: () => t('mat.panelTitle'),
diff --git a/desktop/src/panels/AudioMixerPanel.tsx b/desktop/src/panels/AudioMixerPanel.tsx
new file mode 100644
index 000000000..8731eacbd
--- /dev/null
+++ b/desktop/src/panels/AudioMixerPanel.tsx
@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AudioMixerPanel.tsx
+ * @brief The project mixer — one strip per bus (volume fader, mute, insert
+ * chain, duck rule) editing `project.esproject` features.audio. Every
+ * edit persists through ProjectStore.setAudio AND live-applies to the
+ * edit realm's Audio resource, so tweaks are audible immediately and
+ * Play/exports boot the same mix (the config rides the physics-config
+ * pipeline).
+ */
+
+import { useSyncExternalStore } from 'react';
+import { Plus, Trash2, VolumeX, Volume2 } from 'lucide-react';
+import {
+ Audio, applyAudioProjectConfig,
+ type AudioProjectConfig, type AudioBusDecl, type BusEffectDef,
+} from 'esengine';
+import { ProjectStore } from '@/project/ProjectStore';
+import { EngineHost } from '@/engine/EngineHost';
+import { Select } from '@/components/Select';
+import { t } from '@/i18n';
+
+/** The always-present mixer tree; custom buses append after these. */
+const DEFAULT_BUSES = ['master', 'music', 'sfx', 'ui', 'voice'];
+const DEFAULT_VOLUME: Record<string, number> = { master: 1, music: 0.8, sfx: 1, ui: 1, voice: 1 };
+
+interface StripModel extends AudioBusDecl {
+ builtin: boolean;
+}
+
+/** Default buses merged with the project declarations, declaration order kept. */
+function stripsOf(config: AudioProjectConfig): StripModel[] {
+ const byName = new Map((config.buses ?? []).map((b) => [b.name, b]));
+ const strips: StripModel[] = DEFAULT_BUSES.map((name) => ({
+ name, volume: DEFAULT_VOLUME[name], ...byName.get(name), builtin: true,
+ }));
+ for (const b of config.buses ?? []) {
+ if (!DEFAULT_BUSES.includes(b.name)) strips.push({ ...b, builtin: false });
+ }
+ return strips;
+}
+
+/** Persist + live-apply one new config state. */
+function commit(next: AudioProjectConfig): void {
+ void ProjectStore.setAudio(next);
+ const audio = EngineHost.getResource(Audio);
+ if (audio) applyAudioProjectConfig(audio, next);
+}
+
+/** Replace/patch one bus's declaration inside the config. */
+function patchBus(config: AudioProjectConfig, name: string, patch: Partial<AudioBusDecl> | null): AudioProjectConfig {
+ const buses = [...(config.buses ?? [])];
+ const i = buses.findIndex((b) => b.name === name);
+ if (patch === null) {
+ if (i >= 0) buses.splice(i, 1);
+ } else if (i >= 0) {
+ buses[i] = { ...buses[i], ...patch };
+ } else {
+ buses.push({ name, ...patch });
+ }
+ return { buses };
+}
+
+const FX_KINDS: Array<{ value: BusEffectDef['type']; label: () => string }> = [
+ { value: 'filter', label: () => t('mix.fx.filter') },
+ { value: 'reverb', label: () => t('mix.fx.reverb') },
+ { value: 'compressor', label: () => t('mix.fx.compressor') },
+];
+
+function defaultEffect(type: BusEffectDef['type']): BusEffectDef {
+ switch (type) {
+ case 'filter': return { type: 'filter', filter: 'lowpass', frequency: 1200, q: 1 };
+ case 'reverb': return { type: 'reverb', seconds: 1.5, wet: 0.35 };
+ case 'compressor': return { type: 'compressor', thresholdDb: -24, ratio: 4 };
+ }
+}
+
+function NumCell(props: { label: string; value: number; step?: number; onCommit: (n: number) => void }) {
+ return (
+ <label className="mix-num">
+ <span>{props.label}</span>
+ <input
+ type="number" defaultValue={props.value} key={props.value} step={props.step ?? 1}
+ onBlur={(e) => {
+ const n = Number(e.target.value);
+ if (Number.isFinite(n) && n !== props.value) props.onCommit(n);
+ }}
+ onKeyDown={(e) => { if (e.key === 'Enter') (e.target as HTMLInputElement).blur(); }}
+ />
+ </label>
+ );
+}
+
+function EffectRow(props: { fx: BusEffectDef; onChange: (fx: BusEffectDef) => void; onRemove: () => void }) {
+ const { fx, onChange, onRemove } = props;
+ return (
+ <div className="mix-fx">
+ <span className="mix-fx-kind">{FX_KINDS.find((k) => k.value === fx.type)?.label()}</span>
+ {fx.type === 'filter' && (
+ <>
+ <Select
+ ariaLabel={t('mix.fx.filterKind')}
+ value={fx.filter}
+ options={(['lowpass', 'highpass', 'bandpass', 'lowshelf', 'highshelf', 'peaking', 'notch'] as const)
+ .map((v) => ({ value: v, label: v }))}
+ onChange={(v) => onChange({ ...fx, filter: v })}
+ />
+ <NumCell label="Hz" value={fx.frequency} step={50} onCommit={(n) => onChange({ ...fx, frequency: Math.max(10, n) })} />
+ <NumCell label="Q" value={fx.q ?? 1} step={0.1} onCommit={(n) => onChange({ ...fx, q: n })} />
+ </>
+ )}
+ {fx.type === 'reverb' && (
+ <>
+ <NumCell label={t('mix.fx.seconds')} value={fx.seconds ?? 1.5} step={0.1} onCommit={(n) => onChange({ ...fx, seconds: Math.max(0.05, n) })} />
+ <NumCell label={t('mix.fx.wet')} value={fx.wet ?? 0.35} step={0.05} onCommit={(n) => onChange({ ...fx, wet: Math.max(0, Math.min(1, n)) })} />
+ </>
+ )}
+ {fx.type === 'compressor' && (
+ <>
+ <NumCell label="dB" value={fx.thresholdDb ?? -24} onCommit={(n) => onChange({ ...fx, thresholdDb: n })} />
+ <NumCell label={t('mix.fx.ratio')} value={fx.ratio ?? 4} step={0.5} onCommit={(n) => onChange({ ...fx, ratio: Math.max(1, n) })} />
+ </>
+ )}
+ <button type="button" className="mix-rm" title={t('mix.fx.remove')} onClick={onRemove}>
+ <Trash2 size={12} />
+ </button>
+ </div>
+ );
+}
+
+function BusStrip(props: { strip: StripModel; all: StripModel[]; config: AudioProjectConfig }) {
+ const { strip, all, config } = props;
+ const volume = strip.volume ?? 1;
+ const patch = (p: Partial<AudioBusDecl> | null) => commit(patchBus(config, strip.name, p));
+ const effects = strip.effects ?? [];
+ const duckTargets = all.filter((s) => s.name !== strip.name).map((s) => s.name);
+
+ return (
+ <div className="mix-strip">
+ <div className="mix-head">
+ <span className="mix-name">{strip.name}</span>
+ {!strip.builtin && (
+ <button type="button" className="mix-rm" title={t('mix.removeBus')} onClick={() => patch(null)}>
+ <Trash2 size={12} />
+ </button>
+ )}
+ </div>
+
+ <div className="mix-vol">
+ <input
+ type="range" min={0} max={1} step={0.01} value={volume}
+ className="mix-fader"
+ onChange={(e) => patch({ volume: Number(e.target.value) })}
+ />
+ <span className="mix-vol-num">{Math.round(volume * 100)}</span>
+ <button
+ type="button"
+ className={'mix-mute' + (strip.muted ? ' is-on' : '')}
+ title={t('mix.mute')}
+ onClick={() => patch({ muted: !strip.muted })}
+ >
+ {strip.muted ? <VolumeX size={13} /> : <Volume2 size={13} />}
+ </button>
+ </div>
+
+ <div className="mix-fxs">
+ {effects.map((fx, i) => (
+ <EffectRow
+ key={`${i}-${fx.type}`}
+ fx={fx}
+ onChange={(nf) => patch({ effects: effects.map((e, j) => (j === i ? nf : e)) })}
+ onRemove={() => patch({ effects: effects.filter((_, j) => j !== i) })}
+ />
+ ))}
+ <Select
+ ariaLabel={t('mix.fx.add')}
+ value={'' as string}
+ options={[
+ { value: '', label: t('mix.fx.add') },
+ ...FX_KINDS.map((k) => ({ value: k.value as string, label: k.label() })),
+ ]}
+ onChange={(v) => { if (v) patch({ effects: [...effects, defaultEffect(v as BusEffectDef['type'])] }); }}
+ />
+ </div>
+
+ {strip.name !== 'master' && (
+ <div className="mix-duck">
+ <span className="mix-lbl">{t('mix.duckBy')}</span>
+ <Select
+ ariaLabel={t('mix.duckBy')}
+ value={strip.duck?.trigger ?? ''}
+ options={[{ value: '', label: t('mix.duckNone') }, ...duckTargets.map((n) => ({ value: n, label: n }))]}
+ onChange={(v) => patch({ duck: v ? { trigger: v, amount: strip.duck?.amount ?? 0.3 } : undefined })}
+ />
+ {strip.duck && (
+ <input
+ type="range" min={0} max={1} step={0.05} value={strip.duck.amount}
+ className="mix-duck-amt" title={t('mix.duckAmount')}
+ onChange={(e) => patch({ duck: { ...strip.duck!, amount: Number(e.target.value) } })}
+ />
+ )}
+ </div>
+ )}
+ </div>
+ );
+}
+
+export function AudioMixerPanel() {
+ const project = useSyncExternalStore(ProjectStore.subscribe, ProjectStore.getSnapshot);
+ if (!project) {
+ return <div className="mix-empty">{t('mix.noProject')}</div>;
+ }
+ const config = ProjectStore.audioFeature();
+ const strips = stripsOf(config);
+
+ const addBus = () => {
+ let n = 1;
+ let name = 'bus';
+ while (strips.some((s) => s.name === name)) name = `bus-${n++}`;
+ commit(patchBus(config, name, { parent: 'master', volume: 1 }));
+ };
+
+ return (
+ <div className="mix-panel">
+ <div className="mix-strips">
+ {strips.map((s) => (
+ <BusStrip key={s.name} strip={s} all={strips} config={config} />
+ ))}
+ <button type="button" className="mix-add" title={t('mix.addBus')} onClick={addBus}>
+ <Plus size={14} /> {t('mix.addBus')}
+ </button>
+ </div>
+ </div>
+ );
+}
diff --git a/desktop/src/theme/settings.css b/desktop/src/theme/settings.css
index 2b927e096..c9c982c66 100644
--- a/desktop/src/theme/settings.css
+++ b/desktop/src/theme/settings.css
@@ -200,3 +200,74 @@
.set-swatch.on { box-shadow: 0 0 0 2px var(--srf-2), 0 0 0 4px var(--acc); }
/* The pill toggle is the shared `.toggle` primitive (controls.css). */
+
+/* ── Audio Mixer panel ──────────────────────────────────────────────────── */
+.mix-panel {
+ height: 100%;
+ overflow: auto;
+ background: var(--srf-1);
+ color: var(--text);
+ font-size: var(--fs-sm);
+}
+.mix-empty {
+ display: flex; align-items: center; justify-content: center;
+ height: 100%; color: var(--text-dim);
+}
+.mix-strips {
+ display: flex;
+ align-items: flex-start;
+ gap: 8px;
+ padding: 10px;
+}
+.mix-strip {
+ flex: 0 0 220px;
+ background: var(--srf-2);
+ border: 1px solid var(--line);
+ border-radius: var(--r-sm);
+ padding: 8px;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+.mix-head { display: flex; align-items: center; gap: 6px; }
+.mix-name { font-weight: 600; }
+.mix-head .mix-rm { margin-left: auto; }
+.mix-vol { display: flex; align-items: center; gap: 6px; }
+.mix-fader { flex: 1 1 auto; accent-color: var(--star); }
+.mix-vol-num {
+ width: 26px; text-align: right;
+ color: var(--text-faint); font-variant-numeric: tabular-nums; font-size: var(--fs-2xs);
+}
+.mix-mute {
+ background: none; border: 1px solid var(--line); border-radius: var(--r-sm);
+ color: var(--text-dim); padding: 2px 5px; cursor: pointer; display: inline-flex;
+}
+.mix-mute.is-on { color: var(--error-hi); border-color: var(--error-hi); }
+.mix-fxs { display: flex; flex-direction: column; gap: 4px; }
+.mix-fx {
+ display: flex; align-items: center; gap: 4px; flex-wrap: wrap;
+ background: var(--inset); border: 1px solid var(--line); border-radius: var(--r-sm);
+ padding: 3px 5px;
+}
+.mix-fx-kind { color: var(--text-dim); font-size: var(--fs-2xs); min-width: 44px; }
+.mix-num { display: inline-flex; align-items: center; gap: 3px; color: var(--text-faint); font-size: var(--fs-2xs); }
+.mix-num input {
+ width: 52px; background: var(--srf-2); border: 1px solid var(--line); border-radius: var(--r-sm);
+ color: var(--text); padding: 1px 4px; font: inherit; font-size: var(--fs-2xs);
+}
+.mix-rm {
+ background: none; border: none; color: var(--text-dim);
+ padding: 2px; cursor: pointer; display: inline-flex;
+}
+.mix-rm:hover { color: var(--error-hi); }
+.mix-duck { display: flex; align-items: center; gap: 6px; }
+.mix-lbl { color: var(--text-faint); font-size: var(--fs-2xs); }
+.mix-duck-amt { flex: 1 1 auto; accent-color: var(--star); }
+.mix-add {
+ flex: 0 0 auto;
+ display: inline-flex; align-items: center; gap: 5px;
+ background: transparent; color: var(--text-dim);
+ border: 1px dashed var(--line); border-radius: var(--r-sm);
+ padding: 8px 12px; cursor: pointer; font: inherit;
+}
+.mix-add:hover { color: var(--text); border-color: var(--line-strong); }