Pixijs Scene Core Concepts

This skill is the shared mental model referenced by all pixijs-scene-* leaves. It explains what the scene graph is in PixiJS v8, how a Container differs from a leaf, and where each concept lives. It does not go deep on any single API; it frames the pieces and points to the skill or reference file that does.

Quick Start

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

Related skills: pixijs-scene-container (Container API in detail), the leaf skills (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 (hit testing traverses the scene graph), pixijs-performance (cache, culling, render groups), pixijs-math (Matrix, toGlobal/toLocal detail).

Core Concepts

What the scene graph is

The PixiJS scene graph is a tree of display objects rooted at app.stage. Each node has a parent, a transform (position, scale, rotation, pivot, skew) relative to its parent, and optional visual state (alpha, tint, blendMode, visibility). Each frame the renderer walks the tree, composes transforms and visual state down to world-space, culls what's offscreen, and emits draw calls. The scene graph is both the layout model and the render order: earlier siblings draw behind later siblings.

Every display object in v8 is a Container subclass. DisplayObject from earlier versions was removed.

Container vs leaf (CRITICAL)

There are two roles in the tree:

• Containers: nodes that hold children. Use a Container (or RenderLayer) for any node that groups, positions, or transforms other nodes.
• Leaves: nodes that draw something and have no children. Use Sprite, Graphics, Text, Mesh, ParticleContainer's Particle, DOMContainer, or GifSprite as leaves.

In PixiJS v8, leaves must not have children. Adding children to a Sprite / Graphics / Text / Mesh logs a deprecation warning and is scheduled to become a hard error. The rule is: use Container for any node that needs children; do not nest children inside leaf scene objects. If you need to group a leaf with other leaves, wrap them in a Container.

This distinction is why the pixijs-scene-* skills are split the way they are: pixijs-scene-container covers the grouping node, and each leaf gets its own skill focused on its draw behavior.

Transforms and coordinate spaces

Every container composes a localTransform (a Matrix) from its position, scale, rotation, pivot, and skew. The renderer multiplies parents' local transforms together to produce the worldTransform (and groupTransform if a render group is in the chain), which maps local points to scene-root space. Use toGlobal(point) and toLocal(point, from?) to convert between spaces, and getGlobalPosition() for this object's world position. Full Matrix detail lives in pixijs-math; transform setters and toLocal/toGlobal live in pixijs-scene-container.

Render order and explicit z-ordering

Children render in array order: index 0 first, last index last. For explicit z-ordering on a single container, set sortableChildren = true and assign zIndex values to children. For render order that is decoupled from the logical hierarchy (e.g., a character's parent is a game world but its drawing happens on a UI layer), use RenderLayer. Deep detail, including when to prefer sortable children vs RenderLayer, is in references/scene-management.md.

Render groups

Flagging a container with isRenderGroup: true (or calling container.enableRenderGroup()) tells PixiJS to apply its transform on the GPU as a single matrix instead of recomputing every descendant's world transform on the CPU each frame. Use render groups on large, stable sub-trees such as worlds, UI layers, or parallax strips. Deep detail in references/scene-management.md.

Culling

cullable = true + a cullArea: Rectangle tells the CullerPlugin (or any culling pass) to skip rendering objects that fall outside the visible area. cullableChildren = false short-circuits recursive culling for a sub-tree whose children are always on screen. Culling is a performance topic; pixijs-performance and references/scene-management.md cover the trade-offs.

Masking

Set container.mask to another display object to clip its rendering. PixiJS picks the mask type automatically: a Graphics or Container mask uses a stencil buffer, a Sprite mask uses an alpha filter, and a number selects a ColorMask. All four mask types (AlphaMask, StencilMask, ScissorMask, ColorMask) are covered in references/masking.md.

Visibility, alpha, tint, and blend mode

visible = false skips rendering and transform updates; renderable = false skips rendering but still updates transforms (use when hit-testing or bounds queries need to stay live). alpha and tint multiply down through the sub-tree; blendMode controls how this container's draw instructions composite against what is already on the target. See pixijs-blend-modes for the full blend-mode list and pixijs-scene-container for per-node state.

Destroy semantics

container.destroy() unlinks one node. container.destroy({ children: true }) recursively destroys the whole sub-tree; always use this for killing a branch. texture: true and textureSource: true additionally tear down GPU resources owned by leaves. If cacheAsTexture is on, disable it before destroying. pixijs-scene-container documents the full signature.

Lifecycle events

Containers emit events for hierarchy and visibility changes: childAdded / childRemoved on the parent, added / removed on the child, plus visibleChanged and destroyed on the container itself. Useful for wiring reactive UI updates or resource bookkeeping. Full details in references/container-hierarchy.md.