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.

docs: a DragonBones guide, and the tables that had only ever heard of Spine

yhh5c41a24dac2f
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 1834b625c..d57e3da5e 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -33,6 +33,7 @@ export default defineConfig({
'../../sdk/src/index.ts',
'../../sdk/src/physics/index.ts',
'../../sdk/src/spine/index.ts',
+ '../../sdk/src/dragonbones/index.ts',
],
tsconfig: '../../sdk/tsconfig.json',
output: 'api-ts',
@@ -89,6 +90,7 @@ export default defineConfig({
{ label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'guides/animation' },
{ label: 'Timeline', translations: { 'zh-CN': '时间轴' }, slug: 'guides/timeline' },
{ label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
+ { label: 'DragonBones Animation', translations: { 'zh-CN': 'DragonBones 动画' }, slug: 'guides/dragonbones' },
],
},
{
diff --git a/docs/astro/src/assets/guides/en/dragonbones-inspector.png b/docs/astro/src/assets/guides/en/dragonbones-inspector.png
new file mode 100644
index 000000000..0d055d518
Binary files /dev/null and b/docs/astro/src/assets/guides/en/dragonbones-inspector.png differ
diff --git a/docs/astro/src/assets/guides/en/dragonbones-shared.png b/docs/astro/src/assets/guides/en/dragonbones-shared.png
new file mode 100644
index 000000000..aba8f8622
Binary files /dev/null and b/docs/astro/src/assets/guides/en/dragonbones-shared.png differ
diff --git a/docs/astro/src/assets/guides/zh/dragonbones-inspector.png b/docs/astro/src/assets/guides/zh/dragonbones-inspector.png
new file mode 100644
index 000000000..0297bcb29
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/dragonbones-inspector.png differ
diff --git a/docs/astro/src/assets/guides/zh/dragonbones-shared.png b/docs/astro/src/assets/guides/zh/dragonbones-shared.png
new file mode 100644
index 000000000..aba8f8622
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/dragonbones-shared.png differ
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdx
index b1239a07f..5c3783108 100644
--- a/docs/astro/src/content/docs/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/guides/build-export.mdx
@@ -200,6 +200,7 @@ the base engine stays small:
|---|---|---|
| Physics (Box2D) | `physics.js` / `physics.wasm` | The project declares physics or a scene uses physics components. |
| Spine | `spine21` / `spine38` / `spine41` / `spine42` / `spine43` `.js`/`.wasm` | A scene uses a Spine skeleton of that format version. |
+| DragonBones | `dragonbones.js` / `dragonbones.wasm` | A scene uses a DragonBones armature. One module reads every version. |
| Basis transcoder | `basis.js` / `basis.wasm` | The build shipped KTX2-compressed textures. |
| Video decoder | `videodec.js` / `videodec.wasm` | The wasm video path decodes a clip. |
diff --git a/docs/astro/src/content/docs/guides/dragonbones.mdx b/docs/astro/src/content/docs/guides/dragonbones.mdx
new file mode 100644
index 000000000..8328c889c
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/dragonbones.mdx
@@ -0,0 +1,193 @@
+---
+title: DragonBones Animation
+description: The complete guide to DragonBones skeletal animation — importing a project, the DragonBonesAnimation component, choosing an armature, crossfading with fadeIn, and the DragonBones runtime API.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Estella animates [DragonBones](https://docs.egret.com/dragonbones) armatures:
+bones, meshes, slots and animations, posed by the same renderer that draws
+everything else. It's driven by the `DragonBonesAnimation` component and
+controlled at runtime through the `DragonBones` resource (from the
+`esengine/dragonbones` subpath).
+
+It runs everywhere the engine does — the editor viewport, Play, web, playable
+ads, mini-games, and compiled into the iOS and Android hosts.
+
+<Aside type="tip">
+ Unlike Spine, the DragonBones runtime is **MIT licensed**. Shipping a game that
+ uses it needs no separate license.
+</Aside>
+
+## Importing a project
+
+A DragonBones export is three files, and Estella imports all three as one asset
+type:
+
+| File | What it is |
+|---|---|
+| `<name>_ske.json` or `<name>.dbbin` | The skeleton — bones, slots, animations. |
+| `<name>_tex.json` | The atlas — where each piece sits on the image. |
+| `<name>_tex.png` | The image itself. |
+
+Drop the folder into the project. The two `_ske` / `_tex` halves are told apart
+**by their name suffix**, not their extension — both are `.json`, so extension
+alone cannot say which is which.
+
+The PNG is the one file nothing in your scene points at: it is named *inside* the
+atlas, in its `imagePath` field. Estella follows that reference when it packages a
+build, so the image ships with the atlas instead of being culled as unreachable.
+You do not need to reference it anywhere.
+
+## The `DragonBonesAnimation` component
+
+Add it with **Create → DragonBones**, or add the component to an existing entity.
+It lives in the main `esengine` package.
+
+![The DragonBonesAnimation component in the Details panel — asset slots for the skeleton and atlas, and Armature and Animation dropdowns filled from the file](../../../assets/guides/en/dragonbones-inspector.png)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `skeletonPath` | asset | `''` | Skeleton file (`_ske.json` / `.dbbin`). |
+| `atlasPath` | asset | `''` | Atlas file (`_tex.json`). |
+| `armature` | string | `''` | Which armature in the file (empty = the first). |
+| `animation` | string | `''` | Animation to play on spawn. |
+| `loop` | boolean | `true` | Loop the initial animation. |
+| `playing` | boolean | `true` | Whether playback advances. |
+| `fadeInTime` | number | `0` | Crossfade seconds, used on the first play too. |
+| `timeScale` | number | `1` | Per-entity playback speed. |
+| `skeletonScale` | number | `1` | Uniform skeleton scale. |
+| `flipX` / `flipY` | boolean | `false` | Mirror horizontally / vertically. |
+| `color` | Color | `{1,1,1,1}` | Tint (RGBA, 0..1). |
+| `layer` | number | `0` | Sorting layer for draw order. |
+| `material` | asset | none | Optional custom material. |
+| `enabled` | boolean | `true` | Disable to freeze and hide. |
+
+**Skeleton and atlas are asset slots**: pick from the popover, drag a file in from
+the Content Browser, or use the slot's locate / clear actions. The scene serializes
+them as portable `@uuid:` references, so moving or renaming the files never breaks
+the link.
+
+The armature poses **in the viewport while you edit** — changing the animation, the
+scale or a flip shows immediately, without pressing Play.
+
+<Aside type="caution">
+ `color` is authored but not yet applied to a DragonBones armature — the runtime's
+ ABI has no tint entry point. Slot colours authored in DragonBones Pro *are*
+ honoured; this is the per-entity tint on top of them.
+</Aside>
+
+## Choosing an armature
+
+A DragonBones file is a **project**, not a skeleton: one file often holds several
+armatures. Choosing one is a real step, so `armature` is its own field.
+
+Once the entity points at a skeleton, **Armature** and **Animation** become
+dropdowns filled by reading that file — you pick from what is actually in it
+rather than typing a name and finding out at runtime. The animation list follows
+the chosen armature, because two armatures in one file do not share an animation
+list.
+
+Leaving `armature` empty uses the first armature the file holds. Most files ship
+one, and requiring a value you cannot know without opening the file would make the
+common case harder than it is.
+
+<Aside type="note">
+ A `.dbbin` skeleton fills no dropdown — it is binary, and naming what is inside
+ it would mean starting the runtime just to populate a list. The field stays a
+ plain text box, and a name you type still works.
+</Aside>
+
+## Play & crossfade animations
+
+This is where DragonBones differs from Spine most, and the API says so rather than
+pretending otherwise. Spine keeps a **mix table** on the skeleton — "going from
+idle to run takes 0.2s". DragonBones blends **at the moment an animation starts**,
+so the fade is an argument to starting it:
+
+```typescript
+import { defineSystem, Query, Res, DragonBonesAnimation } from 'esengine';
+import { DragonBones } from 'esengine/dragonbones';
+
+const control = defineSystem(
+ [Query(DragonBonesAnimation), Res(DragonBones)],
+ (q, dragonBones) => {
+ // Null until the runtime lands — it is fetched on first use.
+ if (!dragonBones) return;
+
+ for (const [entity] of q) {
+ dragonBones.fadeIn(entity, 'walk', 0.25, true); // crossfade over 0.25s
+ dragonBones.setTimeScale(entity, 1.5); // 1.5x speed
+ }
+ },
+);
+```
+
+| Method | Description |
+|---|---|
+| `play(entity, name, loop?)` | Start an animation immediately, no blend. |
+| `fadeIn(entity, name, seconds, loop?)` | Crossfade into an animation. |
+| `stop(entity, name?)` | Stop one animation, or all of them when omitted. |
+| `setTimeScale(entity, scale)` | Per-entity playback speed. |
+| `setEnabled(entity, on)` | Remove from the frame entirely (freeze **and** hide). |
+| `setEntityProps(entity, props)` | Set `{ skeletonScale?, flipX?, flipY?, layer?, playing?, timeScale? }` at once. |
+
+`playing: false` freezes the pose but keeps drawing it; `setEnabled(false)` takes
+the armature out of the frame. They are different things and both are useful.
+
+## Query an armature
+
+```typescript
+const anims = dragonBones.getAnimations(entity); // string[]
+const bounds = dragonBones.getBounds(entity); // { x, y, width, height } | null
+```
+
+`getBounds` is derived from the armature's **posed** geometry, not from the bounds
+the authoring tool recorded — so it follows the character as it moves rather than
+describing where it was drawn.
+
+## Sharing one skeleton
+
+Entities pointing at the same skeleton + atlas pair share **one parsed skeleton and
+one atlas**. Ten copies of a character parse the file once and hold one texture
+between them; the last one removed unloads it.
+
+Nothing is required to opt in — it follows from the pair the components reference.
+Per-entity properties stay per entity, so a shared skeleton can still be scaled,
+flipped and tinted independently:
+
+![Two DragonBoy armatures from one file — the second scaled down and mirrored through component fields alone](../../../assets/guides/en/dragonbones-shared.png)
+
+## What ships in a build
+
+The DragonBones runtime is **pay-for-use**. A project without an armature in it
+never fetches, inlines or copies the module:
+
+| Target | How the runtime gets there |
+|---|---|
+| Web / desktop | `dragonbones.wasm` beside the engine, fetched on first use. |
+| Playable ad | Inlined into the single HTML file — only if a scene uses it. |
+| Mini-game | Copied into the package — only if a scene uses it. |
+| iOS / Android | Compiled into the app binary. |
+
+The editor decides by scanning the scenes it is packaging, so there is no setting
+to remember and no way to ship a game whose armatures have no runtime.
+
+## Best practices
+
+- **Give transitions a fade.** `fadeIn` with 0.15–0.3s reads far better than
+ `play`, which snaps. Set `fadeInTime` on the component so the first play blends
+ too.
+- **Share the pair across entities** — a crowd of one character costs one parse and
+ one atlas.
+- **Pick the armature in the editor**, from the dropdown, rather than typing it:
+ a name that does not exist in the file draws nothing.
+- **Prefer `playing: false` to disabling** when you want a character to hold a pose
+ on screen.
+
+## See also
+
+- [Spine Animation](/docs/guides/spine/) — the other skeletal runtime, and how it differs.
+- [Animation](/docs/guides/animation/) — sprite flipbooks and the Animator state machine.
+- [Assets](/docs/guides/assets/) — how skeleton and atlas assets are imported and referenced.
+- [Build & Export](/docs/guides/build-export/) — what a package contains per target.
diff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdx
index 7f8cd55de..55b6ed15d 100644
--- a/docs/astro/src/content/docs/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/guides/mobile.mdx
@@ -175,6 +175,7 @@ behaves exactly as it does in a browser.
| Text, bitmap text, rich text | Same atlas + layout as the web; glyphs rasterized from the OS font |
| Physics (Box2D) | Compiled in; solved across worker threads |
| Spine | Compiled in — one runtime version per binary (`-DESTELLA_SPINE_VERSION`) |
+| DragonBones | Compiled in — one runtime, since the format is frozen |
| Video | Compiled in (cooked at build, decoded on device) |
| Audio | Native mixer ([miniaudio](https://miniaud.io/)) — CoreAudio / AAudio |
| Text input | The platform's **soft keyboard** is the field's editing surface |
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdx
index fd0c925e3..9d9cd9553 100644
--- a/docs/astro/src/content/docs/guides/spine.mdx
+++ b/docs/astro/src/content/docs/guides/spine.mdx
@@ -157,3 +157,4 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
- [Animation](/docs/guides/animation/) — the Animator state machine can drive Spine.
- [Assets](/docs/guides/assets/) — loading skeleton + atlas assets.
+- [DragonBones Animation](/docs/guides/dragonbones/) — the other skeletal runtime, MIT licensed.
diff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/guides/wechat.mdx
index 33dc48ee4..aa5565a2f 100644
--- a/docs/astro/src/content/docs/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/guides/wechat.mdx
@@ -18,6 +18,7 @@ node build-tools/cli.js build -t wechat
# side modules, only if your game uses them:
node build-tools/cli.js build -t physics-wechat # physics
node build-tools/cli.js build -t spine-wechat # Spine (builds 2.1 + 3.8 + 4.1 + 4.2 + 4.3)
+node build-tools/cli.js build -t dragonbones-wechat # DragonBones
node build-tools/cli.js build -t basis-wechat # KTX2 / compressed textures
node build-tools/cli.js build -t videodec-wechat # video (MPEG-1 wasm decoder)
```
diff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
index 1128f90a5..70c28ceae 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
@@ -170,6 +170,7 @@ node build-tools/cli.js build -t wechat
|---|---|---|
| 物理(Box2D) | `physics.js` / `physics.wasm` | 项目声明了物理,或场景使用了物理组件。 |
| Spine | `spine21` / `spine38` / `spine41` / `spine42` / `spine43` 的 `.js`/`.wasm` | 场景使用了对应格式版本的 Spine 骨骼。 |
+| DragonBones | `dragonbones.js` / `dragonbones.wasm` | 场景使用了 DragonBones 骨架。一个模块读所有版本。 |
| Basis 转码器 | `basis.js` / `basis.wasm` | 构建里发布了 KTX2 压缩纹理。 |
| 视频解码器 | `videodec.js` / `videodec.wasm` | wasm 视频路径解码片段时。 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/dragonbones.mdx b/docs/astro/src/content/docs/zh-cn/guides/dragonbones.mdx
new file mode 100644
index 000000000..959678ada
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/dragonbones.mdx
@@ -0,0 +1,169 @@
+---
+title: DragonBones 动画
+description: DragonBones 骨骼动画的完整指南——导入项目、DragonBonesAnimation 组件、选择骨架、用 fadeIn 交叉淡入,以及 DragonBones 运行时 API。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Estella 支持 [DragonBones](https://docs.egret.com/dragonbones) 骨架动画:骨骼、网格、
+插槽与动画,由绘制其它一切的同一个渲染器摆姿势。它由 `DragonBonesAnimation` 组件驱动,
+并在运行时通过 `DragonBones` 资源(来自 `esengine/dragonbones` 子路径)控制。
+
+引擎跑到哪里它就跑到哪里——编辑器视口、Play、Web、Playable 广告、小游戏,以及编译进
+iOS 与 Android 宿主。
+
+<Aside type="tip">
+ 与 Spine 不同,DragonBones 运行时是 **MIT 许可**的。用它发布游戏不需要额外授权。
+</Aside>
+
+## 导入一个项目
+
+DragonBones 导出的是三个文件,Estella 把它们作为同一种资源类型导入:
+
+| 文件 | 是什么 |
+|---|---|
+| `<name>_ske.json` 或 `<name>.dbbin` | 骨骼——骨头、插槽、动画。 |
+| `<name>_tex.json` | 图集——每块图在图片上的位置。 |
+| `<name>_tex.png` | 图片本身。 |
+
+把文件夹拖进项目即可。`_ske` 与 `_tex` 两半是**按名字后缀**区分的,不是扩展名——两个都是
+`.json`,光看扩展名分不出谁是谁。
+
+那张 PNG 是场景里**没有任何东西指向**的文件:它的名字写在图集内部的 `imagePath` 字段里。
+打包时 Estella 会跟着这个引用走,所以图片会跟图集一起进包,而不会因为"没人引用"被剔掉。
+你不需要在任何地方引用它。
+
+## `DragonBonesAnimation` 组件
+
+用 **创建 → DragonBones** 添加,或者给已有实体加这个组件。组件本身在主 `esengine` 包里。
+
+![细节面板里的 DragonBonesAnimation 组件——骨骼与图集的资源槽,以及从文件读出来填充的骨架和动画下拉框](../../../../assets/guides/zh/dragonbones-inspector.png)
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `skeletonPath` | asset | `''` | 骨骼文件(`_ske.json` / `.dbbin`)。 |
+| `atlasPath` | asset | `''` | 图集文件(`_tex.json`)。 |
+| `armature` | string | `''` | 用文件里的哪个骨架(空 = 第一个)。 |
+| `animation` | string | `''` | 生成时播放的动画。 |
+| `loop` | boolean | `true` | 循环初始动画。 |
+| `playing` | boolean | `true` | 是否推进播放。 |
+| `fadeInTime` | number | `0` | 交叉淡入秒数,首次播放也会用。 |
+| `timeScale` | number | `1` | 每实体的播放速度。 |
+| `skeletonScale` | number | `1` | 骨架整体缩放。 |
+| `flipX` / `flipY` | boolean | `false` | 水平 / 垂直镜像。 |
+| `color` | Color | `{1,1,1,1}` | 着色(RGBA,0..1)。 |
+| `layer` | number | `0` | 决定绘制顺序的排序层。 |
+| `material` | asset | 无 | 可选的自定义材质。 |
+| `enabled` | boolean | `true` | 关掉则冻结并隐藏。 |
+
+**骨骼与图集是资源槽**:从弹出框里选、从内容浏览器拖进来,或者用槽自带的定位 / 清除操作。
+场景把它们序列化成可移植的 `@uuid:` 引用,所以移动或重命名文件都不会断链。
+
+编辑时骨架**就在视口里摆着**——改动画、改缩放、改翻转都会立刻看到,不用按 Play。
+
+<Aside type="caution">
+ `color` 可以填,但目前还没有作用到 DragonBones 骨架上——运行时的 ABI 没有着色入口。
+ 在 DragonBones Pro 里给插槽设的颜色**是**生效的;这里说的是叠在它之上的那层每实体着色。
+</Aside>
+
+## 选择骨架
+
+DragonBones 文件是一个**项目**,不是一个骨架:一个文件里常常放着好几个骨架。选哪一个是实打实
+的一步,所以 `armature` 是独立的一个字段。
+
+实体指向骨骼文件之后,**骨架**和**动画**会变成下拉框,内容是读那个文件读出来的——你从文件里
+真实存在的东西中挑,而不是手输一个名字然后在运行时才发现不对。动画列表跟着所选骨架走,因为
+一个文件里的两个骨架并不共用动画列表。
+
+`armature` 留空就用文件里的第一个骨架。大多数文件只有一个,而"必须填一个不打开文件就没法知道
+的值"会让最常见的情况反而更麻烦。
+
+<Aside type="note">
+ `.dbbin` 骨骼不会填充下拉框——它是二进制的,要报出里面有什么就得为了填一个列表而启动运行时。
+ 这个字段会保持成普通文本框,手输的名字照样有效。
+</Aside>
+
+## 播放与交叉淡入
+
+这是 DragonBones 与 Spine 差别最大的地方,API 也照实说,而不是假装一样。Spine 在骨架上维护一张
+**混合表**——"从 idle 到 run 用 0.2 秒"。DragonBones 是**在动画开始的那一刻**混合的,所以淡入
+时长是"开始播放"这个动作的参数:
+
+```typescript
+import { defineSystem, Query, Res, DragonBonesAnimation } from 'esengine';
+import { DragonBones } from 'esengine/dragonbones';
+
+const control = defineSystem(
+ [Query(DragonBonesAnimation), Res(DragonBones)],
+ (q, dragonBones) => {
+ // 运行时落地前是 null——它在第一次被用到时才去取。
+ if (!dragonBones) return;
+
+ for (const [entity] of q) {
+ dragonBones.fadeIn(entity, 'walk', 0.25, true); // 0.25 秒交叉淡入
+ dragonBones.setTimeScale(entity, 1.5); // 1.5 倍速
+ }
+ },
+);
+```
+
+| 方法 | 说明 |
+|---|---|
+| `play(entity, name, loop?)` | 立即开始一个动画,不混合。 |
+| `fadeIn(entity, name, seconds, loop?)` | 交叉淡入到一个动画。 |
+| `stop(entity, name?)` | 停一个动画;省略名字则全停。 |
+| `setTimeScale(entity, scale)` | 每实体的播放速度。 |
+| `setEnabled(entity, on)` | 整个从这一帧里拿掉(既冻结**又**隐藏)。 |
+| `setEntityProps(entity, props)` | 一次设 `{ skeletonScale?, flipX?, flipY?, layer?, playing?, timeScale? }`。 |
+
+`playing: false` 是冻住姿势但继续画;`setEnabled(false)` 是把骨架从这一帧里拿掉。这是两件事,
+而且两个都有用。
+
+## 查询骨架
+
+```typescript
+const anims = dragonBones.getAnimations(entity); // string[]
+const bounds = dragonBones.getBounds(entity); // { x, y, width, height } | null
+```
+
+`getBounds` 是从骨架**当前摆出的**几何算的,不是取制作工具里记录的那个包围盒——所以它跟着角色
+移动,而不是描述它当初被画在哪。
+
+## 共用一份骨架
+
+指向同一对骨骼 + 图集的实体共用**一份解析后的骨架和一张图集**。同一个角色来十个,文件只解析一次、
+纹理只有一份;最后一个被移除时才卸载。
+
+这不需要你做任何开关——它由组件引用的那一对文件自然决定。每实体的属性仍然是每实体的,所以共用
+骨架照样可以各自缩放、翻转、着色:
+
+![同一个文件里的两个 DragonBoy 骨架——第二个仅通过组件字段就缩小并镜像了](../../../../assets/guides/zh/dragonbones-shared.png)
+
+## 打包时会带上什么
+
+DragonBones 运行时是**按需付费**的。项目里没有骨架,就不会去取、内联或复制这个模块:
+
+| 目标 | 运行时怎么进去的 |
+|---|---|
+| Web / 桌面 | `dragonbones.wasm` 放在引擎旁边,首次使用时取。 |
+| Playable 广告 | 内联进那一个 HTML 文件——仅当场景用到。 |
+| 小游戏 | 复制进包里——仅当场景用到。 |
+| iOS / Android | 编译进 app 二进制。 |
+
+编辑器是扫描正在打包的场景来决定的,所以没有需要记住的开关,也没办法打出一个"有骨架却没有运行时"
+的包。
+
+## 最佳实践
+
+- **给切换加淡入。** `fadeIn` 用 0.15–0.3 秒,比 `play` 那种硬切好看得多。在组件上设
+ `fadeInTime`,首次播放也会淡入。
+- **在实体之间共用同一对文件**——同一个角色的一群人,只花一次解析和一张图集。
+- **在编辑器里用下拉框选骨架**,别手输:文件里不存在的名字什么都画不出来。
+- 想让角色**停在某个姿势并留在画面上**时,用 `playing: false`,别用禁用。
+
+## 参见
+
+- [Spine 动画](/docs/zh-cn/guides/spine/) —— 另一个骨骼运行时,以及两者的差别。
+- [动画](/docs/zh-cn/guides/animation/) —— 精灵帧动画与 Animator 状态机。
+- [资源](/docs/zh-cn/guides/assets/) —— 骨骼与图集资源怎么导入和引用。
+- [构建与导出](/docs/zh-cn/guides/build-export/) —— 每个目标的包里有什么。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
index 70faac674..5535b5de7 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
@@ -145,6 +145,7 @@ Android 两者都给,是因为它两者都做得到:编辑器既能直接装配
| 文本、位图字体、富文本 | 与网页端相同的图集与排版;字形从系统字体栅格化 |
| 物理(Box2D) | 编译进包;跨工作线程求解 |
| Spine | 编译进包——每个二进制一个运行时版本(`-DESTELLA_SPINE_VERSION`) |
+| DragonBones | 编译进包——只有一个运行时,因为格式是固定的 |
| 视频 | 编译进包(构建时 cook,真机解码) |
| 音频 | 原生混音器([miniaudio](https://miniaud.io/))—— CoreAudio / AAudio |
| 文本输入 | 平台**软键盘**就是输入框的编辑面 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
index b18dc6717..c4dff43bc 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
@@ -143,3 +143,4 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
- [动画](/docs/zh-cn/guides/animation/) —— Animator 状态机可以驱动 Spine。
- [资源](/docs/zh-cn/guides/assets/) —— 加载骨骼 + 图集资源。
+- [DragonBones 动画](/docs/zh-cn/guides/dragonbones/) —— 另一个骨骼运行时,MIT 许可。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
index 9cd81559d..acb746569 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
@@ -17,6 +17,7 @@ node build-tools/cli.js build -t wechat
# 侧模块,仅当你的游戏用到时:
node build-tools/cli.js build -t physics-wechat # 物理
node build-tools/cli.js build -t spine-wechat # Spine(一次构建 2.1 + 3.8 + 4.1 + 4.2 + 4.3)
+node build-tools/cli.js build -t dragonbones-wechat # DragonBones
node build-tools/cli.js build -t basis-wechat # KTX2 / 压缩纹理
node build-tools/cli.js build -t videodec-wechat # 视频(MPEG-1 wasm 解码器)
```