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(sdk): a DragonBones armature loads from a scene, on every target
yhh6d80aa5c6d98
diff --git a/build-tools/tasks/sdk.js b/build-tools/tasks/sdk.jsindex fbc0b445f..ecaeab7ca 100644--- a/build-tools/tasks/sdk.js+++ b/build-tools/tasks/sdk.js@@ -107,9 +107,11 @@ async function copyDistOutputs(sdkDir, outputDir) {await mkdir(cjsDir, { recursive: true });const spineDir = path.join(esmDir, 'spine');+ const dragonBonesDir = path.join(esmDir, 'dragonbones');const physicsDir = path.join(esmDir, 'physics');const sharedDir = path.join(esmDir, 'shared');await mkdir(spineDir, { recursive: true });+ await mkdir(dragonBonesDir, { recursive: true });await mkdir(physicsDir, { recursive: true });await mkdir(sharedDir, { recursive: true });@@ -122,6 +124,8 @@ async function copyDistOutputs(sdkDir, outputDir) {{ src: 'wasm.d.ts', dest: path.join(esmDir, 'wasm.d.ts') },{ src: 'spine/index.js', dest: path.join(spineDir, 'index.js') },{ src: 'spine/index.d.ts', dest: path.join(spineDir, 'index.d.ts') },+ { src: 'dragonbones/index.js', dest: path.join(dragonBonesDir, 'index.js') },+ { src: 'dragonbones/index.d.ts', dest: path.join(dragonBonesDir, 'index.d.ts') },{ src: 'physics/index.js', dest: path.join(physicsDir, 'index.js') },{ src: 'physics/index.d.ts', dest: path.join(physicsDir, 'index.d.ts') },{ src: 'index.wechat.js', dest: path.join(cjsDir, 'index.wechat.js') },diff --git a/sdk/etc/dragonbones.api.md b/sdk/etc/dragonbones.api.mdnew file mode 100644index 000000000..eb2b66e38--- /dev/null+++ b/sdk/etc/dragonbones.api.md@@ -0,0 +1,177 @@+# API surface — esengine/dragonbones++<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->+Symbols: 18 stable · 0 beta · 0 deprecated++## DragonBones — const+```+ResourceDef<DragonBonesManager | null>+```++## DragonBonesArmatureNames — interface+```+animations: string[]+name: string+```++## DragonBonesAssetInfo — interface+```+atlasJson: string+skeletonData: string | Uint8Array<ArrayBufferLike>+textureId: number+```++## DragonBonesEntityOptions — interface+```+animation: string | undefined+armature: string+assetKey: string | undefined+flipX: boolean | undefined+flipY: boolean | undefined+layer: number | undefined+loop: boolean | undefined+skeletonScale: number | undefined+```++## DragonBonesManager — class+```+addEntity: (entity: Entity, skeletonHandle: number, options: DragonBonesEntityOptions) => boolean+controller: DragonBonesModuleController+dispose: () => void+fadeIn: (entity: Entity, animation: string, fadeSeconds: number, loop?: boolean) => boolean+getAnimations: (entity: Entity) => string[]+getArmatures: (skeletonHandle: number) => string[]+getBounds: (entity: Entity) => SkeletalBounds | null+hasInstance: (entity: Entity) => boolean+loadSkeleton: (skeletonData: Uint8Array | string, atlasJson: string, assetKey?: string) => number+play: (entity: Entity, animation: string, loop?: boolean) => boolean+removeEntity: (entity: Entity) => void+setAtlasTexture: (skeletonHandle: number, textureId: number) => void+setEnabled: (entity: Entity, enabled: boolean) => void+setEntityProps: (entity: Entity, props: Partial<Pick<EntityInfo, "skeletonScale" | "flipX" | "flipY" | "layer" | "playing">> & { timeScale?: number; }) => void+setTimeScale: (entity: Entity, scale: number) => void+stop: (entity: Entity, animation?: string) => void+submitMeshes: (core: SkeletalSubmitCore, registry: unknown) => void+updateAnimations: (dt: number) => void+static new (controller: DragonBonesModuleController): DragonBonesManager+static prototype: DragonBonesManager+```++## DragonBonesModuleController — class+```+createInstance: (skeletonHandle: number, armatureName: string) => number+destroyInstance: (instanceId: number) => void+fadeIn: (instanceId: number, animation: string, fadeSeconds: number, loop?: boolean) => boolean+forEachMeshBatch: (instanceId: number, cb: MeshBatchVisitor) => void+getAnimations: (instanceId: number) => string[]+getArmatures: (handle: number) => string[]+getAtlasImageName: (handle: number) => string+getBounds: (instanceId: number) => SkeletalBounds+getLastError: () => string+loadSkeleton: (skeletonData: Uint8Array | string, atlasJson: string) => number+play: (instanceId: number, animation: string, loop?: boolean) => boolean+runtimeVersion: () => number+setAtlasTexture: (handle: number, textureId: number) => void+setTimeScale: (instanceId: number, scale: number) => void+stop: (instanceId: number, animation?: string) => void+unloadSkeleton: (handle: number) => void+update: (instanceId: number, dt: number) => void+static new (raw: DragonBonesWasmModule, api: DragonBonesWrappedAPI): DragonBonesModuleController+static prototype: DragonBonesModuleController+```++## DragonBonesModuleFactory — type+```+(options?: { wasmBinary?: Uint8Array }) => Promise<DragonBonesWasmModule>+```++## DragonBonesPlugin — class+```+acquire: () => Promise<DragonBonesManager | null>+build: (app: App) => void+cleanup: () => void+manager: DragonBonesManager | null+name: string+static new (manager?: DragonBonesManager): DragonBonesPlugin+static prototype: DragonBonesPlugin+```++## DragonBonesWasmModule — interface+```+HEAP32: Int32Array<ArrayBufferLike>+HEAPF32: Float32Array<ArrayBufferLike>+HEAPU32: Uint32Array<ArrayBufferLike>+HEAPU8: Uint8Array<ArrayBufferLike>+_free: (ptr: number) => void+_malloc: (size: number) => number+cwrap: (name: string, ret: string | null, sig: string[]) => (...args: unknown[]) => unknown+```++## DragonBonesWrappedAPI — interface+```+createInstance: (handle: number, armatureName: string) => number+destroyInstance: (instanceId: number) => void+fadeInAnimation: (instanceId: number, name: string, fadeSeconds: number, playTimes: number) => number+getAnimations: (instanceId: number) => string+getArmatures: (handle: number) => string+getAtlasImageName: (handle: number) => string+getBounds: (instanceId: number, xPtr: number, yPtr: number, wPtr: number, hPtr: number) => void+getLastError: () => string+getMeshBatchCount: (instanceId: number) => number+getMeshBatchData: (instanceId: number, batchIndex: number, verticesPtr: number, indicesPtr: number, textureIdPtr: number, blendModePtr: number) => void+getMeshBatchIndexCount: (instanceId: number, batchIndex: number) => number+getMeshBatchVertexCount: (instanceId: number, batchIndex: number) => number+loadSkeleton: (skeletonPtr: number, skeletonLen: number, atlasPtr: number, atlasLen: number) => number+playAnimation: (instanceId: number, name: string, playTimes: number) => number+runtimeVersion: () => number+setAtlasTexture: (handle: number, textureId: number) => void+setTimeScale: (instanceId: number, scale: number) => void+stopAnimation: (instanceId: number, name: string) => void+unloadSkeleton: (handle: number) => void+update: (instanceId: number, dt: number) => void+```++## RuntimeAssetSource — interface+```+backend: Backend+decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height: number; pixels: Uint8Array; }>+listAssetPaths: (() => string[]) | undefined+resolveAddress: ((ref: string) => string | null) | undefined+resolveRef: ((ref: string) => string) | undefined+```++## applyDragonBonesEntities — function+```+(opts: { manager: DragonBonesManager; sceneData: SceneData; entityMap: Map<number, Entity>; assetInfo: Map<string, DragonBonesAssetInfo>; }): void+```++## dragonBonesEntityProps — function+```+(d: Record<string, unknown>): { skeletonScale: number; flipX: boolean; flipY: boolean; layer: number; timeScale: number; playing: boolean; }+```++## dragonBonesPlugin — const+```+() => DragonBonesPlugin+```++## loadDragonBonesAssets — function+```+(module: ESEngineModule | null, source: RuntimeAssetSource, pairs: ReadonlyArray<{ skeleton: string; atlas: string; }>, transcoderProvider?: TranscoderProvider): Promise<Map<string, DragonBonesAssetInfo>>+```++## loadDragonBonesSceneEntities — function+```+(opts: { module: ESEngineModule | null; source: RuntimeAssetSource; manager: DragonBonesManager; sceneData: SceneData; entityMap: Map<number, Entity>; transcoderProvider?: TranscoderProvider; }): Promise<void>+```++## parseDragonBonesNames — function+```+(source: string | object): DragonBonesArmatureNames[]+```++## wrapDragonBonesModule — function+```+(raw: DragonBonesWasmModule): DragonBonesWrappedAPI+```+diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 404851853..841ac125f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1361 stable · 17 beta · 1 deprecated+Symbols: 1366 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -2117,6 +2117,46 @@ lockX: booleanlockY: boolean```+## DragonBones — const+```+ResourceDef<DragonBonesManager | null>+```++## DragonBonesAnimation — const+```+BuiltinComponentDef<DragonBonesAnimationData>+```++## DragonBonesAnimationData — interface+```+animation: string+armature: string+atlasPath: string+color: Color+enabled: boolean+fadeInTime: number+flipX: boolean+flipY: boolean+layer: number+loop: boolean+material: number+playing: boolean+skeletonPath: string+skeletonScale: number+timeScale: number+```++## DragonBonesPlugin — class+```+acquire: () => Promise<DragonBonesManager | null>+build: (app: App) => void+cleanup: () => void+manager: DragonBonesManager | null+name: string+static new (manager?: DragonBonesManager): DragonBonesPlugin+static prototype: DragonBonesPlugin+```+## Draw — const```DrawAPI@@ -8729,6 +8769,11 @@ PluralSelectorDragPlugin```+## dragonBonesPlugin — const+```+() => DragonBonesPlugin+```+## emptyAnimatorController — function```(): AnimatorControllerDefdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 882923c00..0f932a21f 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1380 stable · 22 beta · 1 deprecated+Symbols: 1385 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -2125,6 +2125,46 @@ lockX: booleanlockY: boolean```+## DragonBones — const+```+ResourceDef<DragonBonesManager | null>+```++## DragonBonesAnimation — const+```+BuiltinComponentDef<DragonBonesAnimationData>+```++## DragonBonesAnimationData — interface+```+animation: string+armature: string+atlasPath: string+color: Color+enabled: boolean+fadeInTime: number+flipX: boolean+flipY: boolean+layer: number+loop: boolean+material: number+playing: boolean+skeletonPath: string+skeletonScale: number+timeScale: number+```++## DragonBonesPlugin — class+```+acquire: () => Promise<DragonBonesManager | null>+build: (app: App) => void+cleanup: () => void+manager: DragonBonesManager | null+name: string+static new (manager?: DragonBonesManager): DragonBonesPlugin+static prototype: DragonBonesPlugin+```+## Draw — const```DrawAPI@@ -8933,6 +8973,11 @@ PluralSelectorDragPlugin```+## dragonBonesPlugin — const+```+() => DragonBonesPlugin+```+## emptyAnimatorController — function```(): AnimatorControllerDefdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex c300165a5..d77989adf 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1360 stable · 19 beta · 1 deprecated+Symbols: 1365 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -2112,6 +2112,46 @@ lockX: booleanlockY: boolean```+## DragonBones — const+```+ResourceDef<DragonBonesManager | null>+```++## DragonBonesAnimation — const+```+BuiltinComponentDef<DragonBonesAnimationData>+```++## DragonBonesAnimationData — interface+```+animation: string+armature: string+atlasPath: string+color: Color+enabled: boolean+fadeInTime: number+flipX: boolean+flipY: boolean+layer: number+loop: boolean+material: number+playing: boolean+skeletonPath: string+skeletonScale: number+timeScale: number+```++## DragonBonesPlugin — class+```+acquire: () => Promise<DragonBonesManager | null>+build: (app: App) => void+cleanup: () => void+manager: DragonBonesManager | null+name: string+static new (manager?: DragonBonesManager): DragonBonesPlugin+static prototype: DragonBonesPlugin+```+## Draw — const```DrawAPI@@ -8724,6 +8764,11 @@ PluralSelectorDragPlugin```+## dragonBonesPlugin — const+```+() => DragonBonesPlugin+```+## emptyAnimatorController — function```(): AnimatorControllerDefdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 503b42f37..03cef0c22 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1381 stable · 17 beta · 1 deprecated+Symbols: 1386 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -2112,6 +2112,46 @@ lockX: booleanlockY: boolean```+## DragonBones — const+```+ResourceDef<DragonBonesManager | null>+```++## DragonBonesAnimation — const+```+BuiltinComponentDef<DragonBonesAnimationData>+```++## DragonBonesAnimationData — interface+```+animation: string+armature: string+atlasPath: string+color: Color+enabled: boolean+fadeInTime: number+flipX: boolean+flipY: boolean+layer: number+loop: boolean+material: number+playing: boolean+skeletonPath: string+skeletonScale: number+timeScale: number+```++## DragonBonesPlugin — class+```+acquire: () => Promise<DragonBonesManager | null>+build: (app: App) => void+cleanup: () => void+manager: DragonBonesManager | null+name: string+static new (manager?: DragonBonesManager): DragonBonesPlugin+static prototype: DragonBonesPlugin+```+## Draw — const```DrawAPI@@ -8944,6 +8984,11 @@ PluralSelectorDragPlugin```+## dragonBonesPlugin — const+```+() => DragonBonesPlugin+```+## emptyAnimatorController — function```(): AnimatorControllerDefdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex cd088de42..11ac13bd6 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1371 stable · 17 beta · 1 deprecated+Symbols: 1376 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -2112,6 +2112,46 @@ lockX: booleanlockY: boolean```+## DragonBones — const+```+ResourceDef<DragonBonesManager | null>+```++## DragonBonesAnimation — const+```+BuiltinComponentDef<DragonBonesAnimationData>+```++## DragonBonesAnimationData — interface+```+animation: string+armature: string+atlasPath: string+color: Color+enabled: boolean+fadeInTime: number+flipX: boolean+flipY: boolean+layer: number+loop: boolean+material: number+playing: boolean+skeletonPath: string+skeletonScale: number+timeScale: number+```++## DragonBonesPlugin — class+```+acquire: () => Promise<DragonBonesManager | null>+build: (app: App) => void+cleanup: () => void+manager: DragonBonesManager | null+name: string+static new (manager?: DragonBonesManager): DragonBonesPlugin+static prototype: DragonBonesPlugin+```+## Draw — const```DrawAPI@@ -8748,6 +8788,11 @@ PluralSelectorDragPlugin```+## dragonBonesPlugin — const+```+() => DragonBonesPlugin+```+## emptyAnimatorController — function```(): AnimatorControllerDefdiff --git a/sdk/package.json b/sdk/package.jsonindex 3061f0219..f2c7955ae 100644--- a/sdk/package.json+++ b/sdk/package.json@@ -37,6 +37,10 @@"import": "./dist/index.native.js","types": "./dist/index.native.d.ts"},+ "./dragonbones": {+ "import": "./dist/dragonbones/index.js",+ "types": "./dist/dragonbones/index.d.ts"+ },"./spine": {"import": "./dist/spine/index.js","types": "./dist/spine/index.d.ts"diff --git a/sdk/rollup.config.js b/sdk/rollup.config.jsindex beb6a4660..05d52319f 100644--- a/sdk/rollup.config.js+++ b/sdk/rollup.config.js@@ -23,6 +23,7 @@ const esmBuilds = ['index.native': 'src/index.native.ts','physics/index': 'src/physics/index.ts','spine/index': 'src/spine/index.ts',+ 'dragonbones/index': 'src/dragonbones/index.ts','wasm': 'src/wasm.ts',},output: {@@ -78,6 +79,7 @@ const dtsBuilds = ['index.native': 'src/index.native.ts','physics/index': 'src/physics/index.ts','spine/index': 'src/spine/index.ts',+ 'dragonbones/index': 'src/dragonbones/index.ts','wasm': 'src/wasm.ts',},output: {diff --git a/sdk/src/core-plugins.ts b/sdk/src/core-plugins.tsindex 3fef24dec..e16add825 100644--- a/sdk/src/core-plugins.ts+++ b/sdk/src/core-plugins.ts@@ -37,5 +37,10 @@ export { PhysicsPlugin, PhysicsEvents, Physics, loadPhysicsModule } from './phys// module, since the wire is authored whether or not physics is loaded.export { PhysicsEventType, type PhysicsContactEventData } from './physics';export { SpinePlugin, SpineEvents, Spine } from './spine';+// DragonBones beside it, and in the barrel for the same reason: the native entry+// collapses every `esengine*` import onto ONE global, so a game reaching+// `Res(DragonBones)` through `esengine/dragonbones` finds nothing on a device+// unless the resource is here too.+export { DragonBonesPlugin, dragonBonesPlugin, DragonBones } from './dragonbones';export { PostProcessPlugin, postProcessPlugin } from './postprocess';diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 3305b044d..7b5284c68 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -100,6 +100,7 @@ export {Children,BitmapText,SpineAnimation,+ DragonBonesAnimation,Name,Disabled,RuntimeOnly,@@ -123,6 +124,7 @@ export {type BitmapTextData,type TrailRendererData,type SpineAnimationData,+ type DragonBonesAnimationData,type RigidBodyData,type BoxColliderData,type CircleColliderData,diff --git a/sdk/src/dragonbones/DragonBonesManager.ts b/sdk/src/dragonbones/DragonBonesManager.tsindex ed3bff8f9..e66755f35 100644--- a/sdk/src/dragonbones/DragonBonesManager.ts+++ b/sdk/src/dragonbones/DragonBonesManager.ts@@ -30,6 +30,12 @@ interface EntityInfo {flipY: boolean;layer: number;timeScale: number;+ /**+ * False freezes the pose: the armature stops advancing but is still drawn.+ * Distinct from {@link DragonBonesManager.setEnabled}, which removes it from+ * the frame entirely — a paused character is still on screen.+ */+ playing: boolean;/** Set when the skeleton is shared; absent means this entity owns its own. */assetKey?: string;}@@ -111,6 +117,7 @@ export class DragonBonesManager {flipY: options.flipY ?? false,layer: options.layer ?? 0,timeScale: 1,+ playing: true,assetKey: options.assetKey,};this.entities_.set(entity, info);@@ -138,9 +145,18 @@ export class DragonBonesManager {else this.disabled_.add(entity);}- setEntityProps(entity: Entity, props: Partial<Pick<EntityInfo, 'skeletonScale' | 'flipX' | 'flipY' | 'layer'>>): void {+ setEntityProps(+ entity: Entity,+ props: Partial<Pick<EntityInfo, 'skeletonScale' | 'flipX' | 'flipY' | 'layer' | 'playing'>>+ & { timeScale?: number },+ ): void {const info = this.entities_.get(entity);- if (info) Object.assign(info, props);+ if (!info) return;+ const { timeScale, ...rest } = props;+ Object.assign(info, rest);+ // timeScale is not a field to assign: the module owns the clock, so it has+ // to be told rather than remembered.+ if (timeScale !== undefined) this.setTimeScale(entity, timeScale);}// — Animation ————————————————————————————————————————————————————————————@@ -183,6 +199,9 @@ export class DragonBonesManager {updateAnimations(dt: number): void {for (const [entity, info] of this.entities_) {if (this.disabled_.has(entity)) continue;+ // Paused armatures fall through to submitMeshes, which still draws the+ // pose they are holding.+ if (!info.playing) continue;this.controller_.update(info.instanceId, dt);}}diff --git a/sdk/src/dragonbones/index.ts b/sdk/src/dragonbones/index.tsindex 2e5af4b40..7735ac125 100644--- a/sdk/src/dragonbones/index.ts+++ b/sdk/src/dragonbones/index.ts@@ -12,3 +12,13 @@ export type { DragonBonesEntityOptions } from './DragonBonesManager';export { DragonBonesPlugin, dragonBonesPlugin, DragonBones } from './DragonBonesPlugin';export { parseDragonBonesNames } from './skeletonNames';export type { DragonBonesArmatureNames } from './skeletonNames';+// Shared scene loader — the editor binds a scene's armatures through the same+// single implementation the builder runtime uses (see ./loadDragonBonesScene).+export {+ loadDragonBonesSceneEntities,+ loadDragonBonesAssets,+ applyDragonBonesEntities,+ dragonBonesEntityProps,+} from './loadDragonBonesScene';+export type { DragonBonesAssetInfo } from './loadDragonBonesScene';+export type { RuntimeAssetSource } from '../runtimeAssets';diff --git a/sdk/src/dragonbones/loadDragonBonesScene.ts b/sdk/src/dragonbones/loadDragonBonesScene.tsnew file mode 100644index 000000000..8016dbeff--- /dev/null+++ b/sdk/src/dragonbones/loadDragonBonesScene.ts@@ -0,0 +1,267 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file dragonbones/loadDragonBonesScene.ts+ * @brief Turning DragonBonesAnimation components into posed armatures.+ *+ * @details The counterpart of `spine/loadSpineScene.ts`, and split for the same+ * reason: the builder runtime and the editor must load a scene's+ * skeletons by ONE implementation, or the viewport and the shipped game+ * disagree about what the scene contains.+ *+ * Two phases, because entity ids do not exist until the scene spawns.+ * Phase 1 fetches bytes and uploads the atlas page; phase 2 binds them to+ * entities. The split is what lets the runtime loader interleave the fetch+ * with everything else it preloads.+ *+ * Where this differs from Spine is the atlas. A Spine `.atlas` lists its+ * pages inside itself; a DragonBones `_tex.json` is a JSON object naming+ * exactly one, in `imagePath`. So there is no page loop here — one image,+ * resolved against the atlas's AUTHORED directory, because a cook renames+ * the atlas and the image independently and neither ends up beside the+ * other by accident.+ */+import type { ESEngineModule } from '../wasm';+import type { Entity } from '../types';+import { getComponentSkeletalFieldDescriptor, type SceneData } from '../scene';+import { discoverSceneAssets } from '../asset/discoverAssets';+import { getAssetTypeEntry } from '../assetTypes';+import { requireResourceManager } from '../resourceManager';+import { log } from '../logger';+import { createTextureFromPixels, type RuntimeAssetSource } from '../runtimeAssets';+import { isKtx2Path, type BasisTranscoder } from '../asset/compressed';+import type { DragonBonesManager } from './DragonBonesManager';++/** Lazily yields the realm's Basis transcoder, or null where a cook cannot have+ * produced a compressed page (editor, uncooked dev). Same seam as Spine's. */+export type TranscoderProvider = () => Promise<BasisTranscoder | null>;++/**+ * The in-place editable props from a DragonBonesAnimation component's data — the+ * SINGLE extraction the scene loader and the editor's live-sync both feed to+ * `setEntityProps`, so a prop added to the component is carried by both paths from+ * one place instead of being hand-listed twice.+ */+export function dragonBonesEntityProps(d: Record<string, unknown>): {+ skeletonScale: number; flipX: boolean; flipY: boolean; layer: number;+ timeScale: number; playing: boolean;+} {+ const num = (v: unknown, dflt: number): number => (typeof v === 'number' ? v : dflt);+ return {+ skeletonScale: num(d.skeletonScale, 1),+ flipX: d.flipX === true,+ flipY: d.flipY === true,+ layer: num(d.layer, 0),+ timeScale: num(d.timeScale, 1),+ playing: d.playing !== false,+ };+}++/** What phase 1 fetched for one skeleton/atlas pair. */+export interface DragonBonesAssetInfo {+ skeletonData: Uint8Array | string;+ atlasJson: string;+ /** The uploaded page's id, or -1 when the image could not be loaded — the+ * armature still poses, it just draws untextured, which is visible. */+ textureId: number;+}++/** The image a `_tex.json` names, or '' when it names none. */+function atlasImageName(atlasJson: string): string {+ try {+ const parsed: unknown = JSON.parse(atlasJson);+ const path = (parsed as { imagePath?: unknown } | null)?.imagePath;+ return typeof path === 'string' ? path : '';+ } catch {+ return '';+ }+}++/**+ * Phase 1 — fetch each pair's skeleton and atlas and upload the atlas image.+ * Keyed by `skeletonRef:atlasRef` for {@link applyDragonBonesEntities}.+ */+export async function loadDragonBonesAssets(+ /** The wasm engine module, or null on a core with no heap — the upload goes+ * through the ResourceManager's byte path there. */+ module: ESEngineModule | null,+ source: RuntimeAssetSource,+ pairs: ReadonlyArray<{ skeleton: string; atlas: string }>,+ transcoderProvider?: TranscoderProvider,+): Promise<Map<string, DragonBonesAssetInfo>> {+ const assetInfo = new Map<string, DragonBonesAssetInfo>();+ const resolveRef = source.resolveRef ?? ((r: string) => r);++ for (const pair of pairs) {+ const cacheKey = `${pair.skeleton}:${pair.atlas}`;+ if (assetInfo.has(cacheKey)) continue;++ try {+ const atlasJson = await source.backend.fetchText(resolveRef(pair.atlas));++ const skelPath = resolveRef(pair.skeleton);+ const skeletonData: Uint8Array | string =+ getAssetTypeEntry(skelPath)?.contentType === 'binary'+ ? new Uint8Array(await source.backend.fetchBinary(skelPath))+ : await source.backend.fetchText(skelPath);++ assetInfo.set(cacheKey, {+ skeletonData,+ atlasJson,+ textureId: await uploadAtlasImage_(+ module, source, pair.atlas, atlasJson, resolveRef, transcoderProvider),+ });+ } catch (err) {+ log.warn('runtime',+ `Failed to load DragonBones asset: skeleton=${pair.skeleton} atlas=${pair.atlas}`, err);+ }+ }+ return assetInfo;+}++/** Decode and upload the one page a `_tex.json` names; -1 if there is none to load. */+async function uploadAtlasImage_(+ module: ESEngineModule | null,+ source: RuntimeAssetSource,+ atlasRef: string,+ atlasJson: string,+ resolveRef: (ref: string) => string,+ transcoderProvider?: TranscoderProvider,+): Promise<number> {+ const imageName = atlasImageName(atlasJson);+ if (!imageName) {+ log.warn('runtime', `DragonBones atlas names no image: ${atlasRef}`);+ return -1;+ }++ // The image is named relative to where the atlas was AUTHORED, not to where a+ // content-addressed build staged it — recover that directory from the atlas's+ // logical address so `<dir>/page.png` resolves through the manifest like every+ // other ref (the same recovery Spine's page loop does).+ const atlasLogical = source.resolveAddress?.(atlasRef) ?? resolveRef(atlasRef);+ const slash = atlasLogical.lastIndexOf('/');+ const imagePath = slash >= 0 ? `${atlasLogical.substring(0, slash)}/${imageName}` : imageName;++ try {+ const staged = resolveRef(imagePath);+ let decoded: { width: number; height: number; pixels: Uint8Array };+ if (isKtx2Path(staged)) {+ const transcoder = await transcoderProvider?.();+ if (!transcoder) throw new Error('KTX2 atlas page but no Basis transcoder in this realm');+ const rgba = transcoder.transcodeToRgba(new Uint8Array(await source.backend.fetchBinary(staged)));+ if (!rgba) throw new Error(`KTX2 transcode failed: ${staged}`);+ decoded = { width: rgba.width, height: rgba.height, pixels: rgba.data };+ } else {+ decoded = await source.decodePixels(staged, false);+ }+ const rm = requireResourceManager();+ const handle = createTextureFromPixels(module, decoded, false);+ rm.registerTextureWithPath(handle, imagePath);+ return rm.getTextureGLId(handle);+ } catch (err) {+ log.warn('runtime', `Failed to load DragonBones atlas image: ${imagePath}`, err);+ return -1;+ }+}++/**+ * Phase 2 — for each DragonBonesAnimation entity, parse its pair into the manager+ * (shared per pair, so ten of the same armature parse the file once), bind the+ * uploaded page, and apply the component's armature, props and animation.+ */+export function applyDragonBonesEntities(opts: {+ manager: DragonBonesManager;+ sceneData: SceneData;+ entityMap: Map<number, Entity>;+ assetInfo: Map<string, DragonBonesAssetInfo>;+}): void {+ const { manager, sceneData, entityMap, assetInfo } = opts;+ if (assetInfo.size === 0) return;++ for (const sceneEntity of sceneData.entities) {+ // Prefab instances carry no inline components; the loader expands them+ // before this runs.+ if (!Array.isArray(sceneEntity.components)) continue;++ for (const comp of sceneEntity.components) {+ const desc = getComponentSkeletalFieldDescriptor(comp.type);+ if (!desc || desc.runtime !== 'dragonbones' || !comp.data) continue;++ const data = comp.data as Record<string, unknown>;+ const skeletonRef = data[desc.skeletonField];+ const atlasRef = data[desc.atlasField];+ if (typeof skeletonRef !== 'string' || typeof atlasRef !== 'string') continue;+ if (!skeletonRef || !atlasRef) continue;++ const assetKey = `${skeletonRef}:${atlasRef}`;+ const info = assetInfo.get(assetKey);+ if (!info) continue;++ const entity = entityMap.get(sceneEntity.id);+ if (entity === undefined) continue;++ const handle = manager.loadSkeleton(info.skeletonData, info.atlasJson, assetKey);+ if (handle < 0) continue;+ if (info.textureId >= 0) manager.setAtlasTexture(handle, info.textureId);++ // No armature named means the first one the file holds: a file usually+ // ships one, and refusing to draw because a field is blank would make+ // the common case need a value the user cannot guess without opening+ // the file.+ const named = typeof data.armature === 'string' ? data.armature : '';+ const armature = named || manager.getArmatures(handle)[0];+ if (!armature) {+ log.warn('runtime', `DragonBones file holds no armature: ${skeletonRef}`);+ continue;+ }++ const props = dragonBonesEntityProps(data);+ const added = manager.addEntity(entity, handle, {+ armature,+ assetKey,+ skeletonScale: props.skeletonScale,+ flipX: props.flipX,+ flipY: props.flipY,+ layer: props.layer,+ });+ if (!added) continue;++ manager.setEntityProps(entity, props);+ if (data.enabled === false) manager.setEnabled(entity, false);++ const animation = typeof data.animation === 'string' ? data.animation : '';+ if (animation) {+ const fade = typeof data.fadeInTime === 'number' ? data.fadeInTime : 0;+ const loop = data.loop !== false;+ // fadeInTime is what this component has instead of Spine's mix+ // table, so an authored fade belongs to the FIRST play too.+ if (fade > 0) manager.fadeIn(entity, animation, fade, loop);+ else manager.play(entity, animation, loop);+ }+ }+ }+}++/**+ * Combined convenience: discover this scene's DragonBones pairs, load them, and+ * bind them to the spawned entities. What the editor's viewport calls.+ */+export async function loadDragonBonesSceneEntities(opts: {+ module: ESEngineModule | null;+ source: RuntimeAssetSource;+ manager: DragonBonesManager;+ sceneData: SceneData;+ entityMap: Map<number, Entity>;+ transcoderProvider?: TranscoderProvider;+}): Promise<void> {+ const discovered = discoverSceneAssets(opts.sceneData);+ if (discovered.dragonBones.length === 0) return;+ const assetInfo = await loadDragonBonesAssets(+ opts.module, opts.source, discovered.dragonBones, opts.transcoderProvider);+ applyDragonBonesEntities({+ manager: opts.manager,+ sceneData: opts.sceneData,+ entityMap: opts.entityMap,+ assetInfo,+ });+}diff --git a/sdk/src/ecs/nativeRuntime.ts b/sdk/src/ecs/nativeRuntime.tsindex d668692e5..b4f6bc828 100644--- a/sdk/src/ecs/nativeRuntime.ts+++ b/sdk/src/ecs/nativeRuntime.ts@@ -41,6 +41,7 @@ import { UICameraInfo } from '../ui/core/ui-camera-info';import { DEFAULT_UI_CAMERA_INFO } from '../corePlugin';import { uiPlugin } from '../ui/ui-plugin';import { SpinePlugin } from '../spine';+import { DragonBonesPlugin } from '../dragonbones';import { setNativeTextSubmit } from '../ui/text/submit';import { initResourceManager } from '../resourceManager';import { Assets as AssetsClass } from '../asset/Assets';@@ -122,6 +123,9 @@ export function createNativeApp(// SpineManager keyed to this app's core) and builds its runtime backends from// `app.sideModules` — which on a device is the runtime compiled into the binary.app.addPlugin(new SpinePlugin());+ // Same shape for DragonBones — its runtime is linked into the host binary+ // (estella_dragonbones), which is what `app.sideModules` hands back here.+ app.addPlugin(new DragonBonesPlugin());return app;}diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.tsindex 95019118e..ce5d2d873 100644--- a/sdk/src/runtimeLoader.ts+++ b/sdk/src/runtimeLoader.ts@@ -21,6 +21,7 @@ import type { App } from './app';import { Assets as AssetsClass } from './asset/Assets';import { Assets as AssetsResource } from './asset/AssetPlugin';import { transcoderFromModule, type BasisWasmModule } from './asset/basisTranscoder';+import type { BasisTranscoder } from './asset/compressed';import type { TextureImportSettings } from './asset/loaders/TextureLoader';import { SceneManager, type SceneConfig } from './sceneManager';import { DEFAULT_GRAVITY, DEFAULT_FIXED_TIMESTEP } from './defaults';@@ -36,6 +37,9 @@ import { requireResourceManager } from './resourceManager';import { log } from './logger';import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';import { loadSpineAssets, applySpineEntities, type SpineAssetInfo } from './spine/loadSpineScene';+import { DragonBonesPlugin } from './dragonbones/DragonBonesPlugin';+import type { DragonBonesManager } from './dragonbones/DragonBonesManager';+import { loadDragonBonesAssets, applyDragonBonesEntities, type DragonBonesAssetInfo } from './dragonbones/loadDragonBonesScene';import type { AddressableManifest, ManifestModel } from './asset/AddressableManifest';import type { Catalog } from './asset/Catalog';@@ -295,15 +299,36 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promislog.warn('scene', `${discovered.spines.length} spine asset(s) skipped — `+ 'this realm has no optional-module host to load a Spine runtime from');}+ const transcoderProvider = async (): Promise<BasisTranscoder | null> => {+ const host = app.sideModules;+ if (!host) return null;+ const mod = await host.acquire('basis');+ return mod ? transcoderFromModule(mod as unknown as BasisWasmModule) : null;+ };const spineAssetInfo = app.sideModules- ? await loadSpineAssets(module, source, spineManager, discovered.spines, async () => {- const host = app.sideModules;- if (!host) return null;- const mod = await host.acquire('basis');- return mod ? transcoderFromModule(mod as unknown as BasisWasmModule) : null;- })+ ? await loadSpineAssets(module, source, spineManager, discovered.spines, transcoderProvider): new Map<string, SpineAssetInfo>();+ // DragonBones, the same two phases. The manager is acquired only when the+ // scene actually holds an armature — the plugin fetches its wasm on the first+ // ask, so a scene without one costs nothing.+ let dragonBonesManager: DragonBonesManager | null = null;+ let dragonBonesAssetInfo = new Map<string, DragonBonesAssetInfo>();+ if (discovered.dragonBones.length > 0) {+ if (!app.sideModules) {+ log.warn('scene', `${discovered.dragonBones.length} DragonBones asset(s) skipped — `+ + 'this realm has no optional-module host to load the DragonBones runtime from');+ } else {+ dragonBonesManager = (await app.getPlugin(DragonBonesPlugin)?.acquire()) ?? null;+ if (!dragonBonesManager) {+ log.warn('scene', 'DragonBones assets present but the runtime could not be loaded');+ } else {+ dragonBonesAssetInfo = await loadDragonBonesAssets(+ module, source, discovered.dragonBones, transcoderProvider);+ }+ }+ }+// Self-gating: install physics when the project declares it OR the scene uses// it, so no runtime entry can forget to wire it. The module comes from the// realm's side-module host (app.sideModules) — fetch / inlined / WeChat — or@@ -389,6 +414,12 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promisawait applySpineEntities({ spineManager, sceneData, entityMap, registry: cppRegistry, assetInfo: spineAssetInfo });}+ if (dragonBonesManager) {+ applyDragonBonesEntities({+ manager: dragonBonesManager, sceneData, entityMap, assetInfo: dragonBonesAssetInfo,+ });+ }+if (sceneName && app.hasResource(SceneManager)) {// Adopt into the SceneManager's instance set so unload/switchTo actually// despawns these entities — SceneOwner alone is only the persistence tag.diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.tsindex 3d200da67..2dd442e99 100644--- a/sdk/src/webAppFactory.ts+++ b/sdk/src/webAppFactory.ts@@ -9,6 +9,7 @@ import { seedEngineComponents } from './component';import { uiPlugins } from './uiPlugins';import { simulationBasePlugins, webBasePlugins } from './pluginSets';import { SpinePlugin } from './spine';+import { DragonBonesPlugin } from './dragonbones';import { createFetchSideModuleHost, type SideModuleHost } from './sideModules';@@ -32,7 +33,11 @@ export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptio?? (options?.wasmBaseUrl ? createFetchSideModuleHost(options.wasmBaseUrl) : undefined);// SpinePlugin builds its per-version SpineManager from app.sideModules in build().const spinePlugin = new SpinePlugin();- const plugins = [...uiPlugins, ...basePlugins, spinePlugin, ...(options?.plugins ?? [])];+ // DragonBones is beside it and costs nothing to install: it fetches its wasm+ // only when something asks for the manager, so a project with no DragonBones in+ // it never touches the side module.+ const dragonBonesPlugin = new DragonBonesPlugin();+ const plugins = [...uiPlugins, ...basePlugins, spinePlugin, dragonBonesPlugin, ...(options?.plugins ?? [])];return _createWebApp(module, { ...options, sideModules, plugins });}diff --git a/tools/api-surface.mjs b/tools/api-surface.mjsindex 4ca8233cb..9bdf8eef0 100644--- a/tools/api-surface.mjs+++ b/tools/api-surface.mjs@@ -32,6 +32,7 @@ const ENTRIES = {'index.native': 'src/index.native.ts','physics': 'src/physics/index.ts','spine': 'src/spine/index.ts',+ 'dragonbones': 'src/dragonbones/index.ts','wasm': 'src/wasm.ts','wechat': 'src/index.wechat.ts','minigame': 'src/index.minigame.ts',