pixijs-assets

L'API Assets est le chargeur, le résolveur et le cache d'assets de PixiJS en un seul singleton. Utilisez-la pour charger des textures, vidéos, spritesheets, polices, JSON et autres ressources avec détection de format, commutation de résolution, groupement de bundles, suivi de progression et nettoyage GPU.

Démarrage rapide

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() est optionnel mais recommandé pour définir basePath, texturePreference ou un manifest. Après l'init, appelez Assets.load() avec une URL, un alias, un tableau ou un UnresolvedAsset ; les assets résolus sont mis en cache et re-résolus par Assets.get().

Types de fichiers supportés

La colonne Parser ID est la valeur que vous passez au champ parser de niveau supérieur sur un descripteur d'asset pour forcer un chargeur spécifique. Voir « Forcer un parser » ci-dessous.

Forcer un parser avec parser

Par défaut, PixiJS choisit un chargeur en correspondant l'extension de fichier ou le type MIME. Quand votre URL n'a pas d'extension (URLs CDN signées, blob URLs, endpoints API, chemins avec hash de contenu), le résolveur ne peut pas dire au chargeur quoi faire. Définissez le champ parser de niveau supérieur sur le descripteur d'asset pour forcer un chargeur spécifique :

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

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

// URL de police sans extension avec famille explicite
await Assets.load({
  src: "https://cdn.example.com/fonts/hero-v2",
  parser: "web-font",
  data: { family: "Hero", weights: ["400", "700"] },
});

// Flux vidéo sans extension de fichier
const clipTexture = await Assets.load({
  src: "https://cdn.example.com/stream/xyz",
  parser: "video",
  data: { mime: "video/mp4", muted: true, playsinline: true },
});

Le champ parser va au niveau supérieur du descripteur d'asset (aux côtés de src et data), pas à l'intérieur de data. Il prend n'importe quel Parser ID du tableau « Types de fichiers supportés » ci-dessus :

• 'texture', 'svg', 'video' : textures image, SVG et vidéo
• 'json', 'text' : JSON et texte brut
• 'web-font', 'bitmap-font' : polices web et bitmap
• 'spritesheet' : JSON d'atlas de textures
• 'gif' : GIFs animés (nécessite 'pixi.js/gif')
• 'basis', 'dds', 'ktx', 'ktx2' : textures compressées (chacun nécessite son import side-effect)

Quand vous en avez besoin

• URLs CDN signées : https://cdn.example.com/get?id=abc123 n'a pas d'extension que le chargeur peut tester.
• Blob ou ObjectURL : URL.createObjectURL(blob) produit des URLs blob:... sans extension.
• Routage personnalisé : /api/assets/hero-v2 où le serveur décide du type de contenu.
• Chemins avec hash de contenu sans suffixe : certains pipelines de build produisent des noms comme /static/abc123def au lieu de /static/abc123def.png.

Si l'URL a une extension, vous n'avez pas besoin de parser ; laissez la détection automatique faire son travail. Définissez parser uniquement quand la détection ne peut pas fonctionner.

loadParser est déprécié

Le champ loadParser de v7 fonctionne toujours mais émet un avertissement de dépréciation. Utilisez parser pour le nouveau code.

// Ancien (déprécié)
await Assets.load({ src: "...", loadParser: "loadTextures" });

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

Sujets

Chaque workflow d'asset est couvert dans un fichier de référence. Choisissez celui qui correspond à votre question :

Guide de décision

• Besoin de charger une seule image ? Utilisez Assets.load(url). Aucune configuration requise.
• Chargement de nombreux assets groupés par niveau/scène ? Utilisez un bundle. Voir references/bundles.md.
• Tous les assets connus au moment du build ? Utilisez un manifest dans Assets.init. Voir references/manifests.md.
• Besoin d'une barre de progression ? Passez un callback de progression à Assets.load. Voir references/progress.md.
• Transitions fluides entre les niveaux ? Préchargez le niveau suivant en arrière-plan. Voir references/background.md.
• Le budget mémoire compte ? Utilisez les textures compressées et Assets.unload entre les écrans. Voir references/compressed-textures.md et references/caching.md.
• Besoin d'icônes SVG nets à n'importe quelle taille ? Chargez en Graphics, pas en texture. Voir references/svg.md.
• Retina + WebP/AVIF ? Configurez texturePreference et utilisez des motifs de format. Voir references/resolution.md.

Options de chargement et gestion des erreurs

Il y a deux concepts distincts « d'options » lors du chargement d'assets :

1. LoadOptions : le deuxième argument de Assets.load/loadBundle. Contrôle la récupération d'erreurs, les tentatives, la progression et les callbacks d'achèvement sur tout un chargement.
2. data : un champ sur chaque descripteur d'asset. Transfère les options spécifiques du parser (mode d'échelle, résolution, famille de police, drapeaux autoplay, etc.) au chargeur spécifique de cet asset.

LoadOptions (par appel)

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] au fur et à mesure que les assets de l'appel se complètent.
• onError(error, url) : url est string | ResolvedAsset. Protégez avant de lire .src ; quand url est une chaîne, .src est undefined.
• strategy: 'throw' | 'skip' | 'retry' — par défaut 'throw'. 'skip' résout avec tous les assets réussis ; 'retry' rétente les assets échoués.
• retryCount — par défaut 3, tentatives par asset quand strategy est 'retry'.
• retryDelay — par défaut 250 ms entre les tentatives.

Les défauts globaux vivent sur Loader.defaultOptions, ou passez loadOptions à Assets.init().

Options data (par asset)

Chaque parser de chargeur lit ses propres options du champ data sur le descripteur d'asset. Utilisez le tableau ci-dessous pour choisir les bonnes options pour chaque type d'asset :

Exemple combinant LoadOptions et data :

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

À l'intérieur d'un manifest ou d'un bundle, chaque entrée peut porter ses propres 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 },
          },
        ],
      },
    ],
  },
});

Configuration à l'exécution

Assets.init(options) accepte, aux côtés de basePath et manifest :

• defaultSearchParams — string ou Record<string, any> ajouté à chaque URL résolue. Utile pour l'invalidation de cache.
• skipDetections: boolean — ignorer la détection de format du navigateur pour un init plus rapide. Nécessite un texturePreference.format explicite.
• bundleIdentifier: BundleIdentifierOptions — personnaliser comment les clés de bundle se résolvent afin que le même alias puisse vivre dans plusieurs bundles.
• loadOptions: Partial<LoadOptions> — définir le strategy, retryCount, retryDelay et les callbacks par défaut pour chaque appel Assets.load suivant.
• preferences: Partial<AssetsPreferences> — crossOrigin, preferWorkers, preferCreateImageBitmap, parseAsGraphicsContext.

Après l'init, les préférences peuvent toujours être ajustées :

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

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

Assets.reset();

• Assets.setPreferences(preferences) — pousser les nouvelles préférences vers chaque parser qui les supporte.
• Assets.detections — getter exposant la liste FormatDetectionParser enregistrée ; utilisez pour inspecter quels formats l'environnement actuel annonce.
• Assets.reset() — réinitialisation interne complète (résolveur + chargeur + cache). Destiné aux tests afin qu'un Assets.init frais puisse s'exécuter.

Erreurs courantes

[CRITIQUE] Utiliser Texture.from(url) pour charger

Incorrect :

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

Correct :

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

En v8, Texture.from() ne lit que le cache. Il ne récupère pas depuis une URL. Utilisez d'abord Assets.load() ; la valeur retournée est la texture elle-même.

[ÉLEVÉE] Utiliser la signature positionnelle Assets.add

Incorrect :

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

Correct :

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

La forme Assets.add(key, url) positionnelle a été supprimée en v8. Utilisez l'objet options avec les propriétés alias et src.

[ÉLEVÉE] Ne pas décharger les textures entre les niveaux

Assets.load() met les textures en cache indéfiniment. Pour les jeux basés sur les niveaux ou les écrans avec des ensembles d'assets distincts, appelez Assets.unloadBundle() lors de la transition pour libérer la mémoire GPU.

Référence API

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