PixiJS ParticleContainer Sprite Limitations

The ParticleContainer in PixiJS is a highly optimized WebGL-only container designed to render thousands of sprites at ultra-high performance. However, to achieve this speed, PixiJS bypasses many standard rendering pipelines, resulting in strict feature limitations. This article outlines the specific restrictions, disabled properties, and architectural limitations you will encounter when placing sprites inside a ParticleContainer.

1. Flat Hierarchy Only (No Nesting)

Unlike a standard Container, a ParticleContainer cannot have a complex nested tree structure. * Direct Children Only: You can only add sprites as direct children of the ParticleContainer. * No Nested Containers: You cannot place other Container, Sprite, or Graphics objects inside the child sprites of a ParticleContainer. The hierarchy must remain strictly flat.

2. Limited Sprite Properties (Disabled by Default)

To maximize rendering speed, ParticleContainer disables several standard sprite properties by default. If you want to modify these properties, you must explicitly enable them in the ParticleContainer constructor options. Enabling these properties comes at a performance cost:

const container = new PIXI.ParticleContainer(maxSize, {
    vertices: false, // Set to true to allow scale and rotation
    position: true,  // Set to true to allow x and y positioning
    rotation: false, // Set to true to allow sprite rotation
    uvs: false,      // Set to true to allow texture shifting/animations
    tint: false      // Set to true to allow tint and alpha changes
});

• Scale and Rotation (vertices & rotation): By default, you cannot scale or rotate sprites. You must enable vertices and rotation to alter these properties.
• Texture Swapping (uvs): By default, all sprites must share the same static texture. If you need to change textures dynamically or use animated spritesheets, you must enable uvs.
• Alpha and Tinting (tint): By default, individual sprite alpha levels and color tints are ignored. Enabling tint allows you to adjust the transparency and color of individual sprites.

3. Single Base Texture Restriction

For optimal performance, all sprites inside a ParticleContainer should share the same BaseTexture. * While you can use different frames from the same spritesheet (provided uvs is set to true), using textures from entirely different image files will force PixiJS to perform multiple draw calls, negating the performance benefits of the container.

4. No Advanced WebGL Features

Several advanced PixiJS features are completely unsupported for individual sprites inside a ParticleContainer: * No Filters: You cannot apply WebGL filters (like blur, glow, or displacement maps) to individual sprites within the container. * No Masks: Masking (both coordinate-based and alpha masking) is not supported for individual child sprites. * No Blend Modes: You cannot set unique blend modes (like ADD, MULTIPLY, or SCREEN) on individual sprites. All sprites within the container must share the same blend mode assigned to the parent container.

5. No Interactive Events

Sprites inside a ParticleContainer do not support interactive events. * You cannot attach pointer events such as pointerdown, pointerover, or click to individual sprites. If your application requires users to click or touch individual particles, you must handle the collision detection and coordinate mapping manually in your JavaScript code, or use a standard Container.