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): armature and animation pickers, filled from the file the entity points at

esengine6a0ae1b97359
diff --git a/desktop/src/engine/dragonBonesNames.ts b/desktop/src/engine/dragonBonesNames.ts
new file mode 100644
index 000000000..0132953dd
--- /dev/null
+++ b/desktop/src/engine/dragonBonesNames.ts
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file dragonBonesNames.ts
+ * @brief Fills the armature and animation dropdowns from the file the entity
+ * points at.
+ *
+ * @details An enum-option provider answers synchronously and reading a file does
+ * not, so this is a cache the provider reads and a warm that fills it.
+ * A cold miss returns nothing, which the inspector already treats as
+ * "leave the field plainly editable" — so the field works before the read
+ * lands and improves after it, instead of stranding the value in an empty
+ * dropdown.
+ *
+ * A `.dbbin` yields nothing, on purpose. It is binary, naming what is
+ * inside it would mean instantiating the runtime, and a free-text field
+ * is a smaller cost than a wasm module loaded to populate a dropdown.
+ */
+import { parseDragonBonesNames, type DragonBonesArmatureNames } from '../../../sdk/src/dragonbones/skeletonNames';
+import { ProjectStore } from '@/project/ProjectStore';
+import { setEnumSource } from './schema';
+import type { EnumOption } from '@/types';
+
+/** ref → what that file declares; an empty array is a read that found nothing. */
+const cache = new Map<string, DragonBonesArmatureNames[]>();
+/** Refs being read, so a repainting inspector cannot start the same read twice. */
+const inFlight = new Set<string>();
+
+const SKELETON_FIELD = 'skeletonPath';
+const ARMATURE_FIELD = 'armature';
+
+function refOf(data: Readonly<Record<string, unknown>>): string {
+ const raw = data[SKELETON_FIELD];
+ return typeof raw === 'string' ? raw : '';
+}
+
+/**
+ * Read the file behind `ref` once. Failure caches an empty list rather than
+ * nothing: a path that cannot be read now will not read differently on the next
+ * repaint, and retrying per frame would hammer the disk for a broken reference.
+ */
+function warm(ref: string): void {
+ if (!ref || cache.has(ref) || inFlight.has(ref)) return;
+ inFlight.add(ref);
+ const path = ProjectStore.refPath(ref);
+ if (!path) {
+ cache.set(ref, []);
+ inFlight.delete(ref);
+ return;
+ }
+ void window.estella.fs.read(path)
+ .then((text) => cache.set(ref, text ? parseDragonBonesNames(text) : []))
+ .catch(() => cache.set(ref, []))
+ .finally(() => inFlight.delete(ref));
+}
+
+function armaturesFor(data: Readonly<Record<string, unknown>>): DragonBonesArmatureNames[] {
+ const ref = refOf(data);
+ warm(ref);
+ return cache.get(ref) ?? [];
+}
+
+const asOptions = (names: readonly string[]): EnumOption[] =>
+ names.map((name) => ({ label: name, value: name }));
+
+/** Register both dropdowns. Called once at boot, beside the other enum sources. */
+export function installDragonBonesEnumSources(): void {
+ setEnumSource('dragonbonesArmatures', (data) => asOptions(armaturesFor(data).map((a) => a.name)));
+
+ setEnumSource('dragonbonesAnimations', (data) => {
+ const armatures = armaturesFor(data);
+ if (armatures.length === 0) return [];
+ // The animations of THIS entity's armature — a file's armatures do not
+ // share an animation list, so offering the union would let a user pick one
+ // that its armature cannot play.
+ const chosen = data[ARMATURE_FIELD];
+ const armature = typeof chosen === 'string' && chosen
+ ? armatures.find((a) => a.name === chosen)
+ : armatures[0];
+ return asOptions(armature?.animations ?? []);
+ });
+}
+
+/** Drop the cache — a project close, or an asset edited outside the editor. */
+export function clearDragonBonesNameCache(): void {
+ cache.clear();
+ inFlight.clear();
+}
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index dd503bf1e..1c3d3a841 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -18,6 +18,7 @@ import { Boxes } from 'lucide-react';
import { spritePrefab, setCanvasDesignSeed, setProjectCameraFit, type EntitySource } from '@/engine/entitySources';
import { setPrefabBaseResolver } from '@/engine/SceneQuery';
import { setUserSchemas, userSchema, setBitmaskSource, setEnumSource, type UserComponentSchema } from '@/engine/schema';
+import { installDragonBonesEnumSources } from '@/engine/dragonBonesNames';
import { setProjectActions, type ProjectActionSchema } from '@/ai/actionCatalog';
import { setAssetRefProblemResolver } from '@/engine/EditorControlSurface';
import { installSpineSync, type SpineTransport } from '@/engine/spineSync';
@@ -245,6 +246,9 @@ class ProjectStoreImpl {
setBitmaskSource('collisionLayers', () => this.collisionLayerOptions());
// Render `layer` fields become a dropdown once the project names sorting layers.
setEnumSource('sortingLayers', () => this.sortingLayerOptions());
+ // Armature / animation dropdowns read the file each entity references, so
+ // their options are per-entity rather than per-project (see dragonBonesNames).
+ installDragonBonesEnumSources();
// New Canvas entities seed their design resolution from the project setting.
setCanvasDesignSeed(() => this.designResolution());
// The device preview reads the project camera fit so its letterbox matches the
@@ -755,6 +759,11 @@ class ProjectStoreImpl {
/** Resolve a serialized asset ref to a project-relative path for the engine
* loader: a uuid ref (`@uuid:` or bare) → path (null if unknown); a plain
* path passes through. */
+ /** Project-relative path for a `@uuid:` ref (or a plain path unchanged). */
+ refPath(ref: string): string | null {
+ return this.resolveRef(ref);
+ }
+
private resolveRef(ref: string): string | null {
const uuid = refUuid(ref);
if (uuid === null) return ref;
diff --git a/desktop/tests/dragonbones-enum-source.test.ts b/desktop/tests/dragonbones-enum-source.test.ts
new file mode 100644
index 000000000..2704f2826
--- /dev/null
+++ b/desktop/tests/dragonbones-enum-source.test.ts
@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// The armature/animation dropdowns. The parsing is covered in the SDK; what is
+// covered here is the choosing — a file's armatures do NOT share an animation
+// list, so offering their union would let someone pick an animation the armature
+// they selected cannot play, and it would look like a broken export rather than a
+// bad menu.
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+const files = new Map<string, string>();
+
+vi.mock('@/project/ProjectStore', () => ({
+ ProjectStore: { refPath: (ref: string) => (files.has(ref) ? ref : null) },
+}));
+
+const sources = new Map<string, (data: Record<string, unknown>) => { label: string; value: string | number }[]>();
+vi.mock('@/engine/schema', () => ({
+ setEnumSource: (name: string, provider: never) => sources.set(name, provider),
+}));
+
+const TWO_ARMATURES = JSON.stringify({
+ armature: [
+ { name: 'Dragon', animation: [{ name: 'walk' }, { name: 'stand' }] },
+ { name: 'Effects', animation: [{ name: 'burst' }] },
+ ],
+});
+
+describe('DragonBones enum sources', () => {
+ beforeEach(async () => {
+ files.clear();
+ sources.clear();
+ (globalThis as { window?: unknown }).window = {
+ estella: { fs: { read: (p: string) => Promise.resolve(files.get(p) ?? '') } },
+ };
+ const mod = await import('@/engine/dragonBonesNames');
+ mod.clearDragonBonesNameCache();
+ mod.installDragonBonesEnumSources();
+ });
+
+ /** The provider reads a cache; the first call only starts the read. */
+ const settle = () => new Promise((r) => setTimeout(r, 0));
+
+ it('offers nothing before the file has been read, so the field stays editable', () => {
+ files.set('hero_ske.json', TWO_ARMATURES);
+ const opts = sources.get('dragonbonesArmatures')!({ skeletonPath: 'hero_ske.json' });
+ expect(opts).toEqual([]);
+ });
+
+ it('lists the file`s armatures once it has', async () => {
+ files.set('hero_ske.json', TWO_ARMATURES);
+ const data = { skeletonPath: 'hero_ske.json' };
+ sources.get('dragonbonesArmatures')!(data);
+ await settle();
+ expect(sources.get('dragonbonesArmatures')!(data).map((o) => o.value)).toEqual(['Dragon', 'Effects']);
+ });
+
+ it('offers only the animations of the armature this entity chose', async () => {
+ files.set('hero_ske.json', TWO_ARMATURES);
+ const base = { skeletonPath: 'hero_ske.json' };
+ sources.get('dragonbonesAnimations')!(base);
+ await settle();
+
+ const anims = (armature: string) =>
+ sources.get('dragonbonesAnimations')!({ ...base, armature }).map((o) => o.value);
+ expect(anims('Dragon')).toEqual(['walk', 'stand']);
+ expect(anims('Effects')).toEqual(['burst']);
+ // Unset means the first armature, which is what the component does too.
+ expect(anims('')).toEqual(['walk', 'stand']);
+ });
+
+ it('answers empty for a reference that does not resolve, and stops asking', async () => {
+ const data = { skeletonPath: 'missing_ske.json' };
+ sources.get('dragonbonesArmatures')!(data);
+ await settle();
+ // Cached as empty rather than retried: a path that cannot be read now will
+ // not read differently on the next repaint, and the inspector repaints a lot.
+ expect(sources.get('dragonbonesArmatures')!(data)).toEqual([]);
+ });
+});
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index 7da46cf7b..c4ff36c5c 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -224,6 +224,8 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
colorFields: ['color'],
animatableFields: [],
fields: {
+ armature: { enumSource: "dragonbonesArmatures" },
+ animation: { enumSource: "dragonbonesAnimations" },
timeScale: { min: 0 },
fadeInTime: { min: 0, step: 0.05 },
layer: { step: 1, enumSource: "sortingLayers" },
diff --git a/sdk/src/dragonbones/index.ts b/sdk/src/dragonbones/index.ts
index b30f0232b..2e5af4b40 100644
--- a/sdk/src/dragonbones/index.ts
+++ b/sdk/src/dragonbones/index.ts
@@ -10,3 +10,5 @@ export type {
export { DragonBonesManager } from './DragonBonesManager';
export type { DragonBonesEntityOptions } from './DragonBonesManager';
export { DragonBonesPlugin, dragonBonesPlugin, DragonBones } from './DragonBonesPlugin';
+export { parseDragonBonesNames } from './skeletonNames';
+export type { DragonBonesArmatureNames } from './skeletonNames';
diff --git a/sdk/src/dragonbones/skeletonNames.ts b/sdk/src/dragonbones/skeletonNames.ts
new file mode 100644
index 000000000..a25a37fbc
--- /dev/null
+++ b/sdk/src/dragonbones/skeletonNames.ts
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file dragonbones/skeletonNames.ts
+ * @brief The armature and animation names a `_ske.json` declares.
+ *
+ * @details Read here rather than asked of the module, for the reason the Spine
+ * atlas's page names are (see spine/atlasPages): naming what is in a file
+ * is not posing a skeleton, and making an inspector dropdown wait on a
+ * wasm instantiation buys nothing.
+ *
+ * A `.dbbin` is binary and yields nothing — which is not an error. Every
+ * reader of this is expected to work without it, and the editor's field
+ * simply stays free text.
+ */
+
+export interface DragonBonesArmatureNames {
+ name: string;
+ animations: string[];
+}
+
+interface RawArmature {
+ name?: unknown;
+ animation?: unknown;
+}
+
+const nameOf = (v: unknown): string | null =>
+ v && typeof v === 'object' && typeof (v as { name?: unknown }).name === 'string'
+ ? (v as { name: string }).name
+ : null;
+
+/**
+ * Armatures and their animations, in file order. Anything unreadable — binary
+ * data, a truncated download, a file that is simply not this format — is no names
+ * rather than a throw: a caller asking what is inside can always be told nothing.
+ */
+export function parseDragonBonesNames(source: string | object): DragonBonesArmatureNames[] {
+ let doc: unknown = source;
+ if (typeof source === 'string') {
+ try {
+ doc = JSON.parse(source);
+ } catch {
+ return [];
+ }
+ }
+ const armatures = (doc as { armature?: unknown } | null)?.armature;
+ if (!Array.isArray(armatures)) return [];
+
+ const out: DragonBonesArmatureNames[] = [];
+ for (const raw of armatures as RawArmature[]) {
+ const name = nameOf(raw);
+ if (name === null) continue;
+ const animations = Array.isArray(raw.animation)
+ ? (raw.animation as unknown[]).map(nameOf).filter((n): n is string => n !== null)
+ : [];
+ out.push({ name, animations });
+ }
+ return out;
+}
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index a2e20f2d7..41b5b6a11 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -127,6 +127,12 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
},
},
"DragonBonesAnimation": {
+ "animation": {
+ "enumSource": "dragonbonesAnimations",
+ },
+ "armature": {
+ "enumSource": "dragonbonesArmatures",
+ },
"fadeInTime": {
"min": 0,
"step": 0.05,
diff --git a/sdk/tests/dragonbones-names.test.ts b/sdk/tests/dragonbones-names.test.ts
new file mode 100644
index 000000000..c80542a31
--- /dev/null
+++ b/sdk/tests/dragonbones-names.test.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// What the inspector's armature and animation dropdowns read. It answers about a
+// file the user chose, so every way that file can be wrong has to be an empty list
+// rather than a throw — a bad path must not take the inspector down with it.
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseDragonBonesNames } from '../src/dragonbones/skeletonNames';
+
+const SKE = resolve(__dirname, 'assets/dragonbones/DragonBoy_ske.json');
+
+describe('parseDragonBonesNames', () => {
+ it('reads a real file`s armatures and their animations', () => {
+ const found = parseDragonBonesNames(readFileSync(SKE, 'utf8'));
+ expect(found).toEqual([
+ { name: 'Dragon', animations: ['stand', 'walk', 'jump', 'fall'] },
+ ]);
+ });
+
+ it('takes an already-parsed document too', () => {
+ const doc = JSON.parse(readFileSync(SKE, 'utf8')) as object;
+ expect(parseDragonBonesNames(doc)[0].name).toBe('Dragon');
+ });
+
+ it('answers nothing for anything it cannot read', () => {
+ // Binary `.dbbin` content, a truncated download, another format entirely,
+ // an empty file — all of them are "no names", and none is an exception.
+ expect(parseDragonBonesNames(' ')).toEqual([]);
+ expect(parseDragonBonesNames('{"armature":')).toEqual([]);
+ expect(parseDragonBonesNames('{"not":"dragonbones"}')).toEqual([]);
+ expect(parseDragonBonesNames('')).toEqual([]);
+ });
+
+ it('skips entries it cannot name instead of inventing one', () => {
+ const doc = { armature: [{ animation: [] }, { name: 'Real', animation: [{ name: 'go' }, {}] }] };
+ expect(parseDragonBonesNames(doc)).toEqual([{ name: 'Real', animations: ['go'] }]);
+ });
+});
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index b2360dd4b..2a8e85500 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash 73200e0a9e5cd114
+ * @schema_hash af08590e4bae8cf8
*/
-#define ES_EDITOR_API_SCHEMA_HASH "73200e0a9e5cd114"
+#define ES_EDITOR_API_SCHEMA_HASH "af08590e4bae8cf8"
#include <emscripten/bind.h>
#include <string>
diff --git a/src/esengine/ecs/components/DragonBonesAnimation.hpp b/src/esengine/ecs/components/DragonBonesAnimation.hpp
index 531b594c5..17a04e4f7 100644
--- a/src/esengine/ecs/components/DragonBonesAnimation.hpp
+++ b/src/esengine/ecs/components/DragonBonesAnimation.hpp
@@ -42,11 +42,11 @@ struct DragonBonesAnimation {
std::string atlasPath;
/** @brief Which armature in the file; empty takes the first */
- ES_PROPERTY()
+ ES_PROPERTY(enum_source=dragonbonesArmatures)
std::string armature;
/** @brief Current animation name */
- ES_PROPERTY()
+ ES_PROPERTY(enum_source=dragonbonesAnimations)
std::string animation;
/** @brief Animation playback speed multiplier */