### Install and start the project

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Pixi/Demos/8.x/README.md

Install dependencies and start the project. Run these commands in the project root.

```bash
npm install
```

```bash
npm run start
```

--------------------------------

### Start the demo with npm run start

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Hilo/Demos/README.md

Run this command after installing dependencies to launch the demo application.

```bash
npm run start
```

--------------------------------

### Install dependencies and build

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Egret/4.x/README.md

Install dependencies and build the project in the DragonBonesJS/Egret/4.x directory. Run these commands sequentially in command line after cloning the repository.

```bash
npm install
```

```bash
npm run build
```

--------------------------------

### Factory usage example

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/BaseFactory.md

Example demonstrating how to use the factory to load, parse, build, manipulate, and tear down armatures.

```APIDOC
## Factory Usage Example

### Description
Example showing how to use the factory to load and parse data, build an armature, swap skins, and clean up.

### Steps
1. **Load and parse**: Use `parseDragonBonesData` and `parseTextureAtlasData` to load and parse skeleton and atlas data.
2. **Build**: Use `buildArmature` to create an armature instance.
3. **Skin swap**: Use `replaceSlotDisplay` and `replaceSkin` to change displays and skins.
4. **Teardown**: Use `removeDragonBonesData` and `clear` to clean up.

### Code Example
```ts
const factory = dragonBones.PixiFactory.factory;   // engine factory
factory.autoSearch = false;

// 1. Load and parse
factory.parseDragonBonesData(skeletonJson, "myProject");
factory.parseTextureAtlasData(atlasJson, atlasTexture, "myProject");

// 2. Build
const armature = factory.buildArmature("hero", "myProject", "skin2");
if (armature !== null) {
    armature.clock = factory.clock;   // drive with the master clock
    armature.animation.play("run", 0);
}

// 3. Skin swap
const ok = factory.replaceSlotDisplay("myProject", "hero", "weapon", "sword_01", slot);
const okSkin = factory.replaceSkin(armature, otherSkinData, false, ["head"]);

// 4. Teardown
factory.removeDragonBonesData("myProject");
factory.clear(false);
```
```

--------------------------------

### Example: Loading and Displaying a DragonBones Armature with Pixi

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/PixiBinding.md

Example usage of the PixiDBBinParser and PixiFactory to load and display DragonBones armatures in a Pixi application.

```APIDOC
## Example: Loading and Displaying a DragonBones Armature with Pixi

### Description
Demonstrates how to use the PixiDBBinParser and PixiFactory to load DragonBones assets and display an armature in a Pixi application.

### Code Example
```ts
import * as PIXI from "pixi.js";

const app = new PIXI.Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

const factory = dragonBones.PixiFactory.factory;   // singleton, shared ticker

// Load assets via Pixi Assets (the dbbin loader is pre-registered):
const [ske, texData, texImg] = await Promise.all([
    PIXI.Assets.load("resource/mecha/mecha_ske.json"),   // or .dbbin
    PIXI.Assets.load("resource/mecha/mecha_tex.json"),
    PIXI.Assets.load("resource/mecha/mecha_tex.png"),
]);

factory.parseDragonBonesData(ske, "mecha");
factory.parseTextureAtlasData(texData, texImg, "mecha");

const armatureDisplay = factory.buildArmatureDisplay("mecha_1002", "mecha");
if (armatureDisplay) {
    armatureDisplay.debugDraw = true;
    armatureDisplay.x = 400; armatureDisplay.y = 300;
    app.stage.addChild(armatureDisplay);
    armatureDisplay.animation.play("idle", 0);
    armatureDisplay.addDBEventListener(dragonBones.EventObject.COMPLETE, (e) => {
        console.log(e.animationState.name);
    }, this);
}

// Cleanup
armatureDisplay.dispose(true);  // armature → pool
app.destroy(true);
```
```

--------------------------------

### Install dependencies with npm install

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/DragonBones/README.md

Run this command in the DragonBones directory to install required npm packages.

```bash
npm install
```

--------------------------------

### Project structure example

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Hilo/1.x/README.md

Shows the required directory layout for the project, including libs, node_modules, out, and src folders.

```text
Your project
    |-- libs
        |-- hilo.d.ts
    |-- node_modules
        |-- ...
    |-- out
        |-- ...
    |-- src
        |-- ...
    |-- ...
```

--------------------------------

### Build with npm run build

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/DragonBones/README.md

Run this command after npm install to build the library.

```bash
npm run build
```

--------------------------------

### Example: Using PixiFactory with DragonBones

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/DragonBones.md

Shows how to access the singleton DragonBones instance via PixiFactory, advance time, and enable debug drawing.

```typescript
import * as PIXI from "pixi.js";
// PixiFactory exposes the singleton DragonBones instance internally:
const factory = dragonBones.PixiFactory.factory;

// advance one frame (PixiFactory.advanceTime proxies here):
dragonBones.PixiFactory.advanceTime(0.016);

// static config:
dragonBones.DragonBones.debugDraw = true;
```

--------------------------------

### Load and display DragonBones armature with PixiFactory

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/PixiBinding.md

Complete example of loading DragonBones assets via Pixi Assets, parsing them with the PixiFactory singleton, building an armature display, playing an animation, and cleaning up. The dbbin loader is pre-registered, so .dbbin files can be loaded directly. The example uses the 'mecha' data and plays the 'idle' animation, logging the animation state name on completion.

```ts
import * as PIXI from "pixi.js";

const app = new PIXI.Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

const factory = dragonBones.PixiFactory.factory;   // singleton, shared ticker

// Load assets via Pixi Assets (the dbbin loader is pre-registered):
const [ske, texData, texImg] = await Promise.all([
    PIXI.Assets.load("resource/mecha/mecha_ske.json"),   // or .dbbin
    PIXI.Assets.load("resource/mecha/mecha_tex.json"),
    PIXI.Assets.load("resource/mecha/mecha_tex.png"),
]);

factory.parseDragonBonesData(ske, "mecha");
factory.parseTextureAtlasData(texData, texImg, "mecha");

const armatureDisplay = factory.buildArmatureDisplay("mecha_1002", "mecha");
if (armatureDisplay) {
    armatureDisplay.debugDraw = true;
    armatureDisplay.x = 400; armatureDisplay.y = 300;
    app.stage.addChild(armatureDisplay);
    armatureDisplay.animation.play("idle", 0);
    armatureDisplay.addDBEventListener(dragonBones.EventObject.COMPLETE, (e) => {
        console.log(e.animationState.name);
    }, this);
}

// Cleanup
armatureDisplay.dispose(true);  // armature → pool
app.destroy(true);
```

--------------------------------

### Example: Parsing and accessing DragonBones data

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/ModelData.md

Shows how to parse DragonBones data using PixiFactory, retrieve armature, bone, slot, animation, and skin data, and access custom UserData from events. The example uses a project name "proj" and assumes a skeleton JSON variable `skeJson`.

```ts
const factory = dragonBones.PixiFactory.factory;
factory.parseDragonBonesData(skeJson, "proj");

const db = factory.getDragonBonesData("proj");
if (db) {
    console.log(db.name, db.version, db.frameRate, db.armatureNames);
    const armatureData = db.getArmature("hero");
    if (armatureData) {
        const boneData = armatureData.getBone("arm");
        const slotData = armatureData.getSlot("weapon");
        const animData = armatureData.getAnimation("attack");
        const skin = armatureData.getSkin("default");
        const displayData = skin ? skin.getDisplay("weapon", "sword_01") : null;
    }
}

// Custom data attached to events:
const data = new UserData();       // (usually read from eventObject.data)
const ints = data.getInt(0), floats = data.getFloat(0), strs = data.getString(0);
```

--------------------------------

### Example: parsing DragonBones data with factory and direct parser

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Parser.md

Example usage of parseDragonBonesData for both JSON and binary formats, including the Pixi 8.x asset pipeline for loading .dbbin files and a direct parser use case with error handling.

```ts
// Object format (JSON):
factory.parseDragonBonesData(skeJson, "dragon", 1.0);

// Binary format (.dbbin ArrayBuffer):
factory.parseDragonBonesData(arrayBuffer, "dragon", 1.0);

// Pixi 8.x asset pipeline (the built-in 'dbbin-loader' handles .dbbin):
await PIXI.Assets.load("resource/bone/ske.dbbin");
// then feed the ArrayBuffer to the factory as above.

// Direct parser use (rare — factories own their parser):
const parser = dragonBones.ObjectDataParser.getInstance();
const data = parser.parseDragonBonesData(skeJson, 1.0);
if (data === null) {
    console.warn("unsupported or invalid data");
}
```

--------------------------------

### Bone

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Bone.md

Documentation for the Bone class, including properties, methods, and an example.

```APIDOC
## Bone

### Description
Bone is the unit implementing translation, rotation and scaling of the skeleton hierarchy.

### Properties
- `offsetMode` (OffsetMode) - Default `OffsetMode.Additive`. `OffsetMode.None`: origin + animation pose. `OffsetMode.Override`: the bone inherits nothing — the global transform equals the offset exactly (with y-flip sign correction).
- `boneData` (BoneData) - Backing bone data.
- `visible` (boolean) - Visibility of all slots of this bone (default `true`; setter updates slots).
- `name` (string) - Bone name.
- `parent` (Bone | null) - Parent bone.
- (inherited) `offset`/`global`/`globalTransformMatrix` - See `TransformObject`.

### Methods
- `invalidUpdate(): void` - Forces the bone to update its transform on the next frame — required after modifying `bone.offset` when no animation state is driving the bone. Returns `void`.
- `contains(value: Bone): boolean` - True if `value` is a (non-self) descendant of this bone.

### Example
```ts
const armature = armatureDisplay.armature;
const arm = armature.getBone("arm");
if (arm) {
    arm.offset.rotation += 0.5;   // rotate the arm by ~28.6°
    arm.invalidUpdate();          // commit for next frame
    arm.visible = false;          // hide slots attached to the arm
}
```

### Sources
`armature/Bone.ts:59`, `:96-253`, `:481`, `:496`, `:518`, `:535`, `:561`, `:574`
```

--------------------------------

### Using IArmatureProxy with armature and animation

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Armature.md

Shows typical usage of an IArmatureProxy instance obtained from factory.buildArmatureDisplay. Demonstrates accessing the armature, flipping it, setting cacheFrameRate, getting bones and slots, performing hit testing with containsPoint, adding a listener via addDBEventListener, and cleanup with dispose.

```ts
const armatureDisplay = factory.buildArmatureDisplay("hero", "hero_project");
// armatureDisplay implements IArmatureProxy

const armature = armatureDisplay.armature;
armature.flipX = true;
armature.cacheFrameRate = 24;

const bone = armature.getBone("head");
if (bone !== null) { bone.visible = false; }

const slot = armature.getSlot("weapon");
if (slot !== null && slot.boundingBoxData !== null) {
    const hit = armature.containsPoint(x, y);
    if (hit === slot) { /* hit the weapon bounding box */ }
}

// listener through the proxy dispatcher:
armatureDisplay.addDBEventListener(dragonBones.EventObject.LOOP_COMPLETE, onLoop, this);

// cleanup:
armature.dispose();          // or armatureDisplay.dispose(true)
```

--------------------------------

### Play, fadeIn, getState, and reset animations with DragonBones

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Animation.md

Shows how to build an armature display, play and fade in animations, access and modify an animation state, handle missing animations, and reset. The example uses the factory's buildArmatureDisplay method and the animation API. Note that play returns null for nonexistent animations and triggers a console.warn.

```ts
const armatureDisplay = factory.buildArmatureDisplay("mecha_1002_101d", "mecha_1002_101d_show");
const animation = armatureDisplay.animation;

animation.play("walk", 0);                       // loop forever
animation.fadeIn("attack", 0.3, 1, 0, "attackGroup"); // blend over 0.3s
animation.play("idle");                          // default/fallback path

const state = animation.getState("walk");
if (state !== null) {
    state.timeScale = 1.5;                       // speed up
    state.addBoneMask("arm", true);              // restrict to one bone
}

// nonexistent animation -> console.warn and null:
const missing = animation.play("nope");
if (missing === null) { console.warn("animation not found"); }

animation.reset();                               // stop everything, pool states
```

--------------------------------

### gotoAndPlayByProgress

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Animation.md

Plays an animation starting at a specified progress.

```APIDOC
## `gotoAndPlayByProgress(animationName: string, progress: number = 0.0, playTimes: number = -1): AnimationState | null`

### Description
Plays an animation starting at a specified progress (0.0 to 1.0). Position is calculated as `duration * max(progress, 0)`. Resets to pose on start.

### Method
`gotoAndPlayByProgress`

### Parameters
- **animationName** (`string`) - Required - Animation data name.
- **progress** (`number`) - Optional - Start progress. Default: `0.0`.
- **playTimes** (`number`) - Optional - Repeat count (see `play`). Default: `-1`.

### Returns
`AnimationState | null` - The played state, or `null` if not found.
```

--------------------------------

### AnimationState usage example

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/AnimationState.md

Shows how to fade in an animation, adjust its time scale, play, set weight, add a bone mask, check completion, and fade out.

```TypeScript
const state = armatureDisplay.animation.fadeIn("attack", 0.3, 1, 1, "attackGroup");
if (state === null) return;

state.timeScale = 2.0;                   // double speed
state.play();                            // (re)start
state.weight = 0.6;                      // blend weight
state.addBoneMask("arm", true);

if (state.isCompleted) { /* ... */ }
state.fadeOut(0.5);                      // fade out over half a second
```

--------------------------------

### gotoAndPlayByFrame

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Animation.md

Plays an animation starting from a specified frame.

```APIDOC
## [Animation] gotoAndPlayByFrame

### Description
Jumps to a specific frame in the animation and plays from there. Returns the created AnimationState or null if the animation does not exist.

### Method
gotoAndPlayByFrame

### Parameters
- **animationName** (string) - Required - The name of the animation.
- **frame** (number) - Optional - Frame index to jump to. Defaults to 0.
- **playTimes** (number) - Optional - Number of times to play. Defaults to -1 (infinite).

### Returns
- **AnimationState | null** - The created AnimationState, or null if the animation is not found.

### Example
```ts
const state = armature.animation.gotoAndPlayByFrame("attack", 10);
```
```

--------------------------------

### gotoAndPlayByProgress

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Animation.md

Plays an animation starting from a specified progress percentage.

```APIDOC
## [Animation] gotoAndPlayByProgress

### Description
Jumps to a specific progress (0.0 to 1.0) in the animation and plays from there. Returns the created AnimationState or null if the animation does not exist.

### Method
gotoAndPlayByProgress

### Parameters
- **animationName** (string) - Required - The name of the animation.
- **progress** (number) - Optional - Progress value between 0.0 and 1.0. Defaults to 0.0.
- **playTimes** (number) - Optional - Number of times to play. Defaults to -1 (infinite).

### Returns
- **AnimationState | null** - The created AnimationState, or null if the animation is not found.

### Example
```ts
const state = armature.animation.gotoAndPlayByProgress("walk", 0.5);
```
```

--------------------------------

### Runtime IK constraint manipulation example

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Constraint.md

Shows how to influence an IK constraint at runtime by moving its target bone. The constraint is created automatically by the factory; direct access to constraints via `armature._constraints` is @internal and not part of the stable public API.

```ts
const armature = factory.buildArmature("armatureName", "dragonBonesName");
// Constraint is created from data — you usually just let the factory build it.
// To influence an IK constraint at runtime, move its target bone:

const target = armature.getBone("ikTarget");
if (target) {
    target.offset.x = 120;
    target.offset.y = -40;
    target.invalidUpdate();
}

// Individual constraints are reachable via armature._constraints
// (marked @internal); the public API is the bone/armature updates above.
```

--------------------------------

### ActionFrame helper class

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Parser.md

@private implementation detail helper class. Holds a frame start time and a readonly array of action indices. Referenced at parser/ObjectDataParser.ts:2432.

```ts
export class ActionFrame {
    public frameStart: number = 0;
    public readonly actions: Array<number> = [];
}
```

--------------------------------

### Matrix.transformPoint

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Geom.md

Transforms a point using the matrix. The example shows how to create a matrix and apply it to a point, then invert and transform back.

```APIDOC
## Matrix.transformPoint

### Description
Transforms a point using the matrix. The example shows how to create a matrix and apply it to a point, then invert and transform back.

### Method
`transformPoint(x: number, y: number, result: { x: number, y: number }): void`

### Parameters
- **x** (number) - The x-coordinate of the point to transform.
- **y** (number) - The y-coordinate of the point to transform.
- **result** (object) - The object to store the transformed coordinates (must have `x` and `y` properties).

### Example
```ts
const m = new dragonBones.Matrix(1, 0, 0, 1, 100, 50);
const p = { x: 10, y: 20 };
m.transformPoint(p.x, p.y, p);
console.log(p.x, p.y);  // 110, 70
```
```

--------------------------------

### Configure Phaser.Game with DragonBones plugin

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Phaser/Demos/README.md

Adds the DragonBones plugin to the Phaser game configuration. The plugin key is "DragonBonesPlugin" and the plugin is set to start automatically. The scene property should reference the first scene to display.

```javascript
const gameConfig = {
        plugins: {
            global: [
                { key: "DragonBonesPlugin", plugin: dragonBones.phaser.plugin.DragonBonesPlugin, start: true } // setup DB plugin
            ]
        },
        scene: TestSceneToDisplay   // first scene to show
    };

    new Phaser.Game(gameConfig);
```

--------------------------------

### EventObject

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/EventObject.md

Documents the EventObject class, including its static event type constants, instance fields, static helper method, and an example of listening and dispatching events.

```APIDOC
## EventObject

### Description
Extends `BaseObject`. Carries all information about an animation/armature event; instances are borrowed from the pool and buffered for deferred dispatch.

### Static Event Type Constants

| Constant | Value | Meaning |
|----------|-------|---------|
| `START` | `"start"` | Animation starts play. |
| `LOOP_COMPLETE` | `"loopComplete"` | One loop finished. |
| `COMPLETE` | `"complete"` | Animation play complete. |
| `FADE_IN` | `"fadeIn"` | Fade-in starts. |
| `FADE_IN_COMPLETE` | `"fadeInComplete"` | Fade-in completed. |
| `FADE_OUT` | `"fadeOut"` | Fade-out starts. |
| `FADE_OUT_COMPLETE` | `"fadeOutComplete"` | Fade-out completed. |
| `FRAME_EVENT` | `"frameEvent"` | A frame event on the animation timeline. |
| `SOUND_EVENT` | `"soundEvent"` | A frame sound event; also forwarded to the global event manager. |

### Instance Fields

| Field | Type | Description |
|-------|------|-------------|
| `time` | `number` | For frame events, the time on the animation timeline (seconds). |
| `type` | `EventStringType` | The event type. |
| `name` | `string` | Frame event name or frame sound name. |
| `armature` | `Armature` | The armature that dispatched the event. |
| `bone` | `Bone \| null` | The bone that dispatched the event, if any. |
| `slot` | `Slot \| null` | The slot that dispatched the event, if any. |
| `animationState` | `AnimationState` | The animation state that dispatched the event. |
| `actionData` | `ActionData \| null` | `@private` — originating action data. |
| `data` | `UserData \| null` | Custom user data attached to the action. |

### Static Helper

#### `actionDataToInstance(data: ActionData, instance: EventObject, armature: Armature): void`
- **Parameters**: `data: ActionData`, `instance: EventObject`, `armature: Armature`
- **Returns**: `void`
- **Description**: Static helper (`@private`) that converts an `ActionData` into an `EventObject`: `ActionType.Play` and `ActionType.Frame` produce `FRAME_EVENT`, `ActionType.Sound` produces `SOUND_EVENT`; then fills `name`, `armature`, `actionData`, `data`, and resolves `bone`/`slot` from the armature when the action references them.

### Example — listening and dispatching

```ts
const factory = dragonBones.PixiFactory.factory;
const armatureDisplay = factory.buildArmatureDisplay("mecha_1002_101d", "mecha_1002_101d_show");

// Listen for animation lifecycle events (Pixi-style listener):
armatureDisplay.addDBEventListener(
    dragonBones.EventObject.COMPLETE,
    (event: dragonBones.EventObject) => {
        console.log("complete:", event.animationState.name, event.armature.name);
    },
    this
);

// Frame sound events arrive on the global sound manager:
factory.soundEventManager.addDBEventListener(
    dragonBones.EventObject.SOUND_EVENT,
    (event: dragonBones.EventObject) => {
        console.log("sound:", event.name);
    },
    this
);

armatureDisplay.animation.play("idle", 0);
```

### Source
`event/EventObject.ts:46-281`
```

--------------------------------

### Bone usage example

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Bone.md

Example usage of Bone: get a bone by name, modify its offset rotation, call invalidUpdate() to commit the change for the next frame, and set visible to false to hide attached slots.

```ts
const armature = armatureDisplay.armature;
const arm = armature.getBone("arm");
if (arm) {
    arm.offset.rotation += 0.5;   // rotate the arm by ~28.6°
    arm.invalidUpdate();          // commit for next frame
    arm.visible = false;          // hide slots attached to the arm
}
```

--------------------------------

### BaseFactory.clock

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/BaseFactory.md

Gets the WorldClock associated with the factory.

```APIDOC
## BaseFactory.clock

### Description
Gets the WorldClock associated with the factory.

### Method
clock (getter)

### Signature
get clock(): WorldClock

### Returns
- **WorldClock** - The WorldClock instance.
```

--------------------------------

### Expected project structure

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Phaser/3.x/README.md

The project must have this directory layout with types, node_modules, out, and src folders. The types folder should contain phaser.d.ts.

```text
Your project
    |-- types
        |-- phaser.d.ts
    |-- node_modules
        |-- ...
    |-- out
        |-- ...
    |-- src
        |-- ...
    |-- ...
```

--------------------------------

### Build PixiJS runtime via CLI

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/BuildTools.md

Use the dbr CLI to build the PixiJS 4.8.9 runtime into the ./out folder, pulling from the npm registry.

```bash
# Build the PixiJS 4.x runtime into ./out:
dbr pixijs@4.8.9 -o ./out -r npm
```

--------------------------------

### gotoAndPlayByFrame

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Animation.md

Plays an animation starting at a specified frame.

```APIDOC
## `gotoAndPlayByFrame(animationName: string, frame: number = 0, playTimes: number = -1): AnimationState | null`

### Description
Plays an animation starting at a specified frame. The frame is translated via `duration * frame / frameCount`. Resets to pose on start.

### Method
`gotoAndPlayByFrame`

### Parameters
- **animationName** (`string`) - Required - Animation data name.
- **frame** (`number`) - Optional - Start frame. Default: `0`.
- **playTimes** (`number`) - Optional - Repeat count (see `play`). Default: `-1`.

### Returns
`AnimationState | null` - The played state, or `null` if not found.
```

--------------------------------

### gotoAndPlayByTime

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Animation.md

Plays an animation starting at a specified time.

```APIDOC
## `gotoAndPlayByTime(animationName: string, time: number = 0.0, playTimes: number = -1): AnimationState | null`

### Description
Plays an animation starting at a specified time in seconds. Resets to pose on start.

### Method
`gotoAndPlayByTime`

### Parameters
- **animationName** (`string`) - Required - Animation data name.
- **time** (`number`) - Optional - Start position in seconds. Default: `0.0`.
- **playTimes** (`number`) - Optional - Repeat count (see `play`). Default: `-1`.

### Returns
`AnimationState | null` - The played state, or `null` if not found.
```

--------------------------------

### Using WorldClock with PixiFactory and manual clock

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/WorldClock.md

Shows how to use the master clock via factory.clock to pause or slow motion, and how to create a manual standalone WorldClock with a custom timeScale, add an armature, and advance it with auto delta.

```ts
const factory = dragonBones.PixiFactory.factory;

// Use the master clock (driven by PIXI.Ticker when useSharedTicker is true):
const armatureDisplay = factory.buildArmature("mecha_1002_101d", "mecha_1002_101d_show")!.display as dragonBones.PixiArmatureDisplay;
// buildArmatureDisplay() already attaches the armature to the clock.

// Pause/resume everything:
factory.clock.timeScale = 0.0;  // freeze
factory.clock.timeScale = 0.5;  // slow motion

// Manual standalone clock (not driven by the ticker):
const bulletTime = new dragonBones.WorldClock(0.0);
bulletTime.timeScale = 0.2;
bulletTime.add(someArmature);
// in your render loop:
bulletTime.advanceTime(-1); // auto delta
```

--------------------------------

### gotoAndPlayByTime

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Animation.md

Plays an animation starting from a specified time.

```APIDOC
## [Animation] gotoAndPlayByTime

### Description
Jumps to a specific time in the animation and plays from there. Returns the created AnimationState or null if the animation does not exist.

### Method
gotoAndPlayByTime

### Parameters
- **animationName** (string) - Required - The name of the animation.
- **time** (number) - Optional - Time in seconds to jump to. Defaults to 0.0.
- **playTimes** (number) - Optional - Number of times to play. Defaults to -1 (infinite).

### Returns
- **AnimationState | null** - The created AnimationState, or null if the animation is not found.

### Example
```ts
const state = armature.animation.gotoAndPlayByTime("idle", 1.5);
```
```

--------------------------------

### Project structure

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Pixi/Demos/8.x/README.md

Required project structure for the DragonBones Pixi demo. Ensure the libs, node_modules, out, resource, and src directories are set up as shown.

```text
Your project
    |-- libs
        |-- dragonBones
            |-- dragonBones.js
            |-- ...
        |-- pixi
            |-- pixi.js
            |-- ...
    |-- node_modules
        |-- ...
    |-- out
        |-- ...
    |-- resource
        |-- ...
    |-- src
        |-- ...
    |-- ...
```

--------------------------------

### Borrow, return, and tune pools with BaseObject

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/BaseObject.md

Shows borrowing and returning a pooled EventObject, and tuning pool sizes with setMaxCount and clearPool. setMaxCount with null configures all pools; negative or NaN maxCount coerces to 0.

```ts
// Borrow and return a pooled event object (as the runtime itself does):
const eventObject = dragonBones.BaseObject.borrowObject(dragonBones.EventObject);
eventObject.type = dragonBones.EventObject.COMPLETE;
// ... dispatch ... (the runtime buffers and returns the object automatically)
eventObject.returnToPool(); // explicit early return is also legal

// Tune the pool for heavy reuse of AnimationState objects:
dragonBones.BaseObject.setMaxCount(dragonBones.AnimationState, 200);
dragonBones.BaseObject.setMaxCount(null, 5000); // all pools
dragonBones.BaseObject.clearPool(null);         // free everything
```

--------------------------------

### PixiFactory

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/PixiBinding.md

Documentation for the PixiFactory class, including static members, constructor, and methods.

```APIDOC
## PixiFactory

### Description
Factory class for creating PixiJS armature displays and textures. Extends `BaseFactory` and integrates with the shared `DragonBones` instance and `PIXI.Ticker`.

### Class
`PixiFactory extends BaseFactory`

### Static Members

#### `factory`
- **Type**: `PixiFactory` (static getter)
- **Description**: Lazily created global singleton.

#### `newInstance(useSharedTicker = true)`
- **Returns**: `PixiFactory`
- **Description**: Same singleton creation, parameterized ticker usage.

#### `useSharedTicker`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: When set, the factory hooks `PIXI.Ticker.shared` and calls `DragonBones.advanceTime` every tick (`_clockHandler`).

#### `advanceTime(passedTime)`
- **Parameters**:
  - `passedTime` (number) - Required - Time in seconds to advance the shared `DragonBones` instance.
- **Returns**: `void`
- **Description**: Manually advances the shared `DragonBones` instance.

### Constructor

#### `constructor(dataParser = null, useSharedTicker = true)`
- **Parameters**:
  - `dataParser` (`DataParser | null`) - Optional - Default `null` - Parser for JSON data (binary always uses `BinaryDataParser`).
  - `useSharedTicker` (`boolean`) - Optional - Default `true` - Whether to drive the master clock from `PIXI.Ticker.shared`.
- **Description**: On first construction, registers `new PixiDBBinParser()` into `PIXI.Assets.loader.parsers`, creates the shared `DragonBones` instance with a `PixiArmatureDisplay(PIXI.Texture.EMPTY)` event manager, and optionally subscribes the ticker. Subsequent instances share the same `DragonBones`.

### Methods

#### `buildArmatureDisplay(armatureName, dragonBonesName = "", skinName = "", textureAtlasName = "")`
- **Parameters**:
  - `armatureName` (string) - Required - Name of the armature.
  - `dragonBonesName` (string) - Optional - Default `""` - Name of the DragonBones data.
  - `skinName` (string) - Optional - Default `""` - Name of the skin.
  - `textureAtlasName` (string) - Optional - Default `""` - Name of the texture atlas.
- **Returns**: `PixiArmatureDisplay | null`
- **Description**: Calls `buildArmature` and attaches to `this._dragonBones.clock`; returns the display container. Returns `null` when data is missing.

#### `getTextureDisplay(textureName, textureAtlasName = null)`
- **Parameters**:
  - `textureName` (string) - Required - Name of the texture.
  - `textureAtlasName` (string | null) - Optional - Default `null` - Name of the texture atlas.
- **Returns**: `PIXI.Sprite | null`
- **Description**: Returns a sprite from a cached `PixiTextureData.renderTexture`.

#### `soundEventManager`
- **Returns**: `PixiArmatureDisplay`
- **Description**: The global event manager — listen to `SOUND_EVENT` here.
```

--------------------------------

### Programmatic build with BuildPixi

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/BuildTools.md

Use the programmatic API to build the PixiJS runtime by creating a BuildPixi instance and calling build with a callback.

```javascript
const { BuildPixi } = require('dragonbones-runtime');
new BuildPixi({ outFolder: 'out', version: '4.8.9', registry: 'npm' })
    .build((err) => { if (err) console.error(err); });
```

--------------------------------

### DragonBones.clock: WorldClock (getter)

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/DragonBones.md

Gets the master world clock driven by the engine ticker.

```APIDOC
## DragonBones.clock: WorldClock (getter)

### Description
Gets the master world clock driven by the engine ticker. BaseFactory.clock proxies to this.

### Method
Getter

### Returns
WorldClock

### Source
core/DragonBones.ts:346
```

--------------------------------

### Slot Properties

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Slot.md

Documentation of the Slot class properties and usage examples from the DragonBonesJS API reference.

```APIDOC
## Slot Properties

### Description
Properties of the Slot class in DragonBonesJS, used to control display, visibility, and child armatures.

### Properties

- **displayController** (`string | null`, default `null`) - Restrict which animation state/group controls the display; `null` = all states.
- **visible** (`boolean`, default `true`) - Display visibility.
- **displayFrameCount** (`number`) - Number of display frames; setter grows/shrinks the `_displayFrames` pool list.
- **displayIndex** (`number`, default `-1`) - Index of the currently shown display; setter clamps to the list and triggers an update.
- **name** (`string`) - Slot name.
- **displayList** (`Array<any>`) - Get/set the display objects of all frames.
- **slotData** (`SlotData`) - Backing slot data.
- **boundingBoxData** (`BoundingBoxData | null`, default `null`) - Current custom bounding box (from the displayed frame).
- **display** (`any`, default `null`) - Current display object (or child armature display).
- **childArmature** (`Armature | null`, default `null`) - Child armature displayed by this slot (setter assigns `display`).
- **parent** (`Bone`) - Owning bone.
- **rawDisplay** / **meshDisplay** (`any`) - Engine-provided fallback displays for images and meshes.

### Examples

#### Setting displayIndex
```ts
const slot = armature.getSlot("weapon");
slot.displayIndex = 3;
slot.displayController = "none";
```

#### Setting display
```ts
const slot = armature.getSlot("text");
slot.display = new yourEngine.TextField();   // swap in a custom display object
```

#### Setting childArmature
```ts
const slot = armature.getSlot("weapon");
const prevChildArmature = slot.childArmature;
if (prevChildArmature) { prevChildArmature.dispose(); }
slot.childArmature = factory.buildArmature("weapon_blabla", "weapon_blabla_project");
```

### Notes
Slot switching disposes previous unique displays, re-parents child armatures, inherits cache frame rate, and runs child armature actions/animations automatically (see `_updateDisplay`, `armature/Slot.ts:473-650`).
```

--------------------------------

### Required project structure

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Hilo/Demos/README.md

The project must follow this directory layout, including libs/dragonBones, libs/hilo, node_modules, out, resource, and src folders.

```text
Your project
    |-- libs
        |-- dragonBones
            |-- dragonBones.js
            |-- ...
        |-- hilo
            |-- hilo.d.ts
            |-- ...
    |-- node_modules
        |-- ...
    |-- out
        |-- ...
    |-- resource
        |-- ...
    |-- src
        |-- ...
    |-- ...
```

--------------------------------

### DragonBones.eventManager: IEventDispatcher (getter)

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/DragonBones.md

Gets the event dispatcher passed to the constructor, used for global events such as sound events.

```APIDOC
## DragonBones.eventManager: IEventDispatcher (getter)

### Description
Gets the event dispatcher passed to the constructor, used for global events such as sound events.

### Method
Getter

### Returns
IEventDispatcher

### Source
core/DragonBones.ts:350
```

--------------------------------

### Transform.toMatrix

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/Geom.md

Converts a Transform object to a Matrix. The example creates a Transform with rotation and scale, then converts it to a matrix for use with a bone.

```APIDOC
## Transform.toMatrix

### Description
Converts a Transform object to a Matrix. The example creates a Transform with rotation and scale, then converts it to a matrix for use with a bone.

### Method
`toMatrix(matrix: Matrix): void`

### Parameters
- **matrix** (Matrix) - The target matrix to receive the transformation.

### Example
```ts
const t = new dragonBones.Transform(0, 0, 0, Math.PI / 4, 1, 1);
t.toMatrix(m);
```
```

--------------------------------

### Build Egret runtime with debug traces

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/BuildTools.md

Run the dbr CLI with DEBUG=dragonbones* to enable debug output while building the Egret 5.0.0 runtime into ./dragonbones-out.

```bash
# With debug traces:
DEBUG=dragonbones* dbr egret@5.0.0 -o ./dragonbones-out
```

--------------------------------

### Listening to EventObject events

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/EventObject.md

Shows how to listen for animation lifecycle events (COMPLETE) on an armature display and for sound events on the global sound manager. Uses PixiFactory and the addDBEventListener method.

```ts
const factory = dragonBones.PixiFactory.factory;
const armatureDisplay = factory.buildArmatureDisplay("mecha_1002_101d", "mecha_1002_101d_show");

// Listen for animation lifecycle events (Pixi-style listener):
armatureDisplay.addDBEventListener(
    dragonBones.EventObject.COMPLETE,
    (event: dragonBones.EventObject) => {
        console.log("complete:", event.animationState.name, event.armature.name);
    },
    this
);

// Frame sound events arrive on the global sound manager:
factory.soundEventManager.addDBEventListener(
    dragonBones.EventObject.SOUND_EVENT,
    (event: dragonBones.EventObject) => {
        console.log("sound:", event.name);
    },
    this
);

armatureDisplay.animation.play("idle", 0);
```

--------------------------------

### Build and manage armature with PixiFactory

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/BaseFactory.md

Complete workflow using PixiFactory: load and parse data, build an armature, swap skins, and tear down. Shows autoSearch=false, master clock assignment, and cleanup calls.

```ts
const factory = dragonBones.PixiFactory.factory;   // engine factory
factory.autoSearch = false;

// 1. Load and parse
factory.parseDragonBonesData(skeletonJson, "myProject");
factory.parseTextureAtlasData(atlasJson, atlasTexture, "myProject");

// 2. Build
const armature = factory.buildArmature("hero", "myProject", "skin2");
if (armature !== null) {
    armature.clock = factory.clock;   // drive with the master clock
    armature.animation.play("run", 0);
}

// 3. Skin swap
const ok = factory.replaceSlotDisplay("myProject", "hero", "weapon", "sword_01", slot);
const okSkin = factory.replaceSkin(armature, otherSkinData, false, ["head"]);

// 4. Teardown
factory.removeDragonBonesData("myProject");
factory.clear(false);
```

--------------------------------

### Load DragonBones files and create armature in Phaser scene

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/Phaser/Demos/README.md

Loads DragonBones files and creates an armature in a Phaser scene. The preload method uses this.load.dragonbone with the atlas image, atlas JSON, and skeleton file. The skeleton file XHR settings must include responseType: "arraybuffer" if the skeleton file is in binary format. The create method uses this.add.armature to create the armature and plays the "idle" animation.

```typescript
class TestSceneToDisplay extends Phaser.Scene {    // test scene
        preload(): void {                              // override
            this.load.dragonbone(                     // load db files
                "mecha_1002_101d_show",                                         // db name
                "resource/mecha_1002_101d_show/mecha_1002_101d_show_tex.png",   // atlas image
                "resource/mecha_1002_101d_show/mecha_1002_101d_show_tex.json",  // atlas json
                "resource/mecha_1002_101d_show/mecha_1002_101d_show_ske.dbbin", // skeleton json or bin
                null,                                                           // atlas image XHR settings
                null,                                                           // atlas json XHR settings
                { responseType: "arraybuffer" }                                 // skeleton file XHR settings, must set responseType if your skeleton file is in binary format
            );
        }

        create(): void {                              // override
            const armatureDisplay = this.add.armature("mecha_1002_101d", "mecha_1002_101d_show");  // create armature, the second argument should use the name you set when load your db file in preload method, but it's actually optional, so just ignore it if you like.
            armatureDisplay.animation.play("idle");   // play animation

            armatureDisplay.x = this.cameras.main.centerX;           // set position
            armatureDisplay.y = this.cameras.main.centerY + 200;
        }
    }
```

--------------------------------

### PixiDBBinParser

Source: https://github.com/dragonbones/dragonbonesjs/blob/master/_autodocs/api-reference/PixiBinding.md

Documentation for the PixiDBBinParser class, a PIXI loader parser for binary DragonBones skeleton data.

```APIDOC
## PixiDBBinParser

### Description
A PIXI loader parser for loading binary DragonBones skeleton data (`.dbbin` files). It is automatically registered into `PIXI.Assets.loader.parsers` by the `PixiFactory` constructor.

### Methods

#### `test(url: string): boolean`
- **Description**: Determines if the given URL should be handled by this parser.
- **Parameters**:
  - `url` (string) - The URL to test.
- **Returns**: `true` if the URL contains `.dbbin`, otherwise `false`.

#### `load(url: string): Promise<ArrayBuffer>`
- **Description**: Loads the resource from the given URL and returns the raw binary data.
- **Parameters**:
  - `url` (string) - The URL of the `.dbbin` file.
- **Returns**: A `Promise` that resolves to an `ArrayBuffer` containing the binary data.

#### `parse(asset: ArrayBuffer): any`
- **Description**: Parses the loaded binary data into a `DataView` for use with DragonBones.
- **Parameters**:
  - `asset` (ArrayBuffer) - The binary data to parse.
- **Returns**: A `DataView` of the binary data.

### Usage
Feed the parsed `DataView`/`ArrayBuffer` to `factory.parseDragonBonesData` for the binary skeleton format.
```