pixijs-scene-gif

GifSprite affiche un GIF animé comme objet d'affichage. Assets.load('animation.gif') retourne une GifSource (pas une Texture), et vous l'enrobez dans un GifSprite. Nécessite un import avec effet secondaire import 'pixi.js/gif' pour enregistrer l'extension du chargeur.

Suppose une familiarité avec pixijs-scene-core-concepts. GifSprite étend Sprite, c'est donc une feuille : ne nidifiez pas d'enfants à l'intérieur. Enrobez plusieurs instances de GifSprite dans un Container pour les grouper.

Démarrage rapide

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] Les GIF décodent chaque frame en une texture canvas distincte. Pour les animations critiques en performance avec de nombreuses frames, préférez une spritesheet avec AnimatedSprite — elle utilise une texture atlas unique et s'agence mieux sur le GPU.

Compétences connexes : pixijs-scene-core-concepts (bases du graphe de scène), pixijs-scene-sprite (AnimatedSprite pour l'animation basée sur spritesheet), pixijs-assets (Assets.load, mise en cache, déchargement), pixijs-ticker (synchronisation d'images), pixijs-performance (mémoire de texture).

Options du constructeur

GifSpriteOptions étend Omit<SpriteOptions, 'texture'>; texture est gérée en interne (définie à partir de source.textures[0] et échangée par frame). Toutes les autres options de Sprite (anchor, scale, tint, roundPixels, etc.) sont valides, et toutes les options de Container (position, scale, tint, label, filters, zIndex, etc.) le sont aussi ici — voir skills/pixijs-scene-core-concepts/references/constructor-options.md.

Options spécifiques aux feuilles ajoutées par GifSpriteOptions :

Le constructeur accepte aussi une GifSource nue comme argument unique (new GifSprite(source)), ce qui est un raccourci pour new GifSprite({ source }) avec les valeurs par défaut ci-dessus.

Motifs essentiels

Configuration et import avec effet secondaire

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 appelle extensions.add(GifAsset), enregistrant .gif avec le chargeur d'assets. Sans cela, Assets.load ne reconnaît pas les fichiers GIF. GifSprite et GifSource sont exportés depuis pixi.js/gif, pas pixi.js.

Importer un export nommé depuis pixi.js/gif déclenche aussi l'effet secondaire, donc un simple import 'pixi.js/gif' n'est nécessaire que quand vous n'importez rien de ce chemin.

Contrôle de la lecture

const gif = new GifSprite({ source });

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

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

gif.playing; // lecture seule
gif.progress; // position de lecture 0-1
gif.totalFrames; // nombre de frames
gif.duration; // durée totale en ms

autoPlay: true (par défaut) démarre la lecture immédiatement; loop: true (par défaut) se répète. animationSpeed est un multiplicateur sur la synchronisation d'image native du GIF. currentFrame est basé sur zéro.

Options de chargement

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...");

Les options dans data sont passées à GifSource.from. fps définit le délai de frame de secours pour les GIF qui ne spécifient pas la synchronisation. scaleMode et resolution contrôlent les textures canvas créées pour chaque frame. Le chargeur correspond aux extensions de fichier .gif et aux URIs data:image/gif.

Callbacks

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 se déclenche quand une animation sans boucle atteint la dernière frame.
• onLoop se déclenche chaque fois qu'une animation avec boucle se réenroule.
• onFrameChange se déclenche chaque fois que la frame affichée change.

Mode de mise à jour manuel

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

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

autoUpdate: false déconnecte de Ticker.shared. Vous appelez gif.update(ticker) vous-même, en passant n'importe quelle instance de Ticker. Utile quand l'animation doit être pilotée par un ticker privé (p. ex., un ticker de jeu conscient des pauses).

Partage des données source et clonage

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 peut être partagé entre plusieurs instances de GifSprite; chaque sprite a un état de lecture indépendant. clone() copie tous les paramètres de lecture mais crée une instance indépendante.

Erreurs courantes

[HAUTE] Ne pas importer pixi.js/gif

Incorrect :

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

Correct :

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

L'extension du chargeur GIF doit être enregistrée avant de charger. Sans l'import avec effet secondaire, le chargeur ne reconnaît pas les fichiers .gif et le chargement échoue ou retourne des données brutes.

[MOYEN] S'attendre à ce que Assets.load retourne une Texture

Incorrect :

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

Correct :

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

Assets.load sur un GIF retourne une GifSource contenant les textures de frame et les données de synchronisation. Passez la source à GifSprite; pour une seule frame statique, lisez source.textures[0].

[MOYEN] Mémoire GIF non libérée à la destruction

Incorrect :

gif.destroy();
// GifSource et les textures de frame restent en mémoire

Correct :

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

Les frames GIF contiennent des données de pixels décodées comme des textures canvas individuelles. gif.destroy() (ou destroy(false)) détruit le sprite mais garde la GifSource intacte. Passez true pour aussi détruire la source. Pour les sources partagées, ne détruisez que quand le dernier consommateur est fini, ou appelez Assets.unload pour laisser le cache d'assets le gérer.

[BASSE] Ne nidifiez pas d'enfants à l'intérieur d'un GifSprite

GifSprite étend Sprite, qui définit allowChildren = false. C'est une feuille. Pour grouper un GIF avec d'autres objets d'affichage, enrobez-les tous dans un simple Container :

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

Référence API

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