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 double-click opens the file, in the editor set up for it

esengine24405572bdbf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4d5dc26f..c1f5a4ebd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,8 +14,27 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **Double-clicking a script did nothing.** The open table only knew about editors
+ the editor ships, so every type without one — `.ts`, `.js`, `.esshader`, `.png` —
+ fell off the end of it in silence. Opening now always resolves to something: the
+ editor's own editor, then the program set for that kind of file, then whatever
+ the OS opens it with. The Content Browser's **Open** entry appeared for folders,
+ scenes and materials only, standing in for "is this openable at all?"; that
+ stopped being a real question, so it is offered for everything.
+
### Added
+- **Settings → External Tools.** Name the script editor, the image editor and the
+ browser once, and the editor hands files to them. A slot is registered rather
+ than hard-coded — an asset type declares which kind of program opens it, the way
+ it already declares its icon — so a plugin's type can say "open me the way
+ scripts are opened", or bring a slot of its own, and the settings page grows a
+ row without knowing it exists. Paths are per-user: an absolute path to an
+ executable is true of one machine, and in project settings it would be committed
+ and then be wrong for everyone else who opened the project.
+
- **The editor updates itself.** Until now an update notification could only hand
over a link: the build is unsigned, and silent auto-update needs a signature it
did not have. The check, the download and the install are now the editor's own —
diff --git a/desktop/electron/externalProgram.ts b/desktop/electron/externalProgram.ts
new file mode 100644
index 000000000..fc1d7285c
--- /dev/null
+++ b/desktop/electron/externalProgram.ts
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file externalProgram.ts
+ * @brief Hand a file to a program the user chose — the script editor, the image
+ * editor, the browser. Two operations, both of which are only interesting
+ * because of how differently the three platforms spell them.
+ *
+ * LAUNCHING. On macOS an application is a DIRECTORY (`Foo.app`), not an
+ * executable, so spawning it fails with EACCES; it has to go through
+ * `open -a`, which also reuses a running instance instead of starting a
+ * second copy. Elsewhere the path IS the executable and is spawned
+ * directly. Never through a shell: a file name containing a space, a
+ * quote or an `&` is ordinary on every platform and would be re-parsed
+ * into different arguments — or into a different command.
+ *
+ * The child is detached and its streams released, so the editor is not
+ * the parent of a long-lived Photoshop, and quitting the editor does not
+ * take the user's editor down with it.
+ */
+import { spawn } from 'node:child_process';
+import { access, constants } from 'node:fs/promises';
+import type { BrowserWindow } from 'electron';
+import { showOpenDialog } from './shotDialogs';
+
+/** Why a launch did not happen, or `null` when it did. */
+export type LaunchError = 'missing' | 'failed';
+
+/**
+ * Open `filePath` with `program`. Resolves to null on success, or a reason the
+ * caller can turn into a message — a program the user configured months ago and
+ * has since uninstalled is the common case, and it deserves better than a stack
+ * trace in the console.
+ */
+export async function launchProgram(program: string, filePath: string): Promise<LaunchError | null> {
+ try {
+ await access(program, constants.F_OK);
+ } catch {
+ return 'missing';
+ }
+
+ const [cmd, args] =
+ process.platform === 'darwin' && program.endsWith('.app')
+ ? ['/usr/bin/open', ['-a', program, filePath]]
+ : [program, [filePath]];
+
+ try {
+ const child = spawn(cmd, args, { detached: true, stdio: 'ignore', shell: false });
+ child.on('error', (err) => console.error('[external] launch failed', program, err));
+ child.unref();
+ return null;
+ } catch (err) {
+ console.error('[external] launch failed', program, err);
+ return 'failed';
+ }
+}
+
+/**
+ * Ask for a program. macOS shows `/Applications` and must be told to treat a
+ * bundle as one selectable thing rather than a folder to descend into; Windows
+ * filters to what it considers runnable. Linux has no convention worth encoding,
+ * so it gets an unfiltered picker.
+ */
+export async function pickProgram(win: BrowserWindow, title: string): Promise<string | null> {
+ const perPlatform: Partial<Electron.OpenDialogOptions> =
+ process.platform === 'darwin'
+ ? { defaultPath: '/Applications', properties: ['openFile', 'treatPackageAsDirectory'] }
+ : process.platform === 'win32'
+ ? { filters: [{ name: 'Programs', extensions: ['exe', 'bat', 'cmd'] }, { name: 'All Files', extensions: ['*'] }] }
+ : {};
+
+ const res = await showOpenDialog(win, {
+ title,
+ properties: ['openFile'],
+ ...perPlatform,
+ });
+ return res.canceled || res.filePaths.length === 0 ? null : res.filePaths[0];
+}
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index a60beb538..1140bf2c9 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -55,6 +55,7 @@ import {
PLUGIN_PACKAGE_EXT,
} from './pluginPackage';
import { findUpdate, downloadUpdate, installUpdate } from './autoUpdate';
+import { pickProgram, launchProgram, type LaunchError } from './externalProgram';
import {
listPlatforms, loadProjectPlatform, createProjectPlatform, setPlatformTrustGate,
listPlayableNetworks, loadPlayableProfile,
@@ -507,8 +508,8 @@ function createWindow() {
},
};
}
- // Everything else is an external link → OS browser, never in-app.
- if (url.startsWith('http')) shell.openExternal(url);
+ // Everything else is an external link → outside the editor, never in-app.
+ if (url.startsWith('http')) void openUrl(url);
return { action: 'deny' };
});
@@ -786,6 +787,38 @@ ipcMain.handle('shell:showItem', (_e, relPath: string) => {
});
// Open an absolute path in the OS (e.g. a build output dir the user just chose).
ipcMain.handle('shell:openPath', (_e, absPath: string) => shell.openPath(absPath));
+
+// External tools. One door for "open this project file outside the editor": the
+// path is project-relative and resolved here, like every other fs door, and an
+// EMPTY program means the OS default — so which program opens a file is data the
+// caller passes, not a second IPC it has to choose between.
+ipcMain.handle('external:pick', async (_e, title: string) => (win ? pickProgram(win, title) : null));
+
+// The browser the user named in Settings, mirrored from the renderer that owns
+// editor-scoped settings — the same shape as the dirty flag above, and for the
+// same reason: main opens urls while REACTING (a window.open it did not receive,
+// an export preview it finished), with nowhere to thread an argument through.
+let preferredBrowser = '';
+ipcMain.on('external:browser', (_e, exe: unknown) => {
+ preferredBrowser = typeof exe === 'string' ? exe : '';
+});
+
+/**
+ * Open a url outside the editor, in the chosen browser when there is one.
+ *
+ * A browser that will not start falls through to the system default rather than
+ * reporting: the user asked to follow a link, and the link is what matters — a
+ * stale preference should not be able to swallow it.
+ */
+async function openUrl(url: string): Promise<void> {
+ if (preferredBrowser && !(await launchProgram(preferredBrowser, url))) return;
+ await shell.openExternal(url);
+}
+ipcMain.handle('external:launch', async (_e, program: string, relPath: string): Promise<LaunchError | null> => {
+ const abs = resolveInRoot(requireRoot(), relPath);
+ if (!program) return (await shell.openPath(abs)) ? 'failed' : null;
+ return launchProgram(program, abs);
+});
ipcMain.handle('workspace:save', (_e, ws: WorkspaceState) => saveWorkspace(requireRoot(), ws));
// Bundle the open project's startup script (manifest scripts.main, default
@@ -960,7 +993,7 @@ ipcMain.handle(
// (blocked subresource loads, no wasm streaming) never apply. Returns the URL.
ipcMain.handle('export:preview', async (_e, absDir: string) => {
const url = await loopbackServer(absDir);
- await shell.openExternal(url);
+ await openUrl(url);
return url;
});
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index d9c09fee1..e3accf2fe 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -12,6 +12,7 @@ import type {
} from './platformCatalog';
import type { PlayRealmResult } from './buildPlayRealm';
import type { AvailableUpdate, DownloadProgress } from './autoUpdate';
+import type { LaunchError } from './externalProgram';
import type { DiscoveredPlugin, CompiledPlugin } from './pluginHost';
import type { ScaffoldPluginOptions, ScaffoldPluginResult } from './pluginScaffold';
import type { PluginPackageInfo, InstallPluginResult } from './pluginPackage';
@@ -210,6 +211,13 @@ const api = {
showItem: (relPath: string): Promise<void> => ipcRenderer.invoke('shell:showItem', relPath),
/** Open an absolute path in the OS (e.g. the build output dir). */
openPath: (absPath: string): Promise<string> => ipcRenderer.invoke('shell:openPath', absPath),
+ /** Show a picker for an external program; absolute path, or null if cancelled. */
+ pickProgram: (title: string): Promise<string | null> => ipcRenderer.invoke('external:pick', title),
+ /** Mirror the chosen browser to main, which opens urls without a call site. */
+ setBrowser: (program: string): void => ipcRenderer.send('external:browser', program),
+ /** Open a project-relative file with `program`; null on success, else why not. */
+ launchProgram: (program: string, relPath: string): Promise<LaunchError | null> =>
+ ipcRenderer.invoke('external:launch', program, relPath),
},
workspace: {
save: (ws: WorkspaceState): Promise<void> => ipcRenderer.invoke('workspace:save', ws),
diff --git a/desktop/src/components/SettingsDialog.tsx b/desktop/src/components/SettingsDialog.tsx
index 9bc7bf8d2..32dd45cf3 100644
--- a/desktop/src/components/SettingsDialog.tsx
+++ b/desktop/src/components/SettingsDialog.tsx
@@ -11,7 +11,7 @@ import { useEffect, useRef, useState } from 'react';
import type { PointerEvent as ReactPointerEvent } from 'react';
import { createPortal } from 'react-dom';
import { useShallow } from 'zustand/react/shallow';
-import { Settings as SettingsIcon, X, RotateCcw } from 'lucide-react';
+import { Settings as SettingsIcon, X, RotateCcw, FolderSearch } from 'lucide-react';
import { useEditorStore } from '@/store/editorStore';
import { useSettings } from '@/store/settingsStore';
import { settingsRegistry } from '@/settings/registry';
@@ -24,7 +24,7 @@ import { SearchField } from '@/components/SearchField';
import { Segmented } from '@/components/Segmented';
import { Select } from '@/components/Select';
import { ColorControl } from '@/components/ColorControl';
-import type { Setting, NumberSetting, KeybindingSetting, StringListSetting, MatrixSetting, FlagListSetting } from '@/settings/types';
+import type { Setting, NumberSetting, KeybindingSetting, StringListSetting, PathSetting, MatrixSetting, FlagListSetting } from '@/settings/types';
import { t } from '@/i18n';
// A bound list setting's getter returns a fresh array each call; useShallow below
@@ -146,6 +146,40 @@ function KeybindCapture({ setting }: { setting: KeybindingSetting }) {
);
}
+/**
+ * A machine-local path: type it, or browse for it. The clear button is not a
+ * reset — clearing means "use the system default", which for these is a real and
+ * often preferable answer, so it stays visible rather than hiding behind the
+ * row's changed-from-default arrow.
+ */
+function PathControl({ setting }: { setting: PathSetting }) {
+ const setValue = useSettings((s) => s.setValue);
+ const value = useSettings((s) => s.getValue<string>(setting.id) ?? '');
+ const browse = async () => {
+ const picked = await window.estella?.shell?.pickProgram?.(setting.pickTitle ?? setting.label);
+ if (picked) setValue(setting.id, picked);
+ };
+ return (
+ <div className="set-path">
+ <input
+ className="set-str"
+ value={value}
+ placeholder={setting.placeholder ?? ''}
+ spellCheck={false}
+ onChange={(e) => setValue(setting.id, e.target.value)}
+ />
+ {value && (
+ <IconButton title={t('ui.clear')} ariaLabel={t('ui.clear')} onClick={() => setValue(setting.id, '')}>
+ <X size={13} />
+ </IconButton>
+ )}
+ <IconButton title={t('ui.browse')} ariaLabel={t('ui.browse')} onClick={() => void browse()}>
+ <FolderSearch size={13} />
+ </IconButton>
+ </div>
+ );
+}
+
function StringListControl({ setting }: { setting: StringListSetting }) {
const setValue = useSettings((s) => s.setValue);
const value = useSettings(useShallow((s) => s.getValue<string[]>(setting.id) ?? (EMPTY_LIST as string[])));
@@ -316,6 +350,8 @@ function Control({ setting }: { setting: Setting }) {
onChange={(e) => setValue(setting.id, e.target.value)}
/>
);
+ case 'path':
+ return <PathControl setting={setting} />;
case 'stringList':
return <StringListControl setting={setting} />;
case 'matrix':
diff --git a/desktop/src/i18n/messages/common.ts b/desktop/src/i18n/messages/common.ts
index d11cd8d8f..60d235dc7 100644
--- a/desktop/src/i18n/messages/common.ts
+++ b/desktop/src/i18n/messages/common.ts
@@ -19,6 +19,8 @@ export const commonMessages = defineMessages({
'ui.untitled': { en: 'untitled', zh: '未命名' },
'ui.download': { en: 'Download', zh: '下载' },
'ui.restart': { en: 'Restart', zh: '重启' },
+ 'ui.browse': { en: 'Browse…', zh: '浏览…' },
+ 'ui.clear': { en: 'Clear', zh: '清除' },
'ui.reloadNow': { en: 'Reload now', zh: '立即重新加载' },
'ui.dismiss': { en: 'Dismiss', zh: '关闭' },
'ui.zoomIn': { en: 'Zoom in', zh: '放大' },
diff --git a/desktop/src/i18n/messages/settings.ts b/desktop/src/i18n/messages/settings.ts
index 47001b5c5..184d8f7f7 100644
--- a/desktop/src/i18n/messages/settings.ts
+++ b/desktop/src/i18n/messages/settings.ts
@@ -37,6 +37,29 @@ export const settingsMessages = defineMessages({
'set.section.shortcuts': { en: 'Keyboard Shortcuts', zh: '键盘快捷键' },
'set.section.console': { en: 'Console', zh: '控制台' },
'set.section.renderer': { en: 'Renderer', zh: '渲染器' },
+ 'set.section.externalTools': { en: 'External Tools', zh: '外部工具' },
+ 'toast.programMissing': {
+ en: 'Could not find {program} — it may have been moved or uninstalled',
+ zh: '找不到 {program},可能已被移动或卸载',
+ },
+ 'toast.programFailed': { en: 'Could not start {program}', zh: '无法启动 {program}' },
+ 'toast.openFailed': { en: 'No program is set up to open this file', zh: '没有可打开该文件的程序' },
+ 'set.externalTools.placeholder': { en: 'Unset — use the system default', zh: '未填写时使用系统默认程序' },
+ 'set.externalTools.script': { en: 'Script editor', zh: '默认脚本编辑器' },
+ 'set.externalTools.script.desc': {
+ en: 'Opens .ts, .js and .esshader files.',
+ zh: '用于打开 .ts、.js 和 .esshader 文件。',
+ },
+ 'set.externalTools.image': { en: 'Image editor', zh: '默认图片编辑器' },
+ 'set.externalTools.image.desc': {
+ en: 'Opens .png, .webp, .jpg and .gif files.',
+ zh: '用于打开 .png、.webp、.jpg 和 .gif 文件。',
+ },
+ 'set.externalTools.browser': { en: 'Browser', zh: '默认浏览器' },
+ 'set.externalTools.browser.desc': {
+ en: 'Opens documentation links and web build previews.',
+ zh: '用于打开文档链接和 Web 构建预览。',
+ },
'set.section.display': { en: 'Display', zh: '显示' },
'set.section.physics': { en: 'Physics', zh: '物理' },
'set.section.rendering': { en: 'Rendering', zh: '渲染' },
diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsx
index 45e831706..d0b76ee27 100644
--- a/desktop/src/panels/ContentBrowser.tsx
+++ b/desktop/src/panels/ContentBrowser.tsx
@@ -1009,9 +1009,11 @@ export function ContentBrowser() {
const isMaterial = !entry.isDir && assetType(entry.name) === 'material';
const ref = entry.isDir ? null : ProjectStore.assetRef(path);
return [
- ...(entry.isDir || isScene || isMaterial
- ? [{ label: t('cb.menuOpen'), onClick: () => onOpen(path, entry.isDir, entry.name) }]
- : []),
+ // Offered for everything, because opening now always resolves to something —
+ // an editor, the program set for that kind of file, or the OS default. The
+ // old folder/scene/material test stood in for "is this openable at all?",
+ // which stopped being a real question when the chain grew its last link.
+ { label: t('cb.menuOpen'), onClick: () => onOpen(path, entry.isDir, entry.name) },
// The startup scene: what the editor opens, Play boots, and exports ship
// first. One per project — the current one offers no redundant action,
// and it can't be excluded from export (it IS the export's boot scene).
diff --git a/desktop/src/project/assetOpen.ts b/desktop/src/project/assetOpen.ts
index 3f7d43dcb..652962b5c 100644
--- a/desktop/src/project/assetOpen.ts
+++ b/desktop/src/project/assetOpen.ts
@@ -8,10 +8,13 @@
* openers); folding them into the registry would create import cycles.
*/
import type { AssetType } from '@/types';
-import { assetTypeRegistry } from './assetTypes';
+import { assetTypeRegistry, assetTypeDef } from './assetTypes';
import { ProjectStore } from './ProjectStore';
import { confirmDiscard } from './discardGuard';
import { t } from '@/i18n';
+import { Toasts } from '@/store/Toasts';
+import { useEditorStore } from '@/store/editorStore';
+import { externalPrograms } from './externalPrograms';
import { toggleAudioPreview } from './audioPreview';
import { openAnimationClip } from '@/timeline/openClip';
import { openFlipbook } from '@/flipbook/openFlipbook';
@@ -38,7 +41,36 @@ export function openAssetOfType(type: AssetType, path: string, name: string): bo
contributed.open(path);
return true;
}
- return false;
+ void openOutside(type, path);
+ return true;
+}
+
+/**
+ * Hand a file to something outside the editor: the program configured for its
+ * kind, else whatever the OS opens it with.
+ *
+ * This is the end of the chain, and it always does something — which is the point.
+ * A double-click that silently did nothing was the whole bug: the editor has no
+ * script editor and no image editor, so every `.ts` and every `.png` fell off the
+ * end of a table that only knew about editors this editor ships.
+ */
+async function openOutside(type: AssetType, path: string): Promise<void> {
+ const slot = assetTypeDef(type).externalProgram;
+ // Empty = the OS default, which is the right answer for a kind with no slot and
+ // for a slot the user has deliberately left unset.
+ const program = slot ? externalPrograms.pathFor(slot) : '';
+ const failure = await window.estella?.shell?.launchProgram?.(program, path);
+ if (!failure) return;
+ if (!program) {
+ Toasts.push(t('toast.openFailed'), 'error');
+ return;
+ }
+ // Configured months ago, uninstalled since. Say which program, and offer the
+ // one action that fixes it rather than making the user hunt for the setting.
+ Toasts.push(t(failure === 'missing' ? 'toast.programMissing' : 'toast.programFailed', { program }), 'error', 6000, {
+ label: t('set.title'),
+ run: () => useEditorStore.getState().openSettings('externalTools'),
+ });
}
/** Open action per built-in asset type; types absent here aren't double-click-openable. */
diff --git a/desktop/src/project/assetTypes.ts b/desktop/src/project/assetTypes.ts
index 089d220b0..e8407f483 100644
--- a/desktop/src/project/assetTypes.ts
+++ b/desktop/src/project/assetTypes.ts
@@ -32,6 +32,12 @@ export interface AssetTypeDef {
badge: string;
icon: LucideIcon;
tint: string;
+ /**
+ * External program slot that opens this type when the editor has no editor of
+ * its own for it (see project/externalPrograms.ts). Declared here for the same
+ * reason the icon is: it is a property of the type, not of the program.
+ */
+ externalProgram?: string;
}
// Desaturated tints (vs candy colors) so the content browser stays scannable by
@@ -39,8 +45,8 @@ export interface AssetTypeDef {
export const ASSET_TYPES: Record<BuiltinAssetType, AssetTypeDef> = {
folder: { badge: '', icon: Folder, tint: 'var(--star)' },
scene: { extensions: ['esscene'], badge: 'SCN', icon: Film, tint: '#c98a93' },
- texture: { extensions: ['png', 'webp'], badge: 'TEX', icon: FileImage, tint: '#7fa6c4' },
- sprite: { extensions: ['jpg', 'jpeg', 'gif'], badge: 'IMG', icon: Image, tint: '#7fa6c4' },
+ texture: { extensions: ['png', 'webp'], badge: 'TEX', icon: FileImage, tint: '#7fa6c4', externalProgram: 'image' },
+ sprite: { extensions: ['jpg', 'jpeg', 'gif'], badge: 'IMG', icon: Image, tint: '#7fa6c4', externalProgram: 'image' },
spine: { extensions: ['atlas', 'skel'], badge: 'SPN', icon: PersonStanding, tint: '#9b8fc0' },
audio: { extensions: ['ogg', 'mp3', 'wav', 'aac', 'flac', 'm4a', 'webm'], badge: 'AUD', icon: Music, tint: '#7faf9c' },
video: { extensions: ['mp4', 'm4v', 'mov'], badge: 'VID', icon: Video, tint: '#c08fb5' },
@@ -51,8 +57,8 @@ export const ASSET_TYPES: Record<BuiltinAssetType, AssetTypeDef> = {
materialgraph: { extensions: ['esmatgraph'], badge: 'MGR', icon: Workflow, tint: '#c0917a' },
// A `.esshader` is the fragment-shader source (with #pragma param declarations) a material
// references; recognizable here so it never reads as a mystery "file" next to its material.
- shader: { extensions: ['esshader'], badge: 'SHD', icon: Sparkles, tint: '#c9a26a' },
- script: { extensions: ['ts', 'js'], badge: 'TS', icon: FileCode2, tint: '#93a3bf' },
+ shader: { extensions: ['esshader'], badge: 'SHD', icon: Sparkles, tint: '#c9a26a', externalProgram: 'script' },
+ script: { extensions: ['ts', 'js'], badge: 'TS', icon: FileCode2, tint: '#93a3bf', externalProgram: 'script' },
// Two animation documents, two editors: .estimeline is the Sequencer's
// multi-track timeline; .esanim is the sprite flipbook (Flipbook editor).
animation: { extensions: ['estimeline'], badge: 'SEQ', icon: Clapperboard, tint: '#9bb39a' },
diff --git a/desktop/src/project/externalPrograms.ts b/desktop/src/project/externalPrograms.ts
new file mode 100644
index 000000000..e48ae22ad
--- /dev/null
+++ b/desktop/src/project/externalPrograms.ts
@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file externalPrograms.ts
+ * @brief Which outside program opens which kind of file. The editor has no
+ * script editor and no image editor and should not grow one — but a
+ * double-click has to do SOMETHING, so the answer is a program the user
+ * already has, named once in Settings.
+ *
+ * A slot is registered, not hard-coded, for the reason every other table
+ * here is a registry: a contributed asset type must be able to say "open
+ * me the way scripts are opened" — or to bring its own slot — without the
+ * settings UI knowing it exists. Registering a slot registers its setting
+ * in the same call and retracts both together, so a slot without a
+ * setting, or a setting nobody reads, cannot happen.
+ *
+ * The value is editor-scoped on purpose. `C:\...\Code.exe` is true of one
+ * machine; in project settings it would be committed and then be wrong for
+ * everyone else who opened the project.
+ */
+import { settingsRegistry } from '@/settings/registry';
+import { ContributionRegistry, type Disposable, type Owner } from '@/contrib/ContributionRegistry';
+import { useSettings } from '@/store/settingsStore';
+import { t } from '@/i18n';
+
+export interface ExternalProgram {
+ /** Stable slot id, referenced by AssetTypeDef.externalProgram. */
+ id: string;
+ label: string;
+ description?: string;
+ /** Push the value somewhere on change + on hydrate (see the browser slot). */
+ effect?: (program: string) => void;
+}
+
+/** The setting id a slot's configured path is stored under. */
+export const programSettingId = (id: string): string => `externalTools.${id}`;
+
+class ExternalProgramRegistry {
+ private readonly programs = new ContributionRegistry<ExternalProgram>('external program');
+
+ /** Register a slot and the setting that fills it. Disposing retracts both. */
+ register(program: ExternalProgram, owner: Owner = 'core'): Disposable {
+ const slot = this.programs.register(owner, program);
+ const setting = settingsRegistry.register(
+ {
+ id: programSettingId(program.id),
+ type: 'path',
+ scope: 'editor',
+ section: 'externalTools',
+ label: program.label,
+ description: program.description,
+ default: '',
+ placeholder: t('set.externalTools.placeholder'),
+ pickTitle: program.label,
+ effect: program.effect,
+ },
+ owner,
+ );
+ return {
+ dispose: () => {
+ slot.dispose();
+ setting.dispose();
+ },
+ };
+ }
+
+ get(id: string): ExternalProgram | undefined {
+ return this.programs.get(id);
+ }
+
+ all(): ExternalProgram[] {
+ return [...this.programs.all()];
+ }
+
+ /** The configured path for a slot, or '' when the user has named none. */
+ pathFor(id: string): string {
+ return useSettings.getState().getValue<string>(programSettingId(id)) ?? '';
+ }
+}
+
+export const externalPrograms = new ExternalProgramRegistry();
+
+// ── The built-in slots ──────────────────────────────────────────────────────
+// Three, because three is what the editor genuinely cannot do itself. Anything
+// with an editor of its own (scenes, materials, tilemaps) never reaches here.
+externalPrograms.register({
+ id: 'script',
+ label: t('set.externalTools.script'),
+ description: t('set.externalTools.script.desc'),
+});
+externalPrograms.register({
+ id: 'image',
+ label: t('set.externalTools.image'),
+ description: t('set.externalTools.image.desc'),
+});
+// The browser is the one slot the renderer does not use itself: main opens urls
+// while reacting to a window.open or finishing an export preview, so it needs its
+// own copy of the value rather than a call site to read it.
+externalPrograms.register({
+ id: 'browser',
+ label: t('set.externalTools.browser'),
+ description: t('set.externalTools.browser.desc'),
+ effect: (program) => window.estella?.shell?.setBrowser?.(program),
+});
diff --git a/desktop/src/settings/editorSettings.ts b/desktop/src/settings/editorSettings.ts
index 047a4d41c..c24a18fca 100644
--- a/desktop/src/settings/editorSettings.ts
+++ b/desktop/src/settings/editorSettings.ts
@@ -28,6 +28,9 @@ settingsRegistry.registerSection({ id: 'performance', label: t('set.section.perf
settingsRegistry.registerSection({ id: 'shortcuts', label: t('set.section.shortcuts'), category: 'editor', order: 4 });
settingsRegistry.registerSection({ id: 'console', label: t('set.section.console'), category: 'editor', order: 5 });
settingsRegistry.registerSection({ id: 'renderer', label: t('set.section.renderer'), category: 'editor', order: 6 });
+// The rows under it are registered by externalPrograms.ts — one per program slot,
+// so a contributed slot appears here without this file knowing it exists.
+settingsRegistry.registerSection({ id: 'externalTools', label: t('set.section.externalTools'), category: 'editor', order: 7 });
// ── Appearance (store-owned, applied via CSS) ───────────────────────────────
// The session renders in the locale resolved at boot from this same persisted
diff --git a/desktop/src/settings/types.ts b/desktop/src/settings/types.ts
index a51ce0af8..913a8c5c9 100644
--- a/desktop/src/settings/types.ts
+++ b/desktop/src/settings/types.ts
@@ -70,6 +70,18 @@ export interface StringSetting extends BaseSetting<string> {
placeholder?: string;
}
+/**
+ * An absolute path to something on THIS machine, picked from a dialog or typed.
+ * Empty means "unset", which every reader is expected to have an answer for —
+ * these name a convenience, not a requirement.
+ */
+export interface PathSetting extends BaseSetting<string> {
+ type: 'path';
+ placeholder?: string;
+ /** Title of the picker dialog. */
+ pickTitle?: string;
+}
+
export interface ColorSetting extends BaseSetting<string> {
type: 'color';
/** Preset swatches (hex). */
@@ -126,6 +138,7 @@ export type Setting =
| NumberSetting
| EnumSetting
| StringSetting
+ | PathSetting
| ColorSetting
| ColorPickerSetting
| KeybindingSetting
diff --git a/desktop/src/theme/settings.css b/desktop/src/theme/settings.css
index 12a481917..c2c3fbc4e 100644
--- a/desktop/src/theme/settings.css
+++ b/desktop/src/theme/settings.css
@@ -151,6 +151,11 @@
.set-str { width: 200px; height: 24px; background: var(--inset); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 0 7px; color: var(--text); font-size: var(--fs-xs); font-family: var(--mono); outline: none; }
.set-str:focus { border-color: var(--acc); box-shadow: 0 0 0 2px var(--acc-soft); }
.set-str::placeholder { color: var(--text-mute); font-family: var(--sans, inherit); }
+/* A path row is wider than a plain string: an absolute program path is long, and
+ truncating the interesting end of it (the executable's name) is what makes the
+ Cocos-style field hard to read at a glance. */
+.set-path { display: flex; align-items: center; gap: 4px; }
+.set-path .set-str { width: 300px; }
.set-reset { width: 16px; height: 16px; display: grid; place-items: center; color: var(--warn); opacity: 0; }
.set-row:hover .set-reset.show, .set-row.changed .set-reset.show { opacity: 0.85; }
.set-reset.show { cursor: pointer; }
diff --git a/desktop/tests/external-programs.test.ts b/desktop/tests/external-programs.test.ts
new file mode 100644
index 000000000..545abd952
--- /dev/null
+++ b/desktop/tests/external-programs.test.ts
@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// A double-click that silently does nothing was the bug these cover. Two ways it
+// comes back: a type that names no program (so it falls off the end of the table),
+// and a type that names one nobody registered (so it resolves to "unset" forever
+// and looks exactly like a user who never configured anything).
+import { describe, it, expect } from 'vitest';
+import { externalPrograms, programSettingId } from '@/project/externalPrograms';
+import { settingsRegistry } from '@/settings/registry';
+import { ASSET_TYPES } from '@/project/assetTypes';
+import { ASSET_OPEN } from '@/project/assetOpen';
+import type { AssetType } from '@/types';
+
+describe('the external program registry', () => {
+ it('gives every slot a setting to fill it', () => {
+ for (const program of externalPrograms.all()) {
+ const setting = settingsRegistry.get(programSettingId(program.id));
+ expect(setting, `no setting for slot ${program.id}`).toBeDefined();
+ expect(setting?.type).toBe('path');
+ // An absolute program path is true of ONE machine. In project scope it would
+ // be committed and then be wrong for everyone else who opened the project.
+ expect(setting?.scope).toBe('editor');
+ expect(setting?.section).toBe('externalTools');
+ }
+ });
+
+ it('registers and retracts a slot and its setting together', () => {
+ const id = 'test.diff';
+ const disposable = externalPrograms.register({ id, label: 'Diff tool' }, 'test-owner');
+ expect(externalPrograms.get(id)).toBeDefined();
+ expect(settingsRegistry.get(programSettingId(id))).toBeDefined();
+
+ disposable.dispose();
+ expect(externalPrograms.get(id)).toBeUndefined();
+ // The half that used to be easy to forget: a setting nobody reads, left in the
+ // dialog by a plugin that unloaded.
+ expect(settingsRegistry.get(programSettingId(id))).toBeUndefined();
+ });
+
+ it('reports an unconfigured slot as empty, not undefined', () => {
+ // '' is what the open chain reads as "use the OS default" — an undefined here
+ // would reach launchProgram as the string "undefined".
+ expect(externalPrograms.pathFor('script')).toBe('');
+ expect(externalPrograms.pathFor('no-such-slot')).toBe('');
+ });
+});
+
+describe('what opens each asset type', () => {
+ const types = Object.entries(ASSET_TYPES) as [AssetType, (typeof ASSET_TYPES)[keyof typeof ASSET_TYPES]][];
+
+ it('never names a program slot that does not exist', () => {
+ for (const [type, def] of types) {
+ if (!def.externalProgram) continue;
+ expect(externalPrograms.get(def.externalProgram), `${type} names an unregistered slot`).toBeDefined();
+ }
+ });
+
+ it('hands source and images to an outside program, having no editor for them', () => {
+ // The reported bug, as an assertion: `script` had neither an entry in
+ // ASSET_OPEN nor a program, so double-clicking a .ts did nothing at all.
+ for (const type of ['script', 'shader', 'texture', 'sprite'] as const) {
+ expect(ASSET_OPEN[type], `${type} unexpectedly grew an internal editor`).toBeUndefined();
+ expect(ASSET_TYPES[type].externalProgram, `${type} opens nothing`).toBeTruthy();
+ }
+ });
+});