PixiJS v8 Rendering skill for Codex

Done well means: textures load once through Assets and are packed into spritesheets, the scene graph is shallow and grouped by texture, thousands of identical objects go through ParticleContainer, off-screen content is culled, static content is cached, and anything removed from the stage is destroyed so GPU memory stays flat.

Before writing code

1. Read AGENTS.md and package.json (pixi.js version). v8 changed most constructors; do not mix v7 snippets into a v8 codebase.
2. Check the bundler (Vite is typical) and whether code imports from pixi.js (full) or tree-shaken subpaths.
3. Note the target: mobile browsers decide texture size limits and particle budgets.

Application setup

import { AnimatedSprite, Application, Assets, Container } from "pixi.js";

const app = new Application();
await app.init({
  resizeTo: window,
  background: "#101018",
  antialias: false,             // true costs fill rate; only for vector-heavy scenes
  resolution: Math.min(window.devicePixelRatio, 2),
  autoDensity: true,            // CSS size stays logical while the backbuffer is hi-dpi
  preference: "webgl",          // or "webgpu"; v8 falls back when unsupported
});
document.getElementById("stage")!.appendChild(app.canvas);

v7	v8
new Application({ ... })	new Application() then await app.init({ ... })
app.view	app.canvas
graphics.beginFill(c).drawRect(...).endFill()	graphics.rect(...).fill(c)
lineStyle(2, c)	.stroke({ width: 2, color: c })
new Text("hi", style)	new Text({ text: "hi", style })
cacheAsBitmap = true	container.cacheAsTexture(true)
BaseTexture	TextureSource (ImageSource, CanvasSource, …)
Texture.from(url) loads	Load with Assets.load(url) first; Texture.from only reads the cache
Ticker callback gets delta	Callback gets the Ticker; use ticker.deltaTime / ticker.deltaMS
Sprites can have children	Only Container can have children; wrap leaves
interactive = true	eventMode = "static" (default is "passive")

Assets

await Assets.init({ basePath: "assets" });
Assets.addBundle("level1", {
  hero: "hero.json",          // spritesheet JSON (TexturePacker); frames become textures
  tiles: "tiles.png",
  font: "ui-font.fnt",        // bitmap font
});
const level = await Assets.loadBundle("level1", (p) => (loadingBar.scale.x = p));
const idle = level.hero.animations["hero_idle"];

• Use spritesheets for anything with more than a handful of frames: one texture source means the batcher can draw many sprites in one call.
• Keep atlas pages at or below 2048x2048 for broad mobile support; 4096 only after checking app.renderer limits on target devices.
• Assets.unload("tiles.png") (or unloadBundle) releases GPU memory for level-scoped assets.

Scene graph

const world = new Container({ label: "world" });
const bg = new Container({ label: "bg" });
const actors = new Container({ label: "actors", sortableChildren: true });
world.addChild(bg, actors);
app.stage.addChild(world);

const hero = new AnimatedSprite(idle);
hero.anchor.set(0.5, 1);
hero.animationSpeed = 0.15;
hero.play();
actors.addChild(hero);

app.ticker.add((ticker) => {
  hero.x += 120 * (ticker.deltaMS / 1000);   // pixels per second, frame-rate independent
  hero.zIndex = hero.y;                       // y-sort only within the sortable layer
});

• Group by texture and blend mode. Interleaving sprites from different sheets, Graphics and Text breaks batches.
• sortableChildren sorts every frame something changes; enable it only on the layer that needs it.
• Use a camera Container (world) and move it, rather than moving every object.

Choosing a display object

Need	Use
Images, animated characters	Sprite, AnimatedSprite
1k-100k+ identical-texture particles	ParticleContainer with Particle objects
Dynamic vector shapes (debug, charts)	Graphics; share geometry with GraphicsContext
Many identical vector shapes	Draw once, app.renderer.generateTexture(graphics), then Sprites
Changing text every frame (score, timers)	BitmapText
Rarely changing, styled text	Text
Repeating background	TilingSprite
Static complex subtree	container.cacheAsTexture(true)

import { ParticleContainer, Particle, Rectangle } from "pixi.js";

const sparks = new ParticleContainer({
  dynamicProperties: { position: true, rotation: false, color: false },
  boundsArea: new Rectangle(0, 0, app.screen.width, app.screen.height),
});
for (let i = 0; i < 20000; i++) {
  sparks.addParticle(new Particle({ texture: sparkTex, x: Math.random() * 800, y: Math.random() * 600 }));
}
app.stage.addChild(sparks);

Particles live in particleChildren, not children; only the properties marked dynamic are re-uploaded each frame. Set boundsArea because the container does not compute bounds.

Culling and caching

import { Culler, Rectangle } from "pixi.js";

actors.cullableChildren = true;
for (const c of actors.children) c.cullable = true;
const view = new Rectangle(0, 0, app.screen.width, app.screen.height);
app.ticker.add(() => Culler.shared.cull(world, view));

Or register CullerPlugin with extensions.add(CullerPlugin) for automatic culling. Cache a subtree with cacheAsTexture(true) only when it rarely changes; call container.updateCacheTexture() after a change, and turn it off for animated content.

Cleanup

function removeEnemy(enemy: Container) {
  enemy.removeFromParent();
  enemy.destroy({ children: true });   // keep shared atlas textures alive
}

• destroy() removes listeners and GPU resources for the object. Pass texture-destroying options only for textures this object owns (a generateTexture or RenderTexture result), never for shared atlas frames.
• Remove ticker callbacks you added (app.ticker.remove(fn)) when a screen closes.
• Filters (BlurFilter, custom filters) render to intermediate textures; reuse filter instances and avoid filters on large containers that change every frame.

Gotchas

• Forgetting await app.init() leaves app.canvas undefined.
• Fractional positions blur pixel art: round the camera position, set TextureSource.defaultOptions.scaleMode = "nearest" before loading, or set scale mode per source.
• Text re-rasterises to a canvas texture on every content change; at 60 changes per second that is a CPU and upload cost. Use BitmapText.
• getBounds() returns a Bounds; use .rectangle when you need a Rectangle.
• WebGPU availability varies by browser; keep a WebGL path and test both if you set preference.
• Losing the WebGL context (mobile tab switching) drops GPU resources; Pixi restores managed textures, but custom raw GL calls need handling.

Verification

• Run the dev server and watch the browser performance panel: steady frame time at the target object count, no long tasks during play.
• Spawn and destroy 1000 objects in a loop for a minute; JS heap and GPU memory (Chrome Task Manager GPU column) should return to baseline.
• Count draw calls with a WebGL inspector extension (Spector.js) or the PixiJS DevTools extension when batches look broken.
• npm run build passes type checking.

Hand-off summary

**PixiJS:** 8.x, WebGL preference, resizeTo window, resolution capped at 2
**Assets:** level1 bundle (hero spritesheet, tiles, bitmap font); unloaded on level exit
**Rendering:** 20k sparks via ParticleContainer (position dynamic only); actors culled each frame
**Leaks fixed:** enemies destroyed with children; ticker callbacks removed on scene exit
**Measured:** 60 FPS at 20k particles on mid laptop; heap flat after 1 min spawn/destroy loop