pixijs-assets

Assets API は、PixiJS のアセットローダー、リゾルバー、キャッシュをひとつにまとめたシングルトンです。フォーマットの検出、解像度の切り替え、バンドルのグループ化、進捗の追跡、GPU リソースのクリーンアップを行いながら、テクスチャ、動画、スプライトシート、フォント、JSON などのリソースを読み込めます。

クイックスタート

await Assets.init({ basePath: "/static/" });

const texture = await Assets.load("bunny.png");
const sprite = new Sprite(texture);
app.stage.addChild(sprite);

const [hero, enemy] = await Assets.load(["hero.png", "enemy.png"]);

await Assets.load({
  alias: "logo",
  src: "logo.webp",
});

const logo = new Sprite(Assets.get("logo"));

Assets.init() は省略できますが、basePath、texturePreference、マニフェストを設定する場合は推奨されます。初期化後、URL、エイリアス、配列、または UnresolvedAsset を指定して Assets.load() を呼び出します。解決済みのアセットはキャッシュされ、Assets.get() によって再解決されます。

サポートされているファイル形式

種類	拡張子	パーサー ID	ローダー
テクスチャ	.png、.jpg、.jpeg、.webp、.avif	texture	loadTextures
SVG	.svg	svg	loadSvg（references/svg.md を参照）
動画テクスチャ	.mp4、.m4v、.webm、.ogg、.ogv、.h264、.avi、.mov	video	loadVideoTextures（references/video.md を参照）
スプライトシート	.json（スプライトシート形式）	spritesheet	spritesheetAsset（references/spritesheet.md を参照）
ビットマップフォント	.fnt、.xml	bitmap-font	loadBitmapFont（読み込みはデフォルトで動作します。BitmapText のレンダリングには 'pixi.js/text-bitmap' が必要です。references/fonts.md を参照）
Web フォント	.ttf、.otf、.woff、.woff2	web-font	loadWebFont（references/fonts.md を参照）
JSON	.json	json	loadJson
テキスト	.txt	text	loadTxt
圧縮テクスチャ	.basis、.dds、.ktx、.ktx2	basis、dds、ktx、ktx2	references/compressed-textures.md を参照
アニメーション GIF	.gif	gif	'pixi.js/gif' が必要です。GifSource を返します（references/gif.md を参照）

パーサー ID 列の値は、特定のローダーを強制的に使用するために、アセット記述子の最上位の parser フィールドに指定します。詳しくは、以下の「パーサーの指定」を参照してください。

parserでパーサーを強制する

デフォルトでは、PixiJS はファイル拡張子または MIME タイプに基づいてローダーを選択します。URL に拡張子がない場合（CDN の署名付き URL、blob URL、API エンドポイント、コンテンツハッシュ付きパスなど）、リゾルバーはどのローダーを使うべきか判断できません。特定のローダーを強制するには、アセット記述子の最上位にあるparserフィールドを設定します。

// Signed CDN URL with no extension
const texture = await Assets.load({
  src: "https://cdn.example.com/signed/abc123?token=xyz",
  parser: "texture",
});

// API endpoint that returns JSON
const data = await Assets.load({
  alias: "config",
  src: "https://api.example.com/v1/config",
  parser: "json",
});

// Extension-less font URL with explicit family
await Assets.load({
  src: "https://cdn.example.com/fonts/hero-v2",
  parser: "web-font",
  data: { family: "Hero", weights: ["400", "700"] },
});

// Video stream without a file extension
const clipTexture = await Assets.load({
  src: "https://cdn.example.com/stream/xyz",
  parser: "video",
  data: { mime: "video/mp4", muted: true, playsinline: true },
});

parserフィールドは、dataの中ではなく、アセット記述子の最上位（srcやdataと同じ階層）に置きます。「サポートされているファイルタイプ」の表にある任意のパーサー ID を指定できます。

• 'texture'、'svg'、'video'：画像、SVG、動画テクスチャ
• 'json'、'text'：JSON とプレーンテキスト
• 'web-font'、'bitmap-font'：ウェブフォントとビットマップフォント
• 'spritesheet'：テクスチャアトラスの JSON
• 'gif'：アニメーション GIF（'pixi.js/gif'が必要）
• 'basis'、'dds'、'ktx'、'ktx2'：圧縮テクスチャ（それぞれ副作用インポートが必要）

必要となるケース

• CDN の署名付き URL：https://cdn.example.com/get?id=abc123には、ローダーが照合できる拡張子がありません。
• Blob または ObjectURL：URL.createObjectURL(blob)は、拡張子のないblob:... URL を生成します。
• カスタムルーティング：/api/assets/hero-v2のように、コンテンツタイプをサーバーが決定する場合。
• 拡張子のないコンテンツハッシュ付きパス：ビルドパイプラインによっては、/static/abc123def.pngではなく、/static/abc123defのような名前が生成されます。

URLに拡張子がある場合、parserは不要です。自動検出に任せてください。検出できない場合にのみparserを設定します。

loadParserは非推奨です

v7 のloadParserフィールドは引き続き動作しますが、非推奨の警告が表示されます。新しいコードではparserを使用してください。

// Old (deprecated)
await Assets.load({ src: "...", loadParser: "loadTextures" });

// New
await Assets.load({ src: "...", parser: "texture" });

トピック

各アセットのワークフローについて、リファレンスファイルで説明しています。質問に合ったものを選んでください。

トピック	リファレンス	対象となる内容
テクスチャアトラスとアニメーション	references/spritesheet.md	AnimatedSpriteを使ったスプライトシートの読み込み
動画テクスチャ	references/video.md	.mp4、.webm、自動再生、ループ、モバイル
ウェブフォントとビットマップフォント	references/fonts.md	.woff2、.fnt、フォントファミリー、SDF フォント
アニメーション GIF	references/gif.md	.gif、GifSprite、再生コントロール
機能ごとのアセットのグループ化	references/bundles.md	addBundle、loadBundle、unloadBundle
すべてを事前に宣言する	references/manifests.md	Assets.init({ manifest })のワークフロー
キャッシュの検索とクリーンアップ	references/caching.md	Assets.get、Assets.unload、Cache
今後使うアセットの事前読み込み	references/background.md	backgroundLoad、backgroundLoadBundle
ローディング画面	references/progress.md	onProgress、LoadOptions の進捗
GPU 圧縮形式	references/compressed-textures.md	.ktx2、.basis、.dds、.ktx
ベクター SVG とラスター SVG	references/svg.md	parseAsGraphicsContext、テクスチャモード
Retina と形式の検出	references/resolution.md	@{1,2}x、formatの優先設定

選択ガイド

• 画像を1枚だけ読み込む必要がありますか？ Assets.load(url) を使用します。セットアップは不要です。
• レベルやシーンごとにまとめた多数のアセットを読み込みますか？ バンドルを使用します。references/bundles.md を参照してください。
• ビルド時にすべてのアセットがわかっていますか？ Assets.init でマニフェストを使用します。references/manifests.md を参照してください。
• ローディングバーが必要ですか？ Assets.load に進捗コールバックを渡します。references/progress.md を参照してください。
• レベル間をスムーズに遷移させますか？ 次のレベルをバックグラウンドで読み込みます。references/background.md を参照してください。
• メモリ予算が重要ですか？ 圧縮テクスチャを使用し、画面切り替え時に Assets.unload を実行します。references/compressed-textures.md と references/caching.md を参照してください。
• どのサイズでも鮮明なSVGアイコンが必要ですか？ テクスチャではなく、Graphicsとして読み込みます。references/svg.md を参照してください。
• RetinaとWebP/AVIFを使用しますか？ texturePreference を設定し、フォーマットパターンを使用します。references/resolution.md を参照してください。

読み込みオプションとエラー処理

アセットの読み込みには、別々の「オプション」の概念が2つあります。

1. LoadOptions：Assets.load／loadBundle の第2引数です。読み込み全体のエラー回復、再試行、進捗、完了コールバックを制御します。
2. data：各アセット記述子のフィールドです。パーサー固有のオプション（スケールモード、解像度、フォントファミリー、自動再生フラグなど）を、そのアセット用の特定のローダーに渡します。

LoadOptions（呼び出しごと）

await Assets.load(["hero.png", "enemy.png"], {
  onProgress: (p) => updateBar(p),
  onError: (err, url) => {
    const src = typeof url === "string" ? url : url.src;
    console.warn("failed:", src, err);
  },
  strategy: "retry",
  retryCount: 3,
  retryDelay: 250,
});

• onProgress(progress)：呼び出し内のアセットの読み込み完了に応じた [0, 1] の値です。
• onError(error, url)：url は string | ResolvedAsset です。.src を読み取る前に型を確認してください。url が文字列の場合、.src は undefined です。
• strategy: 'throw' | 'skip' | 'retry' — デフォルトは 'throw' です。'skip' は読み込みに成功したアセットを解決し、'retry' は失敗したアセットを再試行します。
• retryCount — デフォルトは 3 で、strategy が 'retry' の場合にアセットごとに再試行する回数です。
• retryDelay — 再試行間の待機時間です。デフォルトは 250 ms です。

グローバルなデフォルト値は Loader.defaultOptions に設定するか、Assets.init() に loadOptions を渡します。

data オプション（アセットごと）

各ローダーパーサーは、アセット記述子の data フィールドから独自のオプションを読み取ります。アセットの種類ごとに適切なオプションを選ぶには、以下の表を使用してください。

アセットの種類	data の形状	主なオプション	参考資料
テクスチャ（画像）	TextureSourceOptions	resolution、scaleMode、alphaMode、autoGenerateMipmaps、antialias、addressMode	references/resolution.md
SVG	{ parseAsGraphicsContext?, resolution? }	Graphics モードでは parseAsGraphicsContext、より鮮明にラスター化するには resolution	references/svg.md
ビデオ	VideoSourceOptions	autoPlay、loop、muted、playsinline、preload、updateFPS、crossorigin、mime	references/video.md
Web フォント	LoadFontData	family、weights、style、display、unicodeRange、featureSettings	references/fonts.md
ビットマップフォント	(none; auto-configured)	距離フィールドの検出により、スケールモードとミップマップが設定されます	references/fonts.md
スプライトシート	{ texture?, imageFilename?, ignoreMultiPack?, textureOptions?, cachePrefix? }	textureOptions は TextureSourceOptions（例：scaleMode）をアトラス画像に渡します。texture は画像の読み込みを省略します。imageFilename は参照先の画像を上書きします。ignoreMultiPack はマルチパックの後続処理を省略します。cachePrefix はフレームの名前空間を指定します	references/spritesheet.md
GIF	GifBufferOptions	fps、scaleMode、resolution、autoGenerateMipmaps	references/gif.md
圧縮テクスチャ	TextureSourceOptions	scaleMode、addressMode、autoGenerateMipmaps	references/compressed-textures.md
JSON / テキスト	(none)	そのまま返されます	—
LoadOptions と data を組み合わせる例：

await Assets.load(
  {
    alias: "hero",
    src: "hero.png",
    data: { scaleMode: "nearest", resolution: 2 },
  },
  { strategy: "retry", retryCount: 3 },
);

マニフェストまたはバンドル内では、各エントリに独自の data を指定できます。

await Assets.init({
  manifest: {
    bundles: [
      {
        name: "level1",
        assets: [
          { alias: "tiles", src: "tiles.png", data: { scaleMode: "nearest" } },
          { alias: "font", src: "hero.woff2", data: { family: "Hero" } },
          {
            alias: "clip",
            src: "intro.mp4",
            data: { autoPlay: false, muted: true },
          },
        ],
      },
    ],
  },
});

ランタイム設定

Assets.init(options) では、basePath と manifest に加えて、以下を指定できます。

• defaultSearchParams — 解決されたすべての URL に追加する文字列または Record<string, any> です。キャッシュバスティングに便利です。
• skipDetections: boolean — 初期化を高速化するため、ブラウザーのフォーマット検出をスキップします。texturePreference.format を明示的に指定する必要があります。
• bundleIdentifier: BundleIdentifierOptions — バンドルキーの解決方法をカスタマイズし、同じエイリアスを複数のバンドルで使用できるようにします。
• loadOptions: Partial<LoadOptions> — 以降のすべての Assets.load 呼び出しに対して、デフォルトの strategy、retryCount、retryDelay、コールバックを設定します。
• preferences: Partial<AssetsPreferences> — crossOrigin、preferWorkers、preferCreateImageBitmap、parseAsGraphicsContext を設定します。

初期化後も、設定を調整できます。

Assets.setPreferences({
  crossOrigin: "anonymous",
  preferCreateImageBitmap: false,
});

for (const detection of Assets.detections) {
  console.log(detection.extension);
}

Assets.reset();

• Assets.setPreferences(preferences) — 対応するすべてのパーサーに新しい設定を適用します。
• Assets.detections — 登録済みの FormatDetectionParser のリストを返すゲッターです。現在の環境で利用可能なフォーマットを確認するときに使用します。
• Assets.reset() — 内部状態を完全にリセットします（リゾルバー、ローダー、キャッシュ）。テスト用で、新たに Assets.init を実行できます。

よくある間違い

[CRITICAL] Texture.from(url) を使って読み込む

誤り：

const texture = Texture.from("https://example.com/image.png");

正しい例：

const texture = await Assets.load("https://example.com/image.png");

v8 では、Texture.from() はキャッシュを読み取るだけです。URL からの取得は行いません。まず Assets.load() を使用してください。戻り値はテクスチャそのものです。

[HIGH] 位置引数を使った Assets.add のシグネチャを使う

誤り：

Assets.add("bunny", "bunny.png");

正しい例：

Assets.add({ alias: "bunny", src: "bunny.png" });

位置引数形式の Assets.add(key, url) は v8 で削除されました。alias と src プロパティを持つオプションオブジェクトを使用してください。

[HIGH] レベル間でテクスチャをアンロードしない

Assets.load() はテクスチャを無期限にキャッシュします。レベル制のゲームや、個別のアセットセットを持つ画面では、遷移時に Assets.unloadBundle() を呼び出して GPU メモリを解放してください。

API リファレンス

• Assets
• Loader
• Resolver
• Cache
• LoadOptions
• AssetInitOptions
• AssetsManifest
• AssetsBundle
• BackgroundLoader
• Spritesheet