动画组件

admin

1. 我将查看动画组件的代码来生成详细的使用文档。
   
2. Read file: 动画组件.js
   
3. 让我基于代码内容为您编写一个详细的使用文档：
   
4. 
   
5. # 动画组件使用文档
   
6. 
   
7. ## 1. 组件概述
   
8. 
   
9. 动画组件是一个用于播放序列帧动画的PIXI.js组件，支持多方向、多动作的动画播放控制。
   
10. 
    
11. ### 主要特性
    
12. - 支持2/4/5/8方向动画
    
13. - 支持动作(action)、方向(dir)、状态切换
    
14. - 支持播放速度调整和进度控制
    
15. - 支持动态资源加载和内存管理
    
16. - 支持动作级和全局的镜像配置
    
17. - 支持自定义锚点设置
    
18. - 支持偏移(x.txt)文件
    
19. 
    
20. ## 2. 基础使用
    
21. 
    
22. ### 创建实例
    
23. ```javascript
    
24. const anim = new 动画组件();
    
25. ```
    
26. 
    
27. ### 初始化
    
28. ```javascript
    
29. anim.初始化(x, y, {
    
30.     路径: 'assets/role/{action}_{dir}_{frame}.png',
    
31.     动作列表: {
    
32.         stand: { 帧数: 6, fps: 6 },
    
33.         run: { 帧数: 8, fps: 10 },
    
34.         attack: { 帧数: 6, fps: 8 }
    
35.     },
    
36.     方向数: 8
    
37. });
    
38. ```
    
39. 
    
40. ### 添加到场景
    
41. ```javascript
    
42. scene.addChild(anim.获取容器());
    
43. ```
    
44. 
    
45. ### 播放动画
    
46. ```javascript
    
47. anim.播放('stand', 2, true); // 动作名, 方向, 是否循环
    
48. ```
    
49. 
    
50. ## 3. 配置参数说明
    
51. 
    
52. ### 全局配置
    
53. ```javascript
    
54. {
    
55.     路径: 'assets/role/{action}_{dir}_{frame}.png', // 必填，支持{action} {dir} {frame}占位符
    
56.     动作列表: Object,                               // 必填，动作配置对象
    
57.     方向数: 2|4|5|8,                               // 可选，默认8
    
58.     格式: 'png|jpg|webp',                          // 可选，默认'png'
    
59.     起始帧: 0,                                     // 可选，默认0
    
60.     锚点像素X: 256,                                // 可选，默认256
    
61.     锚点像素Y: 256,                                // 可选，默认256
    
62.     mirrorPairs: [[0,4], [1,3]]                    // 可选，全局镜像配置
    
63. }
    
64. ```
    
65. 
    
66. ### 动作配置
    
67. ```javascript
    
68. {
    
69.     帧数: number,           // 必填，动作总帧数
    
70.     fps: number,            // 可选，默认10
    
71.     方向: number,           // 可选，覆盖全局方向数
    
72.     起始帧: number,         // 可选，覆盖全局起始帧
    
73.     anchor: {x: number, y: number}, // 可选，动作级锚点
    
74.     mirrorPairs: [[0,4], [1,3]]    // 可选，动作级镜像配置
    
75. }
    
76. ```
    
77. 
    
78. ## 4. API参考
    
79. 
    
80. ### 核心方法
    
81. 
    
82. #### 初始化(x, y, 配置)
    
83. - 参数：
    
84.   - x: number - X坐标
    
85.   - y: number - Y坐标
    
86.   - 配置: Object - 动画配置对象
    
87. - 返回：Promise<void>
    
88. 
    
89. #### 播放(动作名, 方向, 循环)
    
90. - 参数：
    
91.   - 动作名: string - 要播放的动作名称
    
92.   - 方向: number - 动画方向(0-7)
    
93.   - 循环: boolean - 是否循环播放
    
94. - 返回：void
    
95. 
    
96. #### 暂停()
    
97. 暂停当前动画播放
    
98. 
    
99. #### 继续()
    
100. 继续播放当前动画
     
101. 
     
102. #### 停止()
     
103. 停止动画播放并重置到第一帧
     
104. 
     
105. ### 状态控制
     
106. 
     
107. #### 设置速度(speed)
     
108. - 参数：speed: number - 播放速度倍率，1为正常速度
     
109. 
     
110. #### 设置进度(progress)
     
111. - 参数：progress: number - 0到1之间的进度值
     
112. 
     
113. #### 跳转到(frame)
     
114. - 参数：frame: number - 目标帧序号
     
115. 
     
116. ### 事件监听
     
117. 
     
118. #### on(事件名, 回调函数)
     
119. 添加事件监听器
     
120. ```javascript
     
121. anim.on('complete', () => console.log('动画播放完成'));
     
122. ```
     
123. 
     
124. #### off(事件名, 回调函数)
     
125. 移除事件监听器
     
126. 
     
127. #### once(事件名, 回调函数)
     
128. 添加一次性事件监听器
     
129. 
     
130. ### 支持的事件
     
131. - 'complete' - 动画播放完成
     
132. - 'loop' - 动画循环播放
     
133. - 'frame' - 帧更新
     
134. 
     
135. ## 5. 高级特性
     
136. 
     
137. ### 镜像配置
     
138. 支持两种级别的镜像配置：
     
139. 1. 全局镜像：在初始化配置中设置
     
140. 2. 动作级镜像：在具体动作配置中设置
     
141. ```javascript
     
142. {
     
143.     mirrorPairs: [[0,4], [1,3]], // 方向0镜像到4，方向1镜像到3
     
144. }
     
145. ```
     
146. 
     
147. ### 偏移支持
     
148. - 通过x.txt文件配置每帧的偏移量
     
149. - 格式：每行两个数字，分别表示x和y的偏移值
     
150. ```
     
151. 10 20
     
152. 15 25
     
153. 20 30
     
154. ```
     
155. 
     
156. ## 6. 注意事项
     
157. 
     
158. 1. 资源命名规范
     
159.    - 图片文件名必须符合路径模板格式
     
160.    - 偏移文件(x.txt)需要放在相同目录下
     
161. 
     
162. 2. 性能优化
     
163.    - 合理设置fps避免性能问题
     
164.    - 不使用时调用销毁()释放资源
     
165. 
     
166. 3. 方向说明
     
167.    - 8方向：0-7，从上开始顺时针
     
168.    - 5方向：自动镜像补全
     
169.    - 2/4方向：按需配置
     
170. 
     
171. 4. 内存管理
     
172.    - 组件会自动管理纹理资源
     
173.    - 使用销毁()方法清理资源
     
174. 
     
175. ## 7. 示例代码
     
176. 
     
177. ```javascript
     
178. // 创建并初始化动画组件
     
179. const anim = new 动画组件();
     
180. await anim.初始化(100, 200, {
     
181.     路径: 'assets/character/{action}_{dir}_{frame}.png',
     
182.     动作列表: {
     
183.         idle: {
     
184.             帧数: 8,
     
185.             fps: 10,
     
186.             anchor: {x: 256, y: 256},
     
187.             mirrorPairs: [[1,3]]
     
188.         },
     
189.         walk: {
     
190.             帧数: 8,
     
191.             fps: 12,
     
192.             方向: 4
     
193.         }
     
194.     },
     
195.     方向数: 8,
     
196.     锚点像素X: 256,
     
197.     锚点像素Y: 256
     
198. });
     
199. 
     
200. // 添加到场景
     
201. scene.addChild(anim.获取容器());
     
202. 
     
203. // 播放动画
     
204. anim.播放('idle', 0, true);
     
205. 
     
206. // 监听事件
     
207. anim.on('complete', () => {
     
208.     console.log('动画播放完成');
     
209. });
     
210. 
     
211. // 控制播放
     
212. anim.设置速度(1.5);
     
213. anim.暂停();
     
214. anim.继续();
     
215. ```
     
216. 
     
217. 这个文档涵盖了动画组件的所有主要功能和使用方法。如果您有任何具体的问题或需要更详细的说明，请随时询问。

复制代码

admin

让我检查代码中关于添加动作的API。
Ran tool
让我查看添加动作API的具体实现：
Read file: 动画组件.js
我为您补充添加动作API的文档说明：

## 4. API参考（补充）

### 动态添加动作

#### 添加动作(actionName, info)
在初始化后动态添加新的动作。

- 参数：
  - actionName: string - 动作名称
  - info: Object - 动作配置对象
    ```javascript
    {
        帧数: number,     // 必填，动作的总帧数
        fps: number,      // 可选，默认10，动画播放速率
        起始帧: number,   // 可选，默认使用全局配置的起始帧
        方向: number,     // 可选，覆盖全局方向数
        anchor: {         // 可选，动作级锚点设置
            x: number,    // 锚点X坐标（像素）
            y: number     // 锚点Y坐标（像素）
        },
        mirrorPairs: Array // 可选，动作级镜像配置，如 [[0,4], [1,3]]
    }
    ```
- 返回：Promise<void>
- 事件：
  - '动作已加载' - 当动作加载完成时触发
  - '加载错误' - 当加载过程中发生错误时触发

示例：
```javascript
// 添加新动作
await anim.添加动作('攻击', {
    帧数: 30,
    fps: 12,
    起始帧: 97,
    方向: 8,
    anchor: { x: 256, y: 256 },
    mirrorPairs: [[1,3], [2,6]]
});

// 监听加载完成
anim.on('动作已加载', (actionName) => {
    console.log(`动作 ${actionName} 加载完成`);
});
```

注意事项：
1. 动作名称不能重复，如果添加已存在的动作名会被忽略
2. 帧数参数是必须的，其他参数都是可选的
3. 动作级配置（方向数、锚点等）会覆盖全局配置
4. 资源路径使用初始化时配置的路径模板
5. 支持动态加载偏移文件(x.txt)
6. 添加动作是异步操作，建议等待加载完成后再使用

这个API允许您在初始化动画组件后，根据需要动态添加新的动作，非常适合按需加载资源的场景。每个新添加的动作都可以有自己的配置参数，包括帧数、播放速度、方向数、锚点位置等，使用方式与初始化时的动作配置完全一致。

admin

动画组件（动画组件.js）——完整使用文档  
（基于 2025-07 的最新同步版）

================================================================
一、核心概念
================================================================
1. 外观（Skin）  
   一套共享序列帧素材，可由多个「来源」组成  
   - 类型 1：文件夹 `…/x.txt + 1.png ~ N.png`  
   - 类型 2：ZIP（ani.json + 图集）—暂未启用

2. 外观总表 `window.MX_APPEAR`（唯一真源）  
   ```
   MX_APPEAR[外观名] = {
     cfgs      : [{ 类型, 基础 } …],   // 每条 = 一种来源
     meta      : { 方向数, mirrorPairs, 锚点像素X, 锚点像素Y },
     frameDefs : { 动作名 : { …完整动作配置… } },
     baseStart : 1,                    // 文件夹起始帧
     clips     : { act -> dir -> clip },
     actionMirrorMap : { act -> {dir:mirrorDir} }
     users     : Set<实例ID>,          // 引用计数
     status    : 'unloaded' | 'loading' | 'ready'
   }
   ```

3. clip 描述（所有实例共享）
   ```
   {  start   : <起始下标>,
     len     : <帧数>,
     fps     : <帧率>,
     offsets : Float32Array(subarray),
     anchor  : {x,y},
     flip    : false | true }
   ```

================================================================
二、动作配置（frameDef）字段
================================================================
必填  
• 起始帧    (number) 本动作第一帧（从 1 开始）  
• 帧数      (number) 总帧数（单方向）

可选  
• fps       (number) 默认为 10  
• 方向      (1 2 4 5 8) 默认为 1  
• 翻转      (array)   形如 `[[1,3],[2,4]]`  
• 锚点x/y   (number)  覆盖外观级锚点  
• 播放次数  (number)  -1=无限（默认）；>0 播完停止

================================================================
三、初始化配置 cfg
================================================================
名称-模式 （推荐）
```
{
  名称        : '外观A',            // 必填
  // ↓ 全为可选：若写入会合并到 MX_APPEAR[名称].meta / frameDefs
  动作列表    : { …frameDefs… },
  起始帧      : 1,
  方向数      : 8,
  mirrorPairs : [[5,3],[6,2]],
  锚点像素X   : 256,
  锚点像素Y   : 256
}
```

路径模板模式（兼容旧代码）
```
{
  路径        : '…/{action}_{dir}_{frame}.png', // 必填
  动作列表    : { …必填… },
  方向数      : 8,
  mirrorPairs : …,
  起始帧      : 1,
  锚点像素X/Y : …
}
```

================================================================
四、静态 API（类方法）
================================================================
1. 批量注册  
```js
动画组件.批量注册([ cfgObj, … ])
```
• cfgObj 字段同“初始化 cfg”，必含 `类型/外观/路径`  
• 已存在同名+同路径时覆盖；可多次调用

2. 卸载外观 / 动作 / 方向  
```js
动画组件.卸载外观('外观A');
动画组件.卸载动作('外观A','走路');
动画组件.卸载方向('外观A','走路',3);
```
• 引用计数 `users.size==0` 时才能真正销毁；否则实例会透明→懒加载

3. 内部 Loader（自动调用）  
```js
动画组件._ensureAppearanceLoaded('外观A');
```

================================================================
五、实例 API
================================================================
| 方法                               | 说明 |
|------------------------------------|------|
| 初始化(x,y,cfg)                    | 创建并加载外观 |
| 播放(action, dir=0, loop=true,<unloadPrev>) | 播放动作；`unloadPrev` 为 true 时卸载上一个动作纹理 |
| 设置状态(action,<loop>)            | 仅换动作 |
| 设置方向(dir,<loop>)              | 仅换方向 |
| 暂停 / 继续                        | 控制播放 |
| 设置速度(speed)                    | 倍速 |
| 设置帧(idx) / 设置进度(0-1)        | 定位 |
| 添加动作(name, frameDef)           | 运行期追加动作（名称模式会写入 frameDefs 并重切片） |
| 设置外观('外观B')                 | 切换外观 |
| 设置自动卸载动作(bool)             | 开/关「切动作→销旧纹理」 |
| 销毁资源()                         | 仅销毁本实例的 clip 纹理 |
| 销毁()                              | 移除 Ticker & Container，users-1 |

事件（on/off/once）  
• '初始化完成' • '外观切换完成' • '动作已加载' • '加载错误'

================================================================
六、典型流程示例
================================================================
```js
// 1. 启动：批量注册
动画组件.批量注册([
  { 类型:1, 外观:'外观A', 路径:'http://…/1/', 起始帧:1, 动作列表:{ 站立:{…}, 走路:{…} } },
  { 类型:1, 外观:'外观B', 路径:'http://…/2/' }
]);

// 2. 实例化
const role = new 动画组件();
role.on('初始化完成', () => role.播放('站立',0,true));
role.初始化(100,200,{ 名称:'外观A' });

// 3. 切动作 & 自动卸载上一动作
role.设置自动卸载动作(true);
role.播放('走路',2,true);   // 站立纹理立即释放

// 4. 动态添加新动作
role.添加动作('攻击',{ 起始帧:97, 帧数:60, fps:12, 方向:8 });
role.播放('攻击',0,false);

// 5. 切换皮肤
role.设置外观('外观B');

// 6. 全局显存清理
动画组件.卸载外观('外观A');
```

这样即可在多实例、频繁切换动作/外观的场景下，确保  
• 纹理 & 偏移数组全局唯一复用  
• 可以按外观 / 动作 / 方向粒度释放  
• 自动懒加载，始终可见、无红字报错  
• 显存占用保持在“当前动作 ± 缓存阈值” 수준。