pixijs-scene-gif

GifSprite はアニメーション GIF をディスプレイオブジェクトとして再生します。Assets.load('animation.gif') は (Texture ではなく) GifSource を返し、これを GifSprite でラップします。GIF ローダー拡張を登録するには、サイドエフェクト 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);

[!NOTE] 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'	v8.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/gif からエクスポートされており、pixi.js からではありません。

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; // 読み取り専用
gif.progress; // 0-1 再生位置
gif.totalFrames; // フレーム数
gif.duration; // ミリ秒単位の総時間

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 から切断されます。gif.update(ticker) を自分で呼び出し、任意の 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 とフレームテクスチャはメモリに残る

正解:

gif.destroy(true);
// または
await Assets.unload("animation.gif");

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

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

GifSprite は Sprite を拡張し、allowChildren = false を設定します。これはリーフです。GIF を他のディスプレイオブジェクトとグループ化するには、すべてを plain な Container でラップしてください:

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

API リファレンス

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