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(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.js
index 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.md
new file mode 100644
index 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.md
index 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: boolean
lockY: 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 @@ PluralSelector
DragPlugin
```
+## dragonBonesPlugin — const
+```
+() => DragonBonesPlugin
+```
+
## emptyAnimatorController — function
```
(): AnimatorControllerDef
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: boolean
lockY: 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 @@ PluralSelector
DragPlugin
```
+## dragonBonesPlugin — const
+```
+() => DragonBonesPlugin
+```
+
## emptyAnimatorController — function
```
(): AnimatorControllerDef
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: boolean
lockY: 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 @@ PluralSelector
DragPlugin
```
+## dragonBonesPlugin — const
+```
+() => DragonBonesPlugin
+```
+
## emptyAnimatorController — function
```
(): AnimatorControllerDef
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: boolean
lockY: 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 @@ PluralSelector
DragPlugin
```
+## dragonBonesPlugin — const
+```
+() => DragonBonesPlugin
+```
+
## emptyAnimatorController — function
```
(): AnimatorControllerDef
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: boolean
lockY: 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 @@ PluralSelector
DragPlugin
```
+## dragonBonesPlugin — const
+```
+() => DragonBonesPlugin
+```
+
## emptyAnimatorController — function
```
(): AnimatorControllerDef
diff --git a/sdk/package.json b/sdk/package.json
index 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.js
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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): Promis
log.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): Promis
await 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.ts
index 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.mjs
index 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',