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.

refactor(editor): one openGraphAsset door behind the three graph openers

esengine526ed73b6c08
diff --git a/desktop/src/animator/openAnimatorController.ts b/desktop/src/animator/openAnimatorController.ts
index 24d08dc07..3774f946b 100644
--- a/desktop/src/animator/openAnimatorController.ts
+++ b/desktop/src/animator/openAnimatorController.ts
@@ -3,54 +3,24 @@
/**
* @file openAnimatorController.ts
* @brief Open / create a `.esanimator` (the animation controller state machine).
- * @details A `.esanimator` IS the runtime AnimatorControllerDef (states carry x/y
- * layout the interpreter ignores), so there is no compile step — Save
- * just writes the JSON. Create writes the definition + .meta.
*/
import { emptyAnimatorController } from 'esengine';
import { AnimatorGraphDocument } from './AnimatorGraphDocument';
-import { ProjectStore } from '@/project/ProjectStore';
-import { confirmDiscardDoc } from '@/project/discardGuard';
-import { dockApi } from '@/layout/dockApi';
-import { baseName } from '@/project/assetMeta';
-import { Toasts } from '@/store/Toasts';
-import { t } from '@/i18n';
+import { type GraphAssetKind, openGraphAsset, createGraphAsset } from '@/document/openGraphAsset';
+
+const ANIMATOR: GraphAssetKind = {
+ document: AnimatorGraphDocument,
+ panelId: 'animatorcontroller',
+ titleKey: 'anim.tabTitle',
+ ext: 'esanimator',
+ defaultName: 'NewAnimator',
+ metaType: 'animatorcontroller',
+ emptyDef: emptyAnimatorController,
+ toast: { openFailed: 'anim.toastOpenFailed', createFailed: 'anim.toastCreateFailed', created: 'anim.toastCreated' },
+};
/** Open an existing `.esanimator` into the controller editor and reveal the panel. */
-export async function openAnimatorController(path: string): Promise<void> {
- // Already-open file: just front the panel — a reload would clobber unsaved edits.
- if (AnimatorGraphDocument.isOpen && AnimatorGraphDocument.filePath === path) {
- dockApi.openDocument('animatorcontroller', 'animatorcontroller', t('anim.tabTitle'));
- return;
- }
- if (!(await confirmDiscardDoc(AnimatorGraphDocument.dirty, t('discard.openAsset', { name: baseName(path) })))) return;
- try {
- const text = await window.estella.fs.read(path);
- AnimatorGraphDocument.openJson(JSON.parse(text), path);
- dockApi.openDocument('animatorcontroller', 'animatorcontroller', t('anim.tabTitle'));
- } catch (e) {
- Toasts.push(t('anim.toastOpenFailed', { error: String(e) }), 'error');
- }
-}
+export const openAnimatorController = (path: string): Promise<void> => openGraphAsset(ANIMATOR, path);
/** Create a new `.esanimator` (+ .meta) in @p dir, then open it. */
-export async function createAnimatorController(dir: string): Promise<void> {
- const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';
- let rel = `${folder}NewAnimator.esanimator`;
- for (let n = 1; ProjectStore.assetRef(rel); n++) rel = `${folder}NewAnimator-${n}.esanimator`;
-
- const def = emptyAnimatorController();
- try {
- await window.estella.fs.write(rel, JSON.stringify(def, null, 2) + '\n');
- await window.estella.fs.write(
- rel + '.meta',
- JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'animatorcontroller', importer: { autoMigrate: true } }, null, 2) + '\n',
- );
- } catch (e) {
- Toasts.push(t('anim.toastCreateFailed', { error: String(e) }), 'error');
- return;
- }
- await ProjectStore.refreshAssets();
- Toasts.push(t('anim.toastCreated', { name: baseName(rel) }), 'info');
- await openAnimatorController(rel);
-}
+export const createAnimatorController = (dir: string): Promise<void> => createGraphAsset(ANIMATOR, dir);
diff --git a/desktop/src/bt/openBehaviorTree.ts b/desktop/src/bt/openBehaviorTree.ts
index 05b086a1f..4336bca08 100644
--- a/desktop/src/bt/openBehaviorTree.ts
+++ b/desktop/src/bt/openBehaviorTree.ts
@@ -2,52 +2,27 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file openBehaviorTree.ts
- * @brief Open / create a `.esbt` (the visual behavior tree, AI3). A `.esbt` IS
- * the runtime BtDefinition, so there is no compile step — Save writes JSON.
+ * @brief Open / create a `.esbt` (the visual behavior tree, AI3).
*/
import { emptyBt, ensureBtIds, type BtDefinition } from 'esengine';
import { BtDocument } from './BtDocument';
-import { ProjectStore } from '@/project/ProjectStore';
-import { confirmDiscardDoc } from '@/project/discardGuard';
-import { dockApi } from '@/layout/dockApi';
-import { baseName } from '@/project/assetMeta';
-import { Toasts } from '@/store/Toasts';
-import { t } from '@/i18n';
+import { type GraphAssetKind, openGraphAsset, createGraphAsset } from '@/document/openGraphAsset';
-export async function openBehaviorTree(path: string): Promise<void> {
- // Already-open file: just front the panel — a reload would clobber unsaved edits.
- if (BtDocument.isOpen && BtDocument.filePath === path) {
- dockApi.openDocument('behaviortree', 'behaviortree', t('bt.tabTitle'));
- return;
- }
- if (!(await confirmDiscardDoc(BtDocument.dirty, t('discard.openAsset', { name: baseName(path) })))) return;
- try {
- const text = await window.estella.fs.read(path);
- // Hand-written trees may lack editor ids; assign before editing.
- BtDocument.openJson(ensureBtIds(JSON.parse(text) as BtDefinition), path);
- dockApi.openDocument('behaviortree', 'behaviortree', t('bt.tabTitle'));
- } catch (e) {
- Toasts.push(t('bt.toastOpenFailed', { error: String(e) }), 'error');
- }
-}
+const BT: GraphAssetKind = {
+ document: BtDocument,
+ panelId: 'behaviortree',
+ titleKey: 'bt.tabTitle',
+ ext: 'esbt',
+ defaultName: 'NewBehaviorTree',
+ metaType: 'behaviortree',
+ emptyDef: emptyBt,
+ // Hand-written trees may lack editor ids; assign before editing.
+ parse: (json) => ensureBtIds(json as BtDefinition),
+ toast: { openFailed: 'bt.toastOpenFailed', createFailed: 'bt.toastCreateFailed', created: 'bt.toastCreated' },
+};
-export async function createBehaviorTree(dir: string): Promise<void> {
- const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';
- let rel = `${folder}NewBehaviorTree.esbt`;
- for (let n = 1; ProjectStore.assetRef(rel); n++) rel = `${folder}NewBehaviorTree-${n}.esbt`;
+/** Open an existing `.esbt` into the behavior-tree editor and reveal the panel. */
+export const openBehaviorTree = (path: string): Promise<void> => openGraphAsset(BT, path);
- const def = emptyBt();
- try {
- await window.estella.fs.write(rel, JSON.stringify(def, null, 2) + '\n');
- await window.estella.fs.write(
- rel + '.meta',
- JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'behaviortree', importer: { autoMigrate: true } }, null, 2) + '\n',
- );
- } catch (e) {
- Toasts.push(t('bt.toastCreateFailed', { error: String(e) }), 'error');
- return;
- }
- await ProjectStore.refreshAssets();
- Toasts.push(t('bt.toastCreated', { name: baseName(rel) }), 'info');
- await openBehaviorTree(rel);
-}
+/** Create a new `.esbt` (+ .meta) in @p dir, then open it. */
+export const createBehaviorTree = (dir: string): Promise<void> => createGraphAsset(BT, dir);
diff --git a/desktop/src/document/openGraphAsset.ts b/desktop/src/document/openGraphAsset.ts
new file mode 100644
index 000000000..c5e6b1de8
--- /dev/null
+++ b/desktop/src/document/openGraphAsset.ts
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file openGraphAsset.ts
+ * @brief Open / create a graph-shaped asset — the shared door behind
+ * openStateMachine / openAnimatorController / openBehaviorTree.
+ * @details A `.esfsm` / `.esanimator` / `.esbt` all IS their runtime definition
+ * (nodes carry x/y layout the interpreter ignores), so there is no
+ * compile step — Save just writes the JSON, Create writes the
+ * definition + .meta. The three differ only by their document, panel,
+ * format factory, extension, and toast strings — a {@link GraphAssetKind}.
+ */
+import { ProjectStore } from '@/project/ProjectStore';
+import { confirmDiscardDoc } from '@/project/discardGuard';
+import { dockApi } from '@/layout/dockApi';
+import { baseName } from '@/project/assetMeta';
+import { Toasts } from '@/store/Toasts';
+import { t, type MsgKey } from '@/i18n';
+
+/** The open/reveal surface of a graph document singleton (see AssetDocument). */
+export interface GraphDocument {
+ readonly isOpen: boolean;
+ readonly filePath: string | null;
+ readonly dirty: boolean;
+ openJson(raw: unknown, filePath: string | null): void;
+}
+
+export interface GraphAssetKind {
+ document: GraphDocument;
+ /** dockview panel id (also serves as its component type). */
+ panelId: string;
+ /** i18n key for the panel tab title. */
+ titleKey: MsgKey;
+ /** File extension without the dot (e.g. `esfsm`). */
+ ext: string;
+ /** Base name for a freshly created asset (e.g. `NewStateMachine`). */
+ defaultName: string;
+ /** `.meta` type minted for a created asset. */
+ metaType: string;
+ /** A blank definition for a newly created asset. */
+ emptyDef(): unknown;
+ /** Normalize parsed JSON before it enters the document (e.g. assign BT ids). */
+ parse?(json: unknown): unknown;
+ toast: { openFailed: MsgKey; createFailed: MsgKey; created: MsgKey };
+}
+
+/** Open an existing graph asset into its editor and reveal the panel. */
+export async function openGraphAsset(kind: GraphAssetKind, path: string): Promise<void> {
+ const front = (): void => dockApi.openDocument(kind.panelId, kind.panelId, t(kind.titleKey));
+ // Already-open file: just front the panel — a reload would clobber unsaved edits.
+ if (kind.document.isOpen && kind.document.filePath === path) {
+ front();
+ return;
+ }
+ if (!(await confirmDiscardDoc(kind.document.dirty, t('discard.openAsset', { name: baseName(path) })))) return;
+ try {
+ const json: unknown = JSON.parse(await window.estella.fs.read(path));
+ kind.document.openJson(kind.parse ? kind.parse(json) : json, path);
+ front();
+ } catch (e) {
+ Toasts.push(t(kind.toast.openFailed, { error: String(e) }), 'error');
+ }
+}
+
+/** Create a new graph asset (+ .meta) in @p dir, then open it. */
+export async function createGraphAsset(kind: GraphAssetKind, dir: string): Promise<void> {
+ const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';
+ let rel = `${folder}${kind.defaultName}.${kind.ext}`;
+ for (let n = 1; ProjectStore.assetRef(rel); n++) rel = `${folder}${kind.defaultName}-${n}.${kind.ext}`;
+
+ try {
+ await window.estella.fs.write(rel, JSON.stringify(kind.emptyDef(), null, 2) + '\n');
+ await window.estella.fs.write(
+ rel + '.meta',
+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: kind.metaType, importer: { autoMigrate: true } }, null, 2) + '\n',
+ );
+ } catch (e) {
+ Toasts.push(t(kind.toast.createFailed, { error: String(e) }), 'error');
+ return;
+ }
+ await ProjectStore.refreshAssets();
+ Toasts.push(t(kind.toast.created, { name: baseName(rel) }), 'info');
+ await openGraphAsset(kind, rel);
+}
diff --git a/desktop/src/fsm/openStateMachine.ts b/desktop/src/fsm/openStateMachine.ts
index fea14ca31..ec8bac29e 100644
--- a/desktop/src/fsm/openStateMachine.ts
+++ b/desktop/src/fsm/openStateMachine.ts
@@ -3,54 +3,24 @@
/**
* @file openStateMachine.ts
* @brief Open / create a `.esfsm` (the visual state machine, AI2).
- * @details A `.esfsm` IS the runtime FsmDefinition (states carry x/y layout the
- * interpreter ignores), so there is no compile step — Save (in the
- * editor) just writes the JSON. Create writes the definition + .meta.
*/
import { emptyFsm } from 'esengine';
import { FsmGraphDocument } from './FsmGraphDocument';
-import { ProjectStore } from '@/project/ProjectStore';
-import { confirmDiscardDoc } from '@/project/discardGuard';
-import { dockApi } from '@/layout/dockApi';
-import { baseName } from '@/project/assetMeta';
-import { Toasts } from '@/store/Toasts';
-import { t } from '@/i18n';
+import { type GraphAssetKind, openGraphAsset, createGraphAsset } from '@/document/openGraphAsset';
+
+const FSM: GraphAssetKind = {
+ document: FsmGraphDocument,
+ panelId: 'statemachine',
+ titleKey: 'fsm.tabTitle',
+ ext: 'esfsm',
+ defaultName: 'NewStateMachine',
+ metaType: 'statemachine',
+ emptyDef: emptyFsm,
+ toast: { openFailed: 'fsm.toastOpenFailed', createFailed: 'fsm.toastCreateFailed', created: 'fsm.toastCreated' },
+};
/** Open an existing `.esfsm` into the state-machine editor and reveal the panel. */
-export async function openStateMachine(path: string): Promise<void> {
- // Already-open file: just front the panel — a reload would clobber unsaved edits.
- if (FsmGraphDocument.isOpen && FsmGraphDocument.filePath === path) {
- dockApi.openDocument('statemachine', 'statemachine', t('fsm.tabTitle'));
- return;
- }
- if (!(await confirmDiscardDoc(FsmGraphDocument.dirty, t('discard.openAsset', { name: baseName(path) })))) return;
- try {
- const text = await window.estella.fs.read(path);
- FsmGraphDocument.openJson(JSON.parse(text), path);
- dockApi.openDocument('statemachine', 'statemachine', t('fsm.tabTitle'));
- } catch (e) {
- Toasts.push(t('fsm.toastOpenFailed', { error: String(e) }), 'error');
- }
-}
+export const openStateMachine = (path: string): Promise<void> => openGraphAsset(FSM, path);
/** Create a new `.esfsm` (+ .meta) in @p dir, then open it. */
-export async function createStateMachine(dir: string): Promise<void> {
- const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';
- let rel = `${folder}NewStateMachine.esfsm`;
- for (let n = 1; ProjectStore.assetRef(rel); n++) rel = `${folder}NewStateMachine-${n}.esfsm`;
-
- const def = emptyFsm();
- try {
- await window.estella.fs.write(rel, JSON.stringify(def, null, 2) + '\n');
- await window.estella.fs.write(
- rel + '.meta',
- JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'statemachine', importer: { autoMigrate: true } }, null, 2) + '\n',
- );
- } catch (e) {
- Toasts.push(t('fsm.toastCreateFailed', { error: String(e) }), 'error');
- return;
- }
- await ProjectStore.refreshAssets();
- Toasts.push(t('fsm.toastCreated', { name: baseName(rel) }), 'info');
- await openStateMachine(rel);
-}
+export const createStateMachine = (dir: string): Promise<void> => createGraphAsset(FSM, dir);