在 PixiJS v8 中播放动画 GIF 时，用…

适用于 PixiJS v8 项目中需要加载并显示动画 GIF，并控制播放、循环、帧回调、共享 source 或释放内存的场景。

适用场景

解决思路

1. 确认使用 PixiJS v8，并在加载 GIF 前执行副作用导入：`import 'pixi.js/gif';`。`pixi.js/gif` 会调用 `extensions.add(GifAsset)`，把 `.gif` 注册到 asset loader；否则 `Assets.load` 无法识别 GIF。
2. 从 `pixi.js/gif` 导入 `GifSprite`，不要从 `pixi.js` 导入；从该路径导入命名导出也会触发副作用，因此只有不导入该路径任何内容时才需要单独写 `import 'pixi.js/gif';`。
3. 用 `Assets.load('animation.gif')` 加载动画 GIF；返回值是 `GifSource`，不是 `Texture`。
4. 用 `new GifSprite({ source })` 包装 `source`；也可简写为 `new GifSprite(source)`，等价于使用默认选项的 `{ source }`。
5. 把 `GifSprite` 加入舞台或容器，例如 `app.stage.addChild(gif)`，并像普通 `Sprite` 一样设置 `anchor`、`x`、`y` 等。
6. 构造参数 `source`：必填，类型为 `GifSource`，可由多个 `GifSprite` 实例共享。
7. 构造参数 `autoPlay`：默认 `true`；设为 `false` 时，需要手动调用 `gif.play()` 才开始播放。
8. 构造参数 `loop`：默认 `true`；设为 `false` 时，动画到最后一帧停止并触发 `onComplete`。
9. 构造参数 `animationSpeed`：默认 `1`；`2` 表示双倍速，`0.5` 表示半速，是 GIF 原生帧时序的倍数。
10. 构造参数 `autoUpdate`：默认 `true`，连接 `Ticker.shared`；设为 `false` 后需自己调用 `gif.update(ticker)` 驱动更新。
11. 构造参数 `fps`：默认 `30`；用于 GIF 未指定逐帧延迟时的兜底帧率。
12. 构造参数 `onComplete`：默认 `null`；非循环动画到达最后一帧时调用。
13. 构造参数 `onLoop`：默认 `null`；循环动画每次回绕时调用。
14. 构造参数 `onFrameChange`：默认 `null`；每次显示帧索引变化时调用，参数为 `frame: number`。
15. 构造参数 `scaleMode`：默认 `'linear'`，但自 8.13.0 起已弃用；应通过 `Assets.load(..., { data: { scaleMode } })` 传入。
16. `GifSpriteOptions` 继承 `Omit<SpriteOptions, 'texture'>`；`texture` 由内部管理，从 `source.textures[0]` 设置并逐帧切换，其他 `Sprite` 选项如 `anchor`、`scale`、`tint`、`roundPixels` 等均有效。
17. `GifSprite` 也接受所有 `Container` 选项，例如 `position`、`scale`、`tint`、`label`、`filters`、`zIndex` 等。
18. 播放控制：调用 `gif.play()` 开始播放，调用 `gif.stop()` 停止播放。
19. 跳帧控制：设置 `gif.currentFrame = 5`，帧索引从 0 开始。
20. 速度控制：设置 `gif.animationSpeed = 2` 或 `gif.animationSpeed = 0.5`。
21. 读取状态：`gif.playing` 为只读播放状态；`gif.progress` 为 0 到 1 的播放位置；`gif.totalFrames` 为帧数；`gif.duration` 为总时长，单位 ms。
22. 加载选项：使用 `Assets.load({ src: 'animation.gif', data: { fps: 12, scaleMode: 'nearest', resolution: 2 } })`；`data` 中的选项会传给 `GifSource.from`。
23. 加载选项中的 `fps` 设置未指定 timing 的 GIF 的兜底帧延迟；`scaleMode` 和 `resolution` 控制每帧创建的 canvas 纹理。
24. loader 同时匹配 `.gif` 文件扩展名和 `data:image/gif` URI；可加载 `Assets.load('data:image/gif;base64,R0lGODlh...')`。
25. 回调用法：`onComplete: () => console.log('animation finished')`；`onLoop: () => console.log('loop completed')`；`onFrameChange: (frame) => console.log('now on frame', frame)`。
26. 手动更新模式：`const gif = new GifSprite({ source, autoUpdate: false }); app.ticker.add((ticker) => { gif.update(ticker); });`。可传入任意 `Ticker` 实例，适用于私有 ticker 或暂停感知的游戏 ticker。
27. 共享 source：`const gif1 = new GifSprite({ source, autoPlay: true }); const gif2 = new GifSprite({ source, autoPlay: false });`。每个 sprite 有独立播放状态。
28. 克隆：`const gif3 = gif1.clone(); gif3.animationSpeed = 0.5;`。`clone()` 复制所有播放设置，但创建独立实例。
29. 内存释放：`gif.destroy(true)` 会连 `GifSource` 一起销毁；或 `await Assets.unload('animation.gif')` 交给资产缓存处理。`gif.destroy()` 或 `destroy(false)` 只销毁 sprite，保留 `GifSource` 和帧纹理。
30. 共享 source 时，只在最后一个消费者结束时销毁 source，或调用 `Assets.unload` 让 asset cache 管理释放。
31. 不要嵌套子节点到 `GifSprite`：它继承 `Sprite`，`allowChildren = false`，是叶子节点。要分组时包一层普通 `Container`，例如 `const group = new Container(); group.addChild(gif, label);`。
32. 性能注意：GIF 每帧解码为独立 canvas 纹理；帧数多且性能关键时，优先使用 spritesheet 加 `AnimatedSprite`，它使用单一 atlas 纹理且 GPU batching 更好。
33. 单帧静态图：如果需要 GIF 的单帧静态图，使用 `source.textures[0]`，不要写成 `const texture = await Assets.load('animation.gif'); new Sprite(texture);`。
34. 错误预防：不要忘记 `import 'pixi.js/gif';`；不要期望 `Assets.load` 返回 `Texture`；不要把 GIF 加载结果直接传给 `Sprite`。

适用边界 · 注意事项

• 性能关键且帧数很多的动画：不要用 GIF 加 `GifSprite`，优先用 spritesheet 加 `AnimatedSprite`，以获得单一 atlas 纹理和更好的 GPU batching。
• 需要把其他显示对象嵌套在 GIF 内部：不适用，`GifSprite` 是叶子节点，不支持 children；应改用普通 `Container` 分组。
• 只需要 GIF 的单帧静态图：不需要 `GifSprite`，直接取 `source.textures[0]` 作为 `Texture` 使用。