pixijs-scene-core-concepts

Cette compétence est le modèle mental partagé référencé par toutes les feuilles pixijs-scene-*. Elle explique ce qu'est le graphe de scène dans PixiJS v8, comment un Container diffère d'une feuille, et où chaque concept se situe. Elle ne fait pas de plongée profonde dans une seule API ; elle cadre les pièces et pointe vers la compétence ou le fichier de référence qui le fait.

Démarrage rapide

const world = new Container({ isRenderGroup: true });
app.stage.addChild(world);

const hero = new Container({ label: "hero" });
hero.addChild(new Sprite(bodyTexture));
hero.addChild(new Sprite(faceTexture));
world.addChild(hero);

const mask = new Graphics().rect(0, 0, 800, 600).fill(0xffffff);
world.mask = mask;
world.addChild(mask);

hero.position.set(world.width / 2, world.height / 2);

Compétences associées : pixijs-scene-container (API Container en détail), les compétences feuilles (pixijs-scene-sprite, pixijs-scene-graphics, pixijs-scene-text, pixijs-scene-mesh, pixijs-scene-particle-container, pixijs-scene-dom-container, pixijs-scene-gif), pixijs-events (le hit testing parcourt le graphe de scène), pixijs-performance (cache, culling, render groups), pixijs-math (Matrix, détail toGlobal/toLocal).

Concepts fondamentaux

Qu'est-ce que le graphe de scène

Le graphe de scène PixiJS est un arbre d'objets d'affichage enraciné à app.stage. Chaque nœud a un parent, une transformation (position, échelle, rotation, pivot, skew) relative à son parent, et un état visuel optionnel (alpha, tint, blendMode, visibility). Chaque frame, le renderer parcourt l'arbre, compose les transformations et l'état visuel jusqu'à l'espace monde, élimine ce qui est hors écran, et émet des appels de dessin. Le graphe de scène est à la fois le modèle de mise en page et l'ordre de rendu : les frères antérieurs se dessinent derrière les frères postérieurs.

Chaque objet d'affichage en v8 est une sous-classe de Container. DisplayObject des versions antérieures a été supprimé.

Container vs feuille (CRITIQUE)

Il y a deux rôles dans l'arbre :

• Containers : nœuds qui contiennent des enfants. Utilisez un Container (ou RenderLayer) pour tout nœud qui groupe, positionne ou transforme d'autres nœuds.
• Feuilles : nœuds qui dessinent quelque chose et n'ont pas d'enfants. Utilisez Sprite, Graphics, Text, Mesh, Particle de ParticleContainer, DOMContainer, ou GifSprite comme feuilles.

Dans PixiJS v8, les feuilles ne doivent pas avoir d'enfants. L'ajout d'enfants à un Sprite / Graphics / Text / Mesh enregistre un avertissement de dépréciation et est prévu pour devenir une erreur hard. La règle est : utilisez Container pour tout nœud qui a besoin d'enfants ; ne nidifiez pas d'enfants dans les objets de scène feuille. Si vous avez besoin de grouper une feuille avec d'autres feuilles, enveloppez-les dans un Container.

Cette distinction est pourquoi les compétences pixijs-scene-* sont divisées de cette façon : pixijs-scene-container couvre le nœud de groupage, et chaque feuille a sa propre compétence axée sur son comportement de dessin.

Transformations et espaces de coordonnées

Chaque container compose une localTransform (une Matrix) à partir de sa position, scale, rotation, pivot, et skew. Le renderer multiplie ensemble les transformations locales des parents pour produire la worldTransform (et groupTransform si un render group est dans la chaîne), qui mappe les points locaux à l'espace racine de scène. Utilisez toGlobal(point) et toLocal(point, from?) pour convertir entre les espaces, et getGlobalPosition() pour la position monde de cet objet. Le détail complet de Matrix se trouve dans pixijs-math ; les setters de transformation et toLocal/toGlobal se trouvent dans pixijs-scene-container.

Ordre de rendu et z-ordering explicite

Les enfants se rendent dans l'ordre du tableau : l'index 0 en premier, le dernier index en dernier. Pour un z-ordering explicite sur un seul container, mettez sortableChildren = true et assignez des valeurs zIndex aux enfants. Pour un ordre de rendu découplé de la hiérarchie logique (par exemple, le parent d'un personnage est un monde de jeu mais son dessin se fait sur une couche UI), utilisez RenderLayer. Le détail profond, y compris quand préférer les enfants sortables vs RenderLayer, se trouve dans references/scene-management.md.

Render groups

Marquer un container avec isRenderGroup: true (ou appeler container.enableRenderGroup()) indique à PixiJS d'appliquer sa transformation sur le GPU comme une seule matrice au lieu de recalculer la transformation mondiale de chaque descendant sur le CPU chaque frame. Utilisez render groups sur les grands sous-arbres stables tels que les mondes, les couches UI, ou les bandes parallax. Détail profond dans references/scene-management.md.

Culling

cullable = true + une cullArea: Rectangle indique au CullerPlugin (ou à toute passe de culling) de sauter le rendu des objets qui se situent en dehors de la zone visible. cullableChildren = false court-circuite le culling récursif pour un sous-arbre dont les enfants sont toujours à l'écran. Le culling est un sujet de performance ; pixijs-performance et references/scene-management.md couvrent les compromis.

Masquage

Mettez container.mask à un autre objet d'affichage pour écrêter son rendu. PixiJS choisit automatiquement le type de mask : un mask Graphics ou Container utilise un stencil buffer, un mask Sprite utilise un alpha filter, et un nombre sélectionne un ColorMask. Les quatre types de mask (AlphaMask, StencilMask, ScissorMask, ColorMask) sont couverts dans references/masking.md.

Visibilité, alpha, tint et blend mode

visible = false saute le rendu et les mises à jour de transformation ; renderable = false saute le rendu mais met toujours à jour les transformations (à utiliser quand le hit-testing ou les requêtes de bounds doivent rester actifs). alpha et tint se multiplient vers le bas dans le sous-arbre ; blendMode contrôle la façon dont les instructions de dessin de ce container se composent contre ce qui est déjà sur la cible. Voir pixijs-blend-modes pour la liste complète des blend-modes et pixijs-scene-container pour l'état par nœud.

Sémantique de destruction

container.destroy() délie un nœud. container.destroy({ children: true }) détruit récursivement tout le sous-arbre ; utilisez toujours ceci pour tuer une branche. texture: true et textureSource: true déchirent en plus les ressources GPU détenues par les feuilles. Si cacheAsTexture est activé, désactivez-le avant de détruire. pixijs-scene-container documente la signature complète.

Événements de cycle de vie

Les Containers émettent des événements pour les changements de hiérarchie et de visibilité : childAdded / childRemoved sur le parent, added / removed sur l'enfant, plus visibleChanged et destroyed sur le container lui-même. Utile pour connecter les mises à jour réactives de l'UI ou la comptabilité des ressources. Détails complets dans references/container-hierarchy.md.

Comparaison des feuilles : quelle compétence couvre quel objet

Container lui-même est couvert dans pixijs-scene-container et est le nœud dans lequel chaque feuille vit.

Quand utiliser quoi (décisions rapides)

• « Je veux grouper et transformer certains objets d'affichage » → Container, voir pixijs-scene-container.
• « Je veux dessiner une texture » → Sprite, voir pixijs-scene-sprite.
• « Je veux dessiner des formes ou chemins vectoriels » → Graphics, voir pixijs-scene-graphics.
• « Je veux dessiner du texte » → Text / BitmapText / HTMLText, voir pixijs-scene-text.
• « Je veux des milliers de sprites bon marché » → ParticleContainer, voir pixijs-scene-particle-container.
• « Je veux un mesh à géométrie personnalisée ou un sprite déformé » → Mesh ou l'une de ses variantes, voir pixijs-scene-mesh.
• « Je veux découper un sous-arbre » → définir .mask, voir references/masking.md.
• « Je veux un ordre de rendu découplé » → RenderLayer, voir references/scene-management.md.
• « Je veux des transformations au niveau GPU pour un grand sous-arbre stable » → isRenderGroup: true, voir references/scene-management.md.
• « Je veux ignorer le rendu hors écran » → cullable = true + CullerPlugin, voir pixijs-performance.

Références

• references/constructor-options.md : les ~30 champs hérités par chaque nœud dérivé de Container (transformation, affichage, hiérarchie, tri, mise en page, effets, callbacks), avec valeurs par défaut, types, et quand l'assignation ligne par ligne est appropriée. Référence partagée pour toutes les compétences feuille.
• references/container-hierarchy.md : ajouter/retirer/permuter les enfants, reparenting avec préservation de transformation, navigation par label, destruction de sous-arbres.
• references/transforms.md : position, scale, rotation, pivot, origin, skew, toGlobal/toLocal, les trois matrices (local/group/world), bounds.
• references/masking.md : AlphaMask, StencilMask, ScissorMask, ColorMask, masquage inverse, comparaison des coûts.
• references/layers.md : RenderLayer, attach/detach, couches triées, split couche + parent logique.
• references/render-groups.md : isRenderGroup, transformations au niveau GPU, quand utiliser, render-groups vs cacheAsTexture.
• references/scene-management.md : vue combinée ; render groups, RenderLayer, culling, tri zIndex, boundsArea.

Erreurs courantes

[CRITIQUE] Ajouter des enfants à un objet d'affichage feuille

Faux :

const sprite = new Sprite(texture);
sprite.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));

Correct :

const group = new Container();
group.addChild(new Sprite(texture));
group.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));

En v8, les feuilles (Sprite, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite) s'étendent techniquement à Container mais ne devraient pas contenir d'enfants. L'ajout d'enfants à une feuille produit un comportement de rendu indéfini. Enveloppez la feuille dans un Container quand vous avez besoin de groupage.

[CRITIQUE] Référencer DisplayObject

Faux :

import { DisplayObject } from "pixi.js"; // pas d'export en v8
function moveNode(node: DisplayObject) {
  node.x += 1;
}

Correct :

import { Container } from "pixi.js";
function moveNode(node: Container) {
  node.x += 1;
}

DisplayObject a été supprimé en v8. Chaque objet d'affichage — y compris Sprite, Graphics, Text, Mesh — est maintenant une sous-classe de Container. Utilisez Container comme type de base.

[ÉLEVÉ] Oublier isRenderGroup sur les grands sous-arbres statiques

Faux :

const world = new Container();
for (let i = 0; i < 5000; i++) {
  world.addChild(new Sprite(texture));
}
app.stage.addChild(world);

Correct :

const world = new Container({ isRenderGroup: true });
for (let i = 0; i < 5000; i++) {
  world.addChild(new Sprite(texture));
}
app.stage.addChild(world);

Sans isRenderGroup: true, le renderer recompose la transformation de chaque enfant par rapport à ses parents à chaque frame. Marquer le sous-arbre comme un render group met en cache les transformations et l'état du dessin jusqu'à ce qu'un enfant change, ce qui est essentiel pour les grands arbres ou la plupart statiques.

[ÉLEVÉ] Traiter child.x comme espace monde

Faux :

const enemy = new Container();
enemy.x = 500;
world.addChild(enemy);
world.x = 200;
console.log(enemy.x); // 500 (local), pas 700 (world)

Correct :

const worldPos = enemy.toGlobal({ x: 0, y: 0 });
console.log(worldPos.x); // 700

Container.x/y/scale/rotation sont LOCAL par rapport au parent. Utilisez toGlobal(point) pour calculer les coordonnées de l'espace monde, ou getGlobalPosition() pour l'origine du container dans l'espace monde. La transformation mondiale n'est pas exposée comme une simple paire x/y.

[MOYEN] sortableChildren sans zIndex

Faux :

const layer = new Container();
layer.sortableChildren = true;
layer.addChild(bg); // pas de zIndex
layer.addChild(mid); // pas de zIndex
layer.addChild(fg); // pas de zIndex
// l'ordre est inchangé — tous les zIndex sont par défaut 0

Correct :

const layer = new Container();
layer.sortableChildren = true;
bg.zIndex = 0;
mid.zIndex = 10;
fg.zIndex = 20;
layer.addChild(bg, mid, fg);

sortableChildren retrie les enfants par zIndex avant le rendu, mais ne prend effet que quand les enfants ont réellement des valeurs zIndex distinctes. Définir uniquement l'indicateur parent n'a aucun effet visible.

Outillage

L'extension Chrome PixiJS Devtools vous permet d'inspecter et de manipuler un graphe de scène en cours d'exécution en temps réel. Installez-la pour tout debugging de mise en page ou d'ordre de rendu non trivial.

Référence API

• Container
• ViewContainer
• RenderLayer
• RenderGroup
• Bounds
• Culler
• CullerPlugin