pixijs-scene-sprite

PixiJS propose trois classes de sprite pour différentes tâches de dessin. Sprite est la feuille de dessin d'image par défaut ; NineSliceSprite est une variante de panneau UI redimensionnable qui préserve les coins ; TilingSprite répète une texture sur une zone. La sous-classe AnimatedSprite de Sprite parcourt les images de texture pour une animation image par image.

Suppose une familiarité avec pixijs-scene-core-concepts. Toutes les classes de sprite sont des nœuds feuilles ; elles ne peuvent pas avoir d'enfants. Enveloppez plusieurs sprites dans un Container pour les grouper.

Quick Start

const texture = await Assets.load("bunny.png");

const sprite = new Sprite({
  texture,
  anchor: 0.5,
  tint: 0xff8888,
});
sprite.x = app.screen.width / 2;
sprite.y = app.screen.height / 2;

app.stage.addChild(sprite);

La position est définie après la construction car app.screen.width / 2 dépend de la taille du rendu en direct. Les positions littérales peuvent être mises directement dans l'objet options via x/y (hérités de Container).

Skills associées : pixijs-scene-core-concepts (feuilles, transforms), pixijs-assets (chargement de texture), pixijs-scene-particle-container (milliers de sprites), pixijs-performance (spritesheets, batching).

Variantes

AnimatedSprite est une sous-classe de Sprite ; toutes les propriétés de Sprite (anchor, tint, position) s'appliquent.

Les options du constructeur de chaque variante sont documentées dans son fichier de sous-référence (references/{variant}.md). Toutes les variantes acceptent également les options Container (position, scale, tint, label, filters, zIndex, etc.) — voir skills/pixijs-scene-core-concepts/references/constructor-options.md.

Quand utiliser quoi

• « Je veux dessiner une seule image à une position » → Sprite. Le choix par défaut pour 90 % du contenu des jeux 2D et des applications.
• « Je veux animer un personnage à travers une série d'images » → AnimatedSprite. Chargez un spritesheet via Assets et passez sheet.animations['walk']. Voir references/animated-sprite.md.
• « Je veux un bouton/panneau UI qui se redimensionne sans étirer les bordures » → NineSliceSprite. Définissez les largeurs de bordure, puis définissez width/height. Voir references/nineslice-sprite.md.
• « Je veux un arrière-plan répétant qui défile » → TilingSprite. Animez tilePosition pour scroller. Voir references/tiling-sprite.md.
• « Je veux des milliers de sprites identiques » → Utilisez ParticleContainer avec des instances Particle (voir pixijs-scene-particle-container), pas des sprites simples.
• « Je veux dessiner des formes ou des chemins » → Utilisez Graphics (voir pixijs-scene-graphics), pas un sprite.

Concepts rapides

Anchor vs pivot

Sprite.anchor est normalisé [0, 1] et décale uniquement l'origine du dessin de texture ; pas de décalage de position. Container.pivot est en espace pixels et décale à la fois l'origine de la transformation et la position visuelle. Pour centrer un sprite, utilisez toujours anchor.set(0.5).

Charger avant de créer

Sprite.from(id) ne lit que le cache Assets ; il ne récupère pas. Faites toujours await Assets.load(...) en premier, ou passez directement la Texture retournée à new Sprite(texture).

Textures dynamiques

Une fois qu'une texture est chargée, modifier son frame ou échanger sa source ne notifie pas automatiquement les sprites. Définissez texture.dynamic = true une fois, ou appelez sprite['onViewUpdate']() manuellement après les modifications.

Erreurs courantes

[ÉLEVÉE] Utiliser Texture.from(url) pour charger

Faux :

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

Correct :

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

Texture.from() ne lit que le cache en v8. Utilisez Assets.load() en premier ; sa valeur de retour est la texture.

[ÉLEVÉE] Confondre anchor et pivot

Faux :

sprite.pivot.set(sprite.width / 2, sprite.height / 2);

Correct :

sprite.anchor.set(0.5);

anchor décale uniquement l'origine du dessin. pivot décale l'origine de la transformation ET la position visuelle, causant un déplacement inattendu du sprite.

[ÉLEVÉE] Ancien nom NineSlicePlane

NineSlicePlane a été renommé en NineSliceSprite en v8 et a changé vers un constructeur d'objet options : new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight }).

[MOYEN] Ajouter des enfants à un sprite

Sprite, NineSliceSprite et TilingSprite définissent tous allowChildren = false. Enveloppez dans un Container pour grouper les sprites avec d'autre contenu.

Référence API

• Sprite
• SpriteOptions
• AnimatedSprite
• NineSliceSprite
• TilingSprite
• Texture