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(inspector): spine animation/skin dropdowns via per-entity dynamic enums

esengine03039a85d6f0
diff --git a/desktop/src/engine/EditorSession.ts b/desktop/src/engine/EditorSession.ts
index 6ef1732a0..23a639dbb 100644
--- a/desktop/src/engine/EditorSession.ts
+++ b/desktop/src/engine/EditorSession.ts
@@ -8,6 +8,7 @@ import { SceneCommands, SceneCommandsImpl } from './SceneCommands';
import { SceneQuery, SceneQueryImpl } from './SceneQuery';
import { useSelection, createSelectionStore, type SelectionStore } from '@/store/selectionStore';
import { EditorControlSurfaceImpl } from './EditorControlSurface';
+import './spineEnums'; // side effect: register spine animation/skin dynamic enums
/**
* The single editor boundary. One instance owns
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 006189fcd..721d90723 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -16,6 +16,7 @@ import {
setPlayMode,
} from 'esengine';
import type { App, ESEngineModule, ResourceDef, SubsystemStatus, SceneData } from 'esengine';
+import { SpinePlugin } from 'esengine/spine';
import { SceneLoader } from './SceneLoader';
import { loadEditorSpine } from './spineLoad';
import { checkEngineBuild } from './EngineGuard';
@@ -92,6 +93,14 @@ class EngineHostImpl {
getResource<T>(resource: ResourceDef<T>): T | undefined {
return this.app_?.getResource(resource);
}
+ /** Animation names of a spine entity's loaded skeleton (for the inspector dropdown); empty if none. */
+ spineAnimations(runtimeId: number): string[] {
+ return this.app_?.getPlugin(SpinePlugin)?.spineManager?.getAnimations(runtimeId as never) ?? [];
+ }
+ /** Skin names of a spine entity's loaded skeleton; empty if none. */
+ spineSkins(runtimeId: number): string[] {
+ return this.app_?.getPlugin(SpinePlugin)?.spineManager?.getSkins(runtimeId as never) ?? [];
+ }
get module(): ESEngineModule | null {
return this.module_;
}
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index f61a15337..c1f1c2227 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -266,6 +266,23 @@ export function animatableFieldsFor(compType: string): readonly string[] {
return userSchema(compType)?.animatableFields ?? [];
}
+// — Per-entity dynamic enums —
+// Some string fields are really a choice from a list that depends on the entity's
+// runtime state, not a static enum (e.g. a spine animation/skin name from the loaded
+// skeleton). A provider, keyed by `component|field`, yields the options for one
+// entity; the inspector renders a dropdown when it returns any.
+const dynamicEnums = new Map<string, (sourceId: number) => readonly string[]>();
+
+export function registerDynamicEnum(component: string, field: string, provider: (sourceId: number) => readonly string[]): void {
+ dynamicEnums.set(`${component}|${field}`, provider);
+}
+
+/** Dynamic enum options for a field on an entity, or null if the field has no provider / no options. */
+export function dynamicEnumOptions(component: string, field: string, sourceId: number): string[] | null {
+ const opts = dynamicEnums.get(`${component}|${field}`)?.(sourceId);
+ return opts && opts.length ? [...opts] : null;
+}
+
// — Field presentation metadata (the SDK's UPROPERTY analog) —
//
// A component declares per-field editor policy (enum options, numeric range,
diff --git a/desktop/src/engine/spineEnums.ts b/desktop/src/engine/spineEnums.ts
new file mode 100644
index 000000000..cf7595559
--- /dev/null
+++ b/desktop/src/engine/spineEnums.ts
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spineEnums.ts
+ * @brief Registers the spine animation/skin fields as per-entity dynamic enums, so
+ * the inspector offers the loaded skeleton's actual animation/skin names as a
+ * dropdown instead of a raw text field. Importing this performs the
+ * registration (side effect).
+ */
+import { registerDynamicEnum } from './schema';
+import { SceneModel } from './SceneModel';
+import { EngineHost } from './EngineHost';
+
+const names = (sourceId: number, pick: (rt: number) => string[]): string[] => {
+ const rt = SceneModel.runtimeFor(sourceId);
+ return rt != null ? pick(rt) : [];
+};
+
+registerDynamicEnum('SpineAnimation', 'animation', (id) => names(id, (rt) => EngineHost.spineAnimations(rt)));
+registerDynamicEnum('SpineAnimation', 'skin', (id) => names(id, (rt) => EngineHost.spineSkins(rt)));
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index e4ea5817a..c931efbdb 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -42,7 +42,7 @@ import { InspectorClipboard } from '@/engine/inspectorClipboard';
import { SceneCommands, toModelValue } from '@/engine/SceneCommands';
import { PlayInspect } from '@/engine/PlayInspect';
import type { SceneData } from 'esengine';
-import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba } from '@/engine/schema';
+import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions } from '@/engine/schema';
import { ProjectStore } from '@/project/ProjectStore';
import { confirmDiscard } from '@/project/discardGuard';
import { MaterialDocument } from '@/material/MaterialDocument';
@@ -1051,7 +1051,35 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
max: field.max,
});
+ // A string field whose choices depend on the entity's runtime state (e.g. a spine
+ // animation/skin name) renders as a dropdown of the live options, falling back to
+ // the text field when none are available (no skeleton loaded).
+ const dynOpts = !mixed && !write && field.type === 'string' ? dynamicEnumOptions(comp, field.key, entities[0]) : null;
let control;
+ if (dynOpts) {
+ const cur = String(field.value);
+ control = (
+ <span className="field">
+ <select
+ className="dyn-enum"
+ value={cur}
+ onMouseDown={(e) => e.stopPropagation()}
+ onChange={(e) => {
+ begin();
+ apply(e.target.value);
+ end();
+ }}
+ >
+ {!dynOpts.includes(cur) && <option value={cur}>{cur || '(none)'}</option>}
+ {dynOpts.map((o) => (
+ <option key={o} value={o}>
+ {o}
+ </option>
+ ))}
+ </select>
+ </span>
+ );
+ } else
switch (field.type) {
case 'number':
control =
diff --git a/desktop/tests/dynamic-enum.test.ts b/desktop/tests/dynamic-enum.test.ts
new file mode 100644
index 000000000..8d9679ff5
--- /dev/null
+++ b/desktop/tests/dynamic-enum.test.ts
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Per-entity dynamic enum registry — string fields whose choices depend on
+ * an entity's runtime state (e.g. spine animation/skin names). The inspector
+ * renders a dropdown when a provider yields options.
+ */
+import { describe, it, expect } from 'vitest';
+import { registerDynamicEnum, dynamicEnumOptions } from '@/engine/schema';
+
+describe('dynamic enum registry', () => {
+ it('returns a provider\'s options for the registered (component, field)', () => {
+ registerDynamicEnum('Foo', 'anim', () => ['walk', 'run']);
+ expect(dynamicEnumOptions('Foo', 'anim', 1)).toEqual(['walk', 'run']);
+ });
+
+ it('is null for an unregistered field, and for empty options (falls back to a text field)', () => {
+ expect(dynamicEnumOptions('Nope', 'x', 1)).toBeNull();
+ registerDynamicEnum('Foo', 'empty', () => []);
+ expect(dynamicEnumOptions('Foo', 'empty', 1)).toBeNull();
+ });
+
+ it('passes the entity source id to the provider (per-entity options)', () => {
+ let seen = -1;
+ registerDynamicEnum('Foo', 'byEntity', (id) => {
+ seen = id;
+ return ['x'];
+ });
+ dynamicEnumOptions('Foo', 'byEntity', 42);
+ expect(seen).toBe(42);
+ });
+});