# Spine 动画集成手册

> 本手册针对 **gameabc 引擎** 的 Spine 项目，说明如何在 Canvas 2D 游戏中加载、
> 控制和管理 Spine 骨骼动画。  
> 运行时版本：**spine-canvas 4.2** | 引擎：**gameabc**

---

## 目录

1. [项目结构总览](#1-项目结构总览)
2. [快速开始：5 分钟跑通](#2-快速开始5-分钟跑通)
3. [从 Spine 编辑器导出资源](#3-从-spine-编辑器导出资源)
4. [SpineMgr 完整 API 参考](#4-spinemgr-完整-api-参考)
5. [事件系统](#5-事件系统)
6. [常见用法示例](#6-常见用法示例)
7. [与 gameabc 精灵系统配合](#7-与-gameabc-精灵系统配合)
8. [性能优化建议](#8-性能优化建议)
9. [常见问题排查](#9-常见问题排查)
10. [附录：文件加载顺序](#10-附录文件加载顺序)

---

## 1. 项目结构总览

```
Projects/Spine/
├── index.html                  ← 入口 HTML
├── js/
│   ├── spine-canvas.js         ← Spine Canvas 2D 运行时 (第三方库)
│   ├── gameabc.min.js          ← gameabc 游戏引擎
│   ├── SpineMgr.js             ← ★ Spine 动画管理器（独立文件，自动挂钩渲染）
│   ├── gamemain.js             ← 游戏主逻辑（无需修改）
│   ├── Spine_Event.js          ← Spine 事件回调 (complete / event)
│   └── Project1_Event.js       ← 精灵事件单元
├── assets/
│   ├── bmp/                    ← gameabc 图片资源
│   └── spine/                  ← ★ Spine 资源目录
│       ├── xxx.json              ← 骨骼数据 (Spine 编辑器导出)
│       ├── xxx.atlas             ← 图集描述文件
│       └── xxx.png               ← 图集纹理图片
├── output/                     ← gameabc 编译输出的配置数据
├── save/                       ← gameabc 编辑器保存的 XML
└── docs/                       ← 本文档所在目录
```

### 关键文件说明

| 文件 | 作用 | 需要修改 |
|------|------|----------|
| `js/spine-canvas.js` | Spine 4.2 Canvas 渲染运行时 | ✗ 不要修改 |
| `js/SpineMgr.js` | Spine 动画管理器，自动初始化+自动渲染 | ✗ 不需要修改 |
| `js/gamemain.js` | 游戏主逻辑（保持原样） | ✗ 不需要修改 |
| `js/Spine_Event.js` | Spine 动画完成/自定义事件回调 | ✓ 处理动画事件 |
| `assets/spine/*` | Spine 导出的资源文件 | ✓ 放入你的资源 |

---

## 2. 快速开始：5 分钟跑通

### 第一步：准备 Spine 资源

将 Spine 编辑器导出的 3 个文件复制到 `assets/spine/` 目录：

```
assets/spine/
├── hero.json       ← 骨骼 JSON
├── hero.atlas      ← 图集描述
└── hero.png        ← 图集纹理
```

### 第二步：在任意位置调用 API 播放动画

**无需手动 `load`**，直接调用 `setAnimation` 即可。如果该 Spine 实例尚未加载，会自动根据 id 查找资源（约定文件名 id.json / id.atlas）并创建实例。
渲染也已自动挂钩到 `gameenddraw`，开发者无需编写任何渲染代码。

在任何 gameabc 事件回调中直接调用即可：

```javascript
// 设置位置 + 播放动画，无需先 load
gameabc_face.spineMgr.setPosition("hero", 640, 500);
gameabc_face.spineMgr.setAnimation("hero", "idle", true);

// 之后切换动画
gameabc_face.spineMgr.setAnimation("hero", "attack", false);
```

> **约定**：id 必须与资源文件名一致（不含扩展名）。例如 id 为 `"hero"`，
> 则需要 `assets/spine/hero.json`、`hero.atlas`、`hero.png`。
>
> **可选**：如果资源不在默认路径 `assets/spine/`，可手动调用一次 `init()`：
> ```javascript
> gameabc_face.spineMgr.init("other/path/");
> ```

### 第三步：打开 index.html 即可运行

用浏览器打开 `index.html`（需要 HTTP 服务器环境，不能直接 `file://`）：

```bash
# 简易方法：在项目目录下启动 HTTP 服务
cd codes/games/client/Projects/Spine
npx http-server -p 8080
# 浏览器访问 http://localhost:8080
```

或者使用 gameabc 自带的预览环境。

---

## 3. 从 Spine 编辑器导出资源

### 导出设置（Spine 编辑器 → Export）

1. 打开 Spine 编辑器，加载你的 `.spine` 项目
2. 点击菜单 **Spine → Export...**
3. 左侧选择 **JSON** 格式
4. 配置项：

| 设置项 | 推荐值 | 说明 |
|--------|--------|------|
| Output folder | `assets/spine/` | 直接导出到项目目录 |
| Extension | `.json` | 骨骼数据格式 |
| Create atlas | ✓ 勾选 | 同时生成图集 |
| Atlas extension | `.atlas` | 图集描述格式 |
| Images folder | (默认) | 纹理来源 |
| Max width/height | 2048 / 2048 | 图集纹理最大尺寸 |
| Pack settings → Power of two | ✓ 勾选 | 纹理尺寸为 2 的幂 |
| Pack settings → Premultiply alpha | ✗ 不勾选 | Canvas 2D 不需要预乘 |

5. 点击 **Export** 按钮

### 导出后得到的文件

```
hero.json      ← 骨骼数据，包含骨骼、插槽、动画等
hero.atlas     ← 图集描述，记录每个区域在纹理中的位置
hero.png       ← 图集纹理图片
```

> **注意**：如果图集很大被拆分成多张（`hero.png`、`hero2.png`），所有 `.png`
> 都需要放到 `assets/spine/` 目录中。`.atlas` 文件会自动引用它们。

---

## 4. SpineMgr 完整 API 参考

`SpineMgr` 挂载在 `gameabc_face.spineMgr` 上，所有调用形如：

```javascript
gameabc_face.spineMgr.方法名(参数);
```

---

### 4.1 init(basePath)  *(可选)*

**手动设置资源根路径。通常无需调用——`load()` 会自动以默认路径 `"assets/spine/"` 初始化。**
仅在资源放在其他目录时才需要调用：

```javascript
gameabc_face.spineMgr.init("other/spine/path/");
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `basePath` | string | Spine 资源文件的根目录路径，需要以 `/` 结尾。省略则使用默认值 `"assets/spine/"` |

---

### 4.2 load(id, jsonFile, atlasFile, option)  *(可选)*

**手动加载一组 Spine 资源并注册为一个实例。通常无需调用——所有 API 在实例不存在时会自动加载。**

仅在以下情况需要手动调用 `load()`：
- id 与文件名不一致（如 id 为 `"mj"` 但文件为 `mj_gangshangkaihua.json`）
- 需要在加载时指定 skin、scale 等初始参数

```javascript
gameabc_face.spineMgr.load("hero", "hero.json", "hero.atlas", {
    x: 640,
    y: 500,
    scale: 0.5,
    skin: "default",
    animation: "idle",
    loop: true,
    mixDuration: 0.2
});
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | string | 唯一标识，后续所有操作通过此 id 引用 |
| `jsonFile` | string | 骨骼 JSON 文件名（相对于 basePath） |
| `atlasFile` | string | 图集 atlas 文件名（相对于 basePath） |
| `option` | object | 可选配置对象 |

**option 字段：**

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `x` | number | 0 | Canvas X 坐标 |
| `y` | number | 0 | Canvas Y 坐标 |
| `scale` | number | 1 | 初始缩放比例 |
| `skin` | string | `"default"` | 初始皮肤名称 |
| `animation` | string | null | 加载完成后自动播放的动画名 |
| `loop` | boolean | true | 默认动画是否循环 |
| `mixDuration` | number | 0.2 | 动画切换时的过渡混合时长（秒） |

---

### 4.3 setAnimation(id, animName, loop, track)

**切换动画。立即替换指定轨道上的当前动画。如果实例尚未加载，会自动根据 id 加载资源并在就绪后播放。**

```javascript
// 无需先 load，直接调用即可
gameabc_face.spineMgr.setAnimation("hero", "attack", false);
gameabc_face.spineMgr.setAnimation("hero", "run", true, 0);
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | string | - | 实例标识 |
| `animName` | string | - | 动画名称（必须在 Spine 中存在） |
| `loop` | boolean | true | 是否循环播放 |
| `track` | number | 0 | 轨道号（多轨道可叠加动画） |

**返回值：** `TrackEntry` 对象，可用于进一步控制；加载未完成时返回 `null`。

---

### 4.4 addAnimation(id, animName, loop, delay, track)

**将动画添加到播放队列，在当前动画结束后自动播放。**

```javascript
// 先播放 attack，attack 完成后自动切换到 idle
gameabc_face.spineMgr.setAnimation("hero", "attack", false);
gameabc_face.spineMgr.addAnimation("hero", "idle", true, 0);
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | string | - | 实例标识 |
| `animName` | string | - | 队列中的下一个动画 |
| `loop` | boolean | true | 是否循环 |
| `delay` | number | 0 | 延迟秒数（0 = 上一动画结束时立即开始） |
| `track` | number | 0 | 轨道号 |

---

### 4.5 setPosition(id, x, y)

**设置 Spine 实例在 Canvas 上的位置。**

```javascript
gameabc_face.spineMgr.setPosition("hero", 640, 500);
```

> Spine 的坐标原点在骨骼的根骨骼处。Y 轴向上为正（与 Canvas 的 Y 轴方向相反），
> spine-canvas 运行时已做了内部转换。

---

### 4.6 setScale(id, sx, sy)

**设置缩放。**

```javascript
gameabc_face.spineMgr.setScale("hero", 0.5);       // 等比缩放
gameabc_face.spineMgr.setScale("hero", 0.5, 0.8);  // 分别设置 X/Y
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `sx` | number | X 方向缩放 |
| `sy` | number | Y 方向缩放（省略则等于 sx） |

---

### 4.7 setFlip(id, flipX, flipY)

**水平/垂直翻转。**

```javascript
gameabc_face.spineMgr.setFlip("hero", true, false);  // 水平翻转
```

---

### 4.8 setVisible(id, visible)

**显示或隐藏 Spine 实例。**

```javascript
gameabc_face.spineMgr.setVisible("hero", false);  // 隐藏
gameabc_face.spineMgr.setVisible("hero", true);   // 显示
```

---

### 4.9 setSkin(id, skinName)

**切换皮肤。**

```javascript
gameabc_face.spineMgr.setSkin("hero", "warrior");
```

> 切换皮肤后会自动重置插槽到 Setup Pose。皮肤名必须在 Spine 编辑器中预定义。

---

### 4.10 getAnimations(id)

**获取该实例所有可用动画名称列表。**

```javascript
var anims = gameabc_face.spineMgr.getAnimations("hero");
// 返回: ["idle", "walk", "run", "attack", "die"]
logmessage("动画列表: " + anims.join(", "));
```

---

### 4.11 getSkins(id)

**获取该实例所有可用皮肤名称列表。**

```javascript
var skins = gameabc_face.spineMgr.getSkins("hero");
// 返回: ["default", "warrior", "mage"]
```

---

### 4.12 playOnce(id, animName, track)

**播放一次动画后自动隐藏。** 自动显示实例、播放指定动画（不循环），动画完成后自动设置 `visible = false`。

```javascript
// 播放一次攻击动画，播完自动隐藏
gameabc_face.spineMgr.playOnce("hero", "attack");

// 指定轨道
gameabc_face.spineMgr.playOnce("hero", "attack", 0);
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | string | - | 实例标识 |
| `animName` | string | - | 动画名称 |
| `track` | number | 0 | 轨道号 |

---

### 4.13 playQueue(id, animList, hideOnComplete)

**按顺序播放一组动画（队列），全部播完后可选择隐藏或保持显示。** 自动显示实例，队列中每个动画均播放一次（不循环），依次播放。

```javascript
// 播放 attack → die，全部播完后自动隐藏（默认）
gameabc_face.spineMgr.playQueue("hero", ["attack", "die"]);

// 播放 intro → idle，全部播完后保持显示
gameabc_face.spineMgr.playQueue("hero", ["intro", "idle"], false);
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | string | - | 实例标识 |
| `animList` | string[] | - | 动画名称数组，按顺序依次播放 |
| `hideOnComplete` | boolean | true | `true` = 队列全部播完后自动隐藏；`false` = 保持显示 |

---

### 4.14 remove(id)

**销毁指定 Spine 实例，释放内存。**

```javascript
gameabc_face.spineMgr.remove("hero");
```

---

### 4.15 removeAll()

**销毁所有 Spine 实例。**

```javascript
gameabc_face.spineMgr.removeAll();
```

### 4.16 spine_onComplete(spineId, animName, trackIndex)  *(事件回调)*

**动画完成回调。每次动画播放一轮结束时触发。** 在 `js/Spine_Event.js` 中定义。

```javascript
// 在 Spine_Event.js 中定义
gameabc_face.spine_onComplete = function(spineId, animName, trackIndex) {
    // 示例：攻击播完后恢复 idle
    if (animName === "attack") {
        gameabc_face.spineMgr.setAnimation(spineId, "idle", true);
    }
};
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `spineId` | string | 实例标识（即 load / autoLoad 时的 id） |
| `animName` | string | 刚完成的动画名称 |
| `trackIndex` | number | 轨道号（通常为 0） |

> **注意**：循环动画每播完一轮也会触发。`playOnce` / `playQueue` 的自动隐藏在此回调**之前**执行，
> 因此回调中可以检查 `visible` 状态或重新显示实例。

---

### 4.17 spine_onEvent(spineId, eventName, intValue, floatValue, stringValue)  *(事件回调)*

**自定义事件回调。当动画播放到 Spine 编辑器中定义的 Event 关键帧时触发。** 在 `js/Spine_Event.js` 中定义。

```javascript
// 在 Spine_Event.js 中定义
gameabc_face.spine_onEvent = function(spineId, eventName, intValue, floatValue, stringValue) {
    if (eventName === "footstep") {
        // 播放脚步声
    }
    if (eventName === "hit") {
        // 产生伤害判定
    }
};
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `spineId` | string | 实例标识 |
| `eventName` | string | Spine 编辑器中定义的事件名 |
| `intValue` | number | 事件的整数参数 |
| `floatValue` | number | 事件的浮点参数 |
| `stringValue` | string | 事件的字符串参数 |

> 事件需要在 Spine 编辑器的时间线中预先添加 Event Key，导出 JSON 后运行时自动解析。

---

## 5. 事件系统（详细说明）

Spine 动画在运行时会触发两类事件，回调定义在 `js/Spine_Event.js` 中。
API 签名见 [4.16](#416-spine_oncompletespineid-animname-trackindex--事件回调) 和 [4.17](#417-spine_oneventspineid-eventname-intvalue-floatvalue-stringvalue--事件回调)。

### 5.1 动画完成事件 spine_onComplete

**每次动画循环播放一轮结束时触发。**

```javascript
// 在 Spine_Event.js 中
gameabc_face.spine_onComplete = function(spineId, animName, trackIndex) {
    // spineId    : load 时的唯一标识, 如 "hero"
    // animName   : 完成的动画名, 如 "attack"
    // trackIndex : 轨道号 (通常为 0)

    // 示例：非循环攻击动画播完后恢复 idle
    if (animName === "attack") {
        gameabc_face.spineMgr.setAnimation(spineId, "idle", true);
    }
};
```

### 5.2 自定义事件 spine_onEvent

**当动画播放到 Spine 编辑器中定义的 Event 关键帧时触发。**

```javascript
// 在 Spine_Event.js 中
gameabc_face.spine_onEvent = function(spineId, eventName, intValue, floatValue, stringValue) {
    // spineId     : 唯一标识
    // eventName   : Spine 编辑器中定义的事件名
    // intValue    : 整数参数
    // floatValue  : 浮点参数
    // stringValue : 字符串参数

    if (eventName === "footstep") {
        // 播放脚步声
    }
    if (eventName === "hit") {
        // 产生伤害判定
    }
};
```

### 如何在 Spine 编辑器中添加事件

1. 打开 Spine 编辑器，选中动画
2. 在时间线底部点击右键 → **Add Event Key**
3. 在 **Tree** 面板中创建并命名事件（如 `hit`、`footstep`）
4. 可为事件设置 int / float / string 参数
5. 导出 JSON 后，运行时会自动解析并触发回调

---

## 6. 常见用法示例

### 6.1 加载多个角色

```javascript
// 在 gamestart 或任意时机，直接设置位置并播放（自动加载）
gameabc_face.spineMgr.setPosition("hero", 640, 500);
gameabc_face.spineMgr.setAnimation("hero", "idle", true);

gameabc_face.spineMgr.setPosition("npc", 300, 500);
gameabc_face.spineMgr.setAnimation("npc", "idle", true);

gameabc_face.spineMgr.setPosition("monster", 900, 500);
gameabc_face.spineMgr.setAnimation("monster", "walk", true);
```

### 6.2 播放一次后隐藏 / 队列播放

```javascript
// 播放一次攻击动画，完成后自动隐藏
gameabc_face.spineMgr.setPosition("effect", 640, 400);
gameabc_face.spineMgr.playOnce("effect", "explode");

// 队列播放：攻击 → 死亡，全部播完后自动隐藏
gameabc_face.spineMgr.playQueue("monster", ["hit", "die"]);

// 队列播放：入场 → 待机，全部播完后保持显示
gameabc_face.spineMgr.playQueue("hero", ["intro", "idle"], false);
```

### 6.3 点击切换动画（攻击→恢复）

```javascript
gameabc_face.mousedown = function(gameid, spid, downx, downy) {
    // 点击播放攻击（非循环）
    gameabc_face.spineMgr.setAnimation("hero", "attack", false);
    // 攻击完自动切回 idle
    gameabc_face.spineMgr.addAnimation("hero", "idle", true, 0);
};
```

### 6.4 角色移动 + 动画联动

```javascript
var heroState = "idle";

gameabc_face.mousedown = function(gameid, spid, downx, downy) {
    heroState = "run";
    gameabc_face.spineMgr.setAnimation("hero", "run", true);
};

gameabc_face.mouseup = function(gameid, spid_down, downx, downy, spid_up, upx, upy) {
    heroState = "idle";
    gameabc_face.spineMgr.setAnimation("hero", "idle", true);
};

gameabc_face.mousemove = function(gameid, spid, downx, downy, movex, movey, timelong, offmovex, offmovey) {
    // 通过拖拽移动角色
    var mgr = gameabc_face.spineMgr;
    var entry = mgr._entries["hero"];
    if (entry) {
        mgr.setPosition("hero", entry.x + offmovex, entry.y + offmovey);
        // 根据移动方向翻转
        mgr.setFlip("hero", offmovex < 0, false);
    }
};
```

### 6.5 多轨道叠加（走路 + 射击）

Spine 支持多轨道同时播放动画。低轨道（track 0）为基础动画，高轨道覆盖部分骨骼：

```javascript
// track 0: 下半身走路
gameabc_face.spineMgr.setAnimation("hero", "walk", true, 0);

// track 1: 上半身射击（在 Spine 编辑器中只设置上半身骨骼的关键帧）
gameabc_face.spineMgr.setAnimation("hero", "shoot", false, 1);
```

### 6.6 动态切换皮肤（换装系统）

```javascript
// 查看有哪些皮肤
var skins = gameabc_face.spineMgr.getSkins("hero");
logmessage("可用皮肤: " + skins.join(", "));

// 切换到战士皮肤
gameabc_face.spineMgr.setSkin("hero", "warrior");

// 切换到法师皮肤
gameabc_face.spineMgr.setSkin("hero", "mage");
```

### 6.7 运行时查询动画列表

```javascript
gameabc_face.spine_onComplete = function(spineId, animName, trackIndex) {
    var anims = gameabc_face.spineMgr.getAnimations(spineId);
    logmessage(spineId + " 拥有的动画: " + anims.join(", "));
};
```

---

## 7. 与 gameabc 精灵系统配合

### 渲染时序

```
gameabc 引擎循环 (每帧)
    │
    ├── gamebegindraw()          ← 帧开始
    ├── 遍历 Layer → 每个精灵:
    │       ├── gamemydrawbegin()
    │       ├── 精灵自绘 (图片/文字)
    │       └── gamemydraw()
    ├── gameenddraw()            ← 用户自定义逻辑
    │       └── (自动) spineMgr.updateAndDraw(ctx)  ← ★ 通过 defineProperty 自动追加
    └── 帧结束
```

Spine 动画在 `gameenddraw` 末尾**自动渲染**（通过 `Object.defineProperty` 拦截实现，
无论开发者如何重新定义 `gameenddraw`，Spine 渲染都不会丢失），
因此会**覆盖在所有 gameabc 精灵之上**。
开发者在 `gameenddraw` 中编写的自定义逻辑会先执行，Spine 渲染在其后自动执行。

### 如果需要 Spine 在精灵之下渲染

可以通过手动控制渲染时机来实现。在 `gamebegindraw` 中手动调用渲染，并禁用自动渲染：

```javascript
// 方式：在 gamebegindraw 中手动渲染
gameabc_face.gamebegindraw = function(gameid, spid, times, timelong) {
    var ctx = gameabc_face.dc;
    if (ctx) {
        gameabc_face.spineMgr.updateAndDraw(ctx);
    }
    // 标记自动渲染跳过（因为已在此手动渲染）
    gameabc_face.spineMgr._rendered = true;
};
```

> 注意：当前自动挂钩在 gameenddraw 末尾，如需精细控制层级，
> 可将 SpineMgr._inited 临时置 false 跳过自动渲染，手动选择渲染时机。

### 让 Spine 跟随某个精灵移动

```javascript
gameabc_face.gamemydraw = function(gameid, spid, times, timelong) {
    // 让 Spine 角色跟随精灵 1 的位置
    if (spid === 1) {
        var sx = get_self(1, 18, 0, 0, 0);  // 获取精灵 1 的 X
        var sy = get_self(1, 19, 0, 0, 0);  // 获取精灵 1 的 Y
        gameabc_face.spineMgr.setPosition("hero", sx, sy);
    }
};
```

---

## 8. 性能优化建议

### 8.1 图集纹理

- 纹理尺寸建议不超过 **2048×2048**
- 导出时勾选 **Power of two** 确保尺寸为 2 的幂
- 不要勾选 **Premultiply alpha**（Canvas 2D 不需要预乘 Alpha）

### 8.2 控制实例数量

- Canvas 2D 渲染性能有限，建议同屏 Spine 实例不超过 **5-8 个**
- 不可见的实例调用 `setVisible(id, false)`，跳过渲染和更新
- 不再需要的实例调用 `remove(id)` 释放内存

### 8.3 减少骨骼复杂度

- 骨骼数量建议控制在 **50 个**以内
- 减少网格变形（Mesh Deform），对 Canvas 2D 影响较大
- 使用裁剪（Clipping）时性能开销大，谨慎使用

### 8.4 动画混合时长

`mixDuration` 越长，过渡越平滑，但在切换瞬间需要同时计算两个动画。  
建议设为 **0.1 ~ 0.3 秒**。

---

## 9. 常见问题排查

### Q1: 画面上看不到 Spine 动画

**检查清单：**

1. **文件路径是否正确？**
   - 确认 `assets/spine/` 目录下有 `.json`、`.atlas`、`.png`
   - 文件名大小写必须一致（Linux/Mac 服务器区分大小写）

2. **是否通过 HTTP 访问？**
   - `file://` 协议无法加载跨域资源，必须使用 HTTP 服务器

3. **打开浏览器控制台（F12）看报错**
   - 404 错误：文件路径有误
   - JSON 解析错误：`.json` 文件格式异常
   - `spine is not defined`：`spine-canvas.js` 未正确加载

4. **坐标是否在可见范围内？**
   - 项目设计尺寸为 1280×720，检查 `x` 和 `y` 是否在此范围

5. **logmessage 输出是否有 "[SpineMgr] xxx 构建完成"？**
   - 有 → 加载成功，检查坐标和缩放
   - 有 "构建失败" → 查看具体错误信息
   - 没有 → 资源还在加载中或路径错误

### Q2: 动画显示位置不对

- Spine 编辑器中设置骨骼原点的位置会影响运行时的锚点
- 调整 `setPosition` 的坐标，或在 Spine 编辑器中修改根骨骼位置
- 注意 Spine 的 Y 轴与 Canvas Y 轴方向可能不同

### Q3: 动画速度太快或太慢

- 检查 `gameabc_Project` 中的 `fps` 设置（默认 30）
- SpineMgr 内部是用 `Date.now()` 计算真实时间差的，不依赖帧率
- 如果需要倍速播放，修改 `state.timeScale`：
  ```javascript
  var entry = gameabc_face.spineMgr._entries["hero"];
  entry.state.timeScale = 2.0;  // 2 倍速
  ```

### Q4: 切换动画时有跳帧

- 增大 `mixDuration`（加载时的 option 或修改 `stateData.defaultMix`）
- 使用 `addAnimation` 排队而不是直接 `setAnimation` 打断

### Q5: 多个 Spine 实例重叠时闪烁

- 确认没有同一个 id 加载两次
- 检查 `ctx.save()` / `ctx.restore()` 是否配对（SpineMgr 内部已处理）

### Q6: spine-canvas.js 版本与 Spine 编辑器版本不匹配

- **spine-canvas.js 4.2** 需搭配 **Spine 编辑器 4.2.x** 导出的数据
- 如果使用 Spine 4.1 编辑器，请下载对应版本的运行时：
  ```
  https://unpkg.com/@esotericsoftware/spine-canvas@4.1/dist/iife/spine-canvas.js
  ```

---

## 10. 附录：文件加载顺序

`index.html` 中的 script 标签加载顺序至关重要：

```
1. spine-canvas.js      ← 先加载 Spine 运行时 (定义 window.spine)
2. gameabc.min.js        ← 再加载游戏引擎
3. SpineMgr.js           ← Spine 管理器 + defineProperty 自动挂钩渲染
4. gamemain.js           ← 游戏主逻辑（不需修改，直接调用 API 即可）
5. Spine_Event.js        ← Spine 事件回调 (依赖 gameabc_face)
6. Project1_Event.js     ← 精灵事件
7. gameabc_data.min.js   ← 项目配置数据 (引擎初始化)
```

> **不能调换顺序**，`SpineMgr.js` 必须在 `gamemain.js` 之前加载，
> 否则会出现 `spine is not defined` 或 `gameabc_face.spineMgr is undefined` 的错误。

---

## 附录：完整最小示例 gamemain.js

`gamemain.js` **不需要任何修改**，保持原样即可。在任意事件回调中直接调用 `gameabc_face.spineMgr` 的 API：

```javascript
// gamemain.js —— 无需修改框架，只需在回调中调用 API

gameabc_face.gamestart = function(gameid) {
    // 直接设置位置并播放动画（自动加载，无需 load）
    gameabc_face.spineMgr.setPosition("mj_gangshangkaihua", 640, 500);
    gameabc_face.spineMgr.setAnimation("mj_gangshangkaihua", "animation", true);
};

// gameenddraw 保持原样，Spine 渲染由 SpineMgr.js 自动处理
gameabc_face.gameenddraw = function(gameid, spid, times, timelong) {
    // 这里写其他自定义绘制逻辑，或留空
};

gameabc_face.mousedown = function(gameid, spid, downx, downy) {
    // 点击播放动画
    gameabc_face.spineMgr.setAnimation("mj_gangshangkaihua", "animation", false);
};
```

> **重要**：`SpineMgr.js` 是独立文件，通过 `Object.defineProperty` 自动拦截 `gameenddraw`，
> 无论 `gamemain.js` 如何定义 `gameenddraw`，Spine 渲染都会自动追加在其后执行。
> `gamemain.js` 完全不需要修改。

---

> **参考链接**  
> - Spine 官方运行时文档: https://zh.esotericsoftware.com/spine-api-reference  
> - Spine Player 在线演示: https://jp.esotericsoftware.com/spine-player  
> - spine-canvas npm 包: https://www.npmjs.com/package/@esotericsoftware/spine-canvas