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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.snapindex 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.tsnew file mode 100644index 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.cppindex 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.hppindex 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 */