pixijs-assets

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

クイックスタート

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、またはマニフェストを設定する場合は推奨されます。初期化後、Assets.load() を URL、エイリアス、配列、または UnresolvedAsset で呼び出すと、読み込まれたアセットはキャッシュされ、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 形式)	spritesheet	spritesheetAsset (references/spritesheet.md を参照)
ビットマップフォント	.fnt, .xml	bitmap-font	loadBitmapFont (読み込みはデフォルトで機能します。BitmapText のレンダリングには 'pixi.js/text-bitmap' が必要です。references/fonts.md を参照)
ウェブフォント	.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 タイプを照合してローダーを選択します。CDN 署名付き URL、Blob URL、API エンドポイント、コンテンツハッシュパスなど、URL に拡張子がない場合、リゾルバーはローダーに何をするべきかを伝えられません。アセット記述子のトップレベル parser フィールドを設定して、特定のローダーを強制します:

// 拡張子のない署名付き CDN URL
const texture = await Assets.load({
  src: "https://cdn.example.com/signed/abc123?token=xyz",
  parser: "texture",
});

// JSON を返す API エンドポイント
const data = await Assets.load({
  alias: "config",
  src: "https://api.example.com/v1/config",
  parser: "json",
});

// 明示的なファミリーを持つ拡張子なしのフォント URL
await Assets.load({
  src: "https://cdn.example.com/fonts/hero-v2",
  parser: "web-font",
  data: { family: "Hero", weights: ["400", "700"] },
});

// ファイル拡張子のないビデオストリーム
const clipTexture = await Assets.load({
  src: "https://cdn.example.com/stream/xyz",
  parser: "video",
  data: { mime: "video/mp4", muted: true, playsinline: true },
});

parser フィールドはアセット記述子のトップレベル (src と data の並び)に配置され、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 を使用してください。

// 古い (非推奨)
await Assets.load({ src: "...", loadParser: "loadTextures" });

// 新しい
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	references/svg.md	parseAsGraphicsContext、テクスチャモード
Retina + フォーマット検出	references/resolution.md	@{1,2}x、format 設定

判断ガイド

• 単一の画像を読み込むだけ? 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 は未定義です。
• 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
ウェブフォント	LoadFontData	family, weights, style, display, unicodeRange, featureSettings	references/fonts.md
ビットマップフォント	(なし; 自動設定)	Distance-field 検出はスケールモードとミップマップを設定します	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 / テキスト	(なし)	そのまま返されます	—

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 リストを公開する getter。現在の環境がアドバタイズするフォーマットを検査するときに使用します。
• Assets.reset() — 内部フル リセット (リゾルバー + ローダー + キャッシュ)。テストの対象なので、新しい Assets.init が実行できます。

よくある間違い

[重大] 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() を使用します。戻り値はテクスチャ自体です。

[高] 位置付き Assets.add シグネチャを使用する

間違い:

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

正しい:

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

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

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

Assets.load() はテクスチャを無制限にキャッシュします。レベルベースのゲームやアセットセットが異なる画面の場合、トランジション時に Assets.unloadBundle() を呼び出して GPU メモリを解放します。

API リファレンス

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