pixijs-scene-gif

GifSprite はアニメーション GIF を表示オブジェクトとして再生します。Assets.load('animation.gif') は Texture ではなく GifSource を返すため、それを GifSprite でラップします。ローダー拡張機能を登録するには、副作用を伴う import 'pixi.js/gif' が必要です。

pixijs-scene-core-concepts の知識があることを前提としています。GifSprite は Sprite を継承するリーフなので、内部に子をネストしないでください。複数の GifSprite インスタンスをグループ化する場合は、Container でラップします。

クイックスタート

import "pixi.js/gif";
import { GifSprite } from "pixi.js/gif";

const source = await Assets.load("animation.gif");

const gif = new GifSprite({
  source,
  autoPlay: true,
  loop: true,
  animationSpeed: 1,
});

gif.anchor.set(0.5);
gif.x = app.screen.width / 2;
gif.y = app.screen.height / 2;

app.stage.addChild(gif);

メモ

GIF はすべてのフレームを個別のキャンバステクスチャにデコードします。フレーム数が多く、パフォーマンスが重要なアニメーションには、AnimatedSprite を使ったスプライトシートを推奨します。単一のアトラステクスチャを使用するため、GPU でより効率よくバッチ処理できます。

関連スキル： pixijs-scene-core-concepts（シーングラフの基本）、pixijs-scene-sprite（スプライトシートベースのアニメーションに使用する AnimatedSprite）、pixijs-assets（Assets.load、キャッシュ、アンロード）、pixijs-ticker（フレームのタイミング）、pixijs-performance（テクスチャメモリ）。

コンストラクターのオプション

GifSpriteOptions は Omit<SpriteOptions, 'texture'> を拡張します。texture は内部で管理され（source.textures[0] から設定され、フレームごとに切り替わります）、その他すべての Sprite オプション（anchor、scale、tint、roundPixels など）を使用できます。また、すべての Container オプション（position、scale、tint、label、filters、zIndex など）も使用できます。詳しくは skills/pixijs-scene-core-concepts/references/constructor-options.md を参照してください。

GifSpriteOptions で追加されるリーフ固有のオプション：

オプション	型	デフォルト	説明
source	GifSource	—	必須です。Assets.load('file.gif') が返す、解析済みの GIF データです。複数の GifSprite インスタンスで共有できます。
autoPlay	boolean	true	構築時にすぐ再生を開始します。false の場合、再生を開始するには gif.play() を呼び出す必要があります。
loop	boolean	true	最終フレームに達したときにアニメーションを繰り返します。false の場合、スプライトは最終フレームで停止し、onComplete を呼び出します。
animationSpeed	number	1	GIF のネイティブなフレームタイミングに対する倍率です。2 は 2 倍速、0.5 は半分の速度で再生します。
autoUpdate	boolean	true	再生を Ticker.shared に接続します。false にすると、gif.update(ticker) を使って手動で更新できます。
fps	number	30	フレームごとの遅延時間が指定されていない GIF に使用するフォールバックのフレームレートです。
onComplete	() => void | null	null	ループしないアニメーションが最終フレームに達したときに呼び出されます。
onLoop	() => void | null	null	ループするアニメーションが一周するたびに呼び出されます。
onFrameChange	(frame: number) => void | null	null	表示中のフレームインデックスが変わるたびに呼び出されます。
scaleMode	SCALE_MODE	'linear'	8.13.0 以降は非推奨です。代わりに Assets.load(..., { data: { scaleMode } }) で scaleMode を渡してください。

コンストラクターには、唯一の引数として GifSource を直接渡すこともできます（new GifSprite(source)）。これは、上記のデフォルト値を使う new GifSprite({ source }) の省略形です。

基本パターン

セットアップと副作用インポート

import "pixi.js/gif";
import { Assets } from "pixi.js";
import { GifSprite } from "pixi.js/gif";

const source = await Assets.load("animation.gif");
const gif = new GifSprite({ source });

pixi.js/gif は extensions.add(GifAsset) を呼び出し、アセットローダーに .gif を登録します。これがないと、Assets.load は GIF ファイルを認識しません。GifSprite と GifSource は pixi.js ではなく、pixi.js/gif からエクスポートされています。

pixi.js/gif から名前付きエクスポートをインポートすると、副作用も発生するため、そのパスから何もインポートしない場合にのみ、単独の import 'pixi.js/gif' が必要です。

再生の制御

const gif = new GifSprite({ source });

gif.play();
gif.stop();

gif.currentFrame = 5;
gif.animationSpeed = 2;
gif.animationSpeed = 0.5;

gif.playing; // read-only
gif.progress; // 0-1 playback position
gif.totalFrames; // number of frames
gif.duration; // total duration in ms

autoPlay: true（デフォルト）にするとすぐに再生が始まり、loop: true（デフォルト）にすると繰り返し再生されます。animationSpeed は GIF のネイティブなフレーム間隔に対する倍率です。currentFrame はゼロ始まりです。

読み込みオプション

const source = await Assets.load({
  src: "animation.gif",
  data: {
    fps: 12,
    scaleMode: "nearest",
    resolution: 2,
  },
});

const fromDataUri = await Assets.load("data:image/gif;base64,R0lGODlh...");

data 内のオプションは GifSource.from に渡されます。fps は、タイミングが指定されていない GIF のフォールバックとなるフレーム遅延を設定します。scaleMode と resolution は、各フレーム用に作成されるキャンバステクスチャを制御します。ローダーは .gif ファイル拡張子と data:image/gif URI の両方に一致します。

コールバック

const gif = new GifSprite({
  source,
  loop: false,
  onComplete: () => console.log("animation finished"),
  onLoop: () => console.log("loop completed"),
  onFrameChange: (frame) => console.log("now on frame", frame),
});

• onComplete は、ループしないアニメーションが最後のフレームに到達したときに呼び出されます。
• onLoop は、ループするアニメーションが一周するたびに呼び出されます。
• onFrameChange は、表示中のフレームが変わるたびに呼び出されます。

手動更新モード

const gif = new GifSprite({ source, autoUpdate: false });

app.ticker.add((ticker) => {
  gif.update(ticker);
});

autoUpdate: false にすると、Ticker.shared との接続が解除されます。任意の Ticker インスタンスを渡して、自分で gif.update(ticker) を呼び出します。プライベートなティッカー（例：一時停止に対応したゲームティッカー）でアニメーションを制御する場合に便利です。

ソースデータの共有と複製

const source = await Assets.load("animation.gif");

const gif1 = new GifSprite({ source, autoPlay: true });
const gif2 = new GifSprite({ source, autoPlay: false });

const gif3 = gif1.clone();
gif3.animationSpeed = 0.5;

GifSource は複数の GifSprite インスタンス間で共有できます。各スプライトは独立した再生状態を持ちます。clone() はすべての再生設定をコピーしますが、独立したインスタンスを作成します。

よくある間違い

[HIGH] pixi.js/gif をインポートしない

誤り：

import { Assets } from "pixi.js";
const gif = await Assets.load("animation.gif");

正しい例：

import "pixi.js/gif";
import { Assets } from "pixi.js";
const source = await Assets.load("animation.gif");

GIF ローダー拡張機能は、読み込み前に登録する必要があります。副作用インポートがないと、ローダーは .gif ファイルを認識できず、読み込みに失敗するか、生データが返されます。

[MEDIUM] Assets.load が Texture を返すと思い込む

誤り：

const texture = await Assets.load("animation.gif");
const sprite = new Sprite(texture);

正しい例：

const source = await Assets.load("animation.gif");
const gif = new GifSprite({ source });

GIF に対する Assets.load は、フレームテクスチャとタイミングデータを含む GifSource を返します。ソースを GifSprite に渡してください。静止画の単一フレームを使用する場合は、source.textures[0] を読み取ります。

[MEDIUM] 破棄時に GIF メモリが解放されない

誤り：

gif.destroy();
// GifSource and frame textures remain in memory

正しい例：

gif.destroy(true);
// or
await Assets.unload("animation.gif");

GIF フレームは、個別のキャンバステクスチャとしてデコード済みピクセルデータを保持します。gif.destroy()（または destroy(false)）はスプライトを破棄しますが、GifSource はそのまま保持します。ソースも破棄するには true を渡します。ソースを共有している場合は、最後の利用者が使い終わってから破棄するか、Assets.unload を呼び出してアセットキャッシュに処理させてください。

[LOW] GifSprite 内に子要素をネストしない

GifSprite は Sprite を継承しており、allowChildren = false に設定されています。つまり、リーフ要素です。GIF を他の表示オブジェクトとグループ化するには、それらすべてを通常の Container で囲みます。

const group = new Container();
group.addChild(gif, label);

API リファレンス

• GifSprite
• GifSpriteOptions
• GifSource
• GifAsset
• GifBufferOptions
• GifFrame