Official PixiJS skills covering Application, scene graph, sprites, graphics, text, filters, mesh, custom rendering, performance, and v7-to-v8 migration, plus PixiJS 3D (@pixi/3d) scenes, glTF models, materials, lights, cameras, and post-processing

GitHub stars
378

Install

/plugin install pixijs-skills@pixijs-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add pixijs/pixijs-skills.

Contents

Discovered from source

Skills 2

PixiJS 3D (@pixi/3d) is PixiJS's 3D extension. A View3D is an ordinary 2D display object on the Pixi stage that renders a 3D scene into its rectangle, so 3D and 2D mix freely. The scene hangs from view.root, the view owns its camera, lights are nodes in the scene, and the Pixi application ticker is the frame loop.

This file gives you the mental model, a complete starting app, and the conventions that catch people. The references/ folder has one complete, runnable recipe per job; open the one you need.

For a signature or option this skill doesn't cover, fetch the class's API page: https://3d.pixijs.download/release/docs/<module>.<Class>.html.md (scene.View3D, materials.Material3D, extras_camera.OrbitCamera, maths.Vector3). To find a class's module, or a guide on a topic, look it up in https://3d.pixijs.download/release/docs/llms.txt.

Quick Start

A lit scene with shadows, two primitives, a loaded model and mouse orbit controls. Complete src/main.ts for a Vite + TypeScript app with pixi.js and @pixi/3d installed.

import {
  CubeGeometry,
  DirectionalLight,
  Material3D,
  Mesh3D,
  Model3D,
  PlaneGeometry,
  SphereGeometry,
  View3D,
} from '@pixi/3d';
import type { Scene3DSource } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';
import { Application, Assets } from 'pixi.js';

const app = new Application();
await app.init({ resizeTo: window, backgroundColor: 0x87b7e6, antialias: true });
document.body.appendChild(app.canvas);

// A View3D is a 2D display object that renders a 3D scene into its rectangle.
const view = new View3D({
  autoResize: true,
  shadowQuality: 'medium',
  environment: { skyColor: 0xbcd4f0, groundColor: 0x6b6250, intensity: 0.7 }, // hemisphere fill light
});
app.stage.addChild(view);

// Lights are nodes under view.root. Lights and cameras face their local -Z axis.
const sun = new DirectionalLight({ color: 0xfff2dc, intensity: 3, castShadow: true });
sun.rotation.set(-Math.PI / 4, Math.PI / 6, 0);
view.root.addChild(sun);

// PlaneGeometry lies in XY with a +Z normal: rotate it -90° around X to make a floor.
const ground = new Mesh3D({
  geometry: new PlaneGeometry({ width: 30, height: 30 }),
  material: new Material3D({ baseColor: 0x7f8f6a, roughness: 0.95, metallic: 0 }),
  rotation: { x: -Math.PI / 2, y: 0, z: 0 },
  castShadow: false,
  receiveShadow: true,
});
view.root.addChild(ground);

// Meshes take a geometry and a material. Options objects set position, rotation, scale, shadows.
view.root.addChild(
  new Mesh3D({
    geometry: new CubeGeometry({ width: 2, height: 2, depth: 2 }),
    material: new Material3D({ baseColor: 0xd9534f, roughness: 0.6, metallic: 0 }),
    position: { x: -3, y: 1, z: 0 },
  }),
  new Mesh3D({
    geometry: new SphereGeometry({ radius: 1.2 }),
    material: new Material3D({ baseColor: 0x4a90d9, roughness: 0.3, metallic: 0.2 }),
    position: { x: 3, y: 1.2, z: 0 },
  }),
);

// Models: load a glTF/GLB with Assets, then wrap the source in a Model3D.
const source = await Assets.load<Scene3DSource>('/assets/models/Duck.glb');
// The file's own node transforms set its size (this duck is about 1.6 units); read duck.getLocalBounds() before scaling.
const duck = new Model3D({ source, position: { x: 0, y: 0, z: 3 } });
view.root.addChild(duck);

// The view owns its camera. OrbitCamera (extras) drives it from the mouse.
view.camera.position.set(0, 5, 12);
view.camera.lookAt({ x: 0, y: 1, z: 0 });
new OrbitCamera({ view, enableDamping: true });

// Per-frame work goes on the application ticker.
app.ticker.add((ticker) => {
  duck.rotation.y += 0.01 * ticker.deltaTime;
});

Conventions

  • Scene graph. Everything 3D goes under view.root (a Container3D); a mesh on app.stage does nothing useful. Nodes have position, rotation (Euler radians), quaternion, scale, visible, lookAt(point), addChild, traverse(callback) over a subtree, and bounds via getLocalBounds().
  • Options objects. Constructors take one options object: new Mesh3D({ geometry, material, position: { x, y, z }, castShadow, parent: view.root }). The same values are plain properties afterwards (mesh.position.set(x, y, z)).
  • Camera. view.camera is a Camera3D: fov is the vertical field of view in degrees (default 60), near 0.1, far 1000, mode 'perspective' or 'orthographic' with orthographicSize (half the view's width in world units, default 5). Aim it with position.set(...) and lookAt(point).
  • Facing. Cameras and lights look down their local -Z; meshes and glTF models face +Z. A DirectionalLight is aimed by its rotation (or lookAt), not a target.
  • Planes. PlaneGeometry lies in the XY plane with a +Z normal. For a floor, rotate it -π/2 around X.
  • Primitive options. CubeGeometry({ width, height, depth }), SphereGeometry({ radius }), CylinderGeometry({ radiusTop, radiusBottom, height }) (no radius), ConeGeometry({ radius, height }), CapsuleGeometry({ radius, height }) (height includes the caps), TorusGeometry({ radius, tube }) (lies in XZ), PlaneGeometry({ width, height }), IcosahedronGeometry({ radius, detail }). Each also takes segment counts.
  • Lighting. DirectionalLight, PointLight, SpotLight, AmbientLight are nodes. Soft fill comes from the view's environment: { skyColor, groundColor, intensity } for a hemisphere, or a CubeTexture (.cubemap or .hdr via Assets.load) for image-based lighting. Shadows: castShadow on the light, castShadow / receiveShadow on meshes, shadowQuality ('low' | 'medium' | 'high' | 'ultra') on the view.
  • Materials. Material3D is physically based (baseColor, metallic, roughness, baseColorTexture, alphaMode, alpha); glow is an opt-in group, emissive: { color, strength }, never a plain colour. FlatMaterial is unlit. Custom looks come from shader bits in extraBits, not a ShaderMaterial class. material.clone(options) copies a material with options changed or bits added.
  • Models. Assets.load<Scene3DSource>(url) then new Model3D({ source }). Animation clips play through model.player. Models from one source share its materials; model.materials gives one model its own.
  • Extras. OrbitCamera, FPSCamera, ParticleSystem3D, BloomEffect, SsaoEffect, TiltShiftEffect, MotionBlurEffect, TintEffect, FxaaEffect, ToonMaterial, PortalPass, PortalMaterial, dissolveBit live in @pixi/3d/extras.
  • Many copies. BatchedMesh3D draws thousands of instances in one call (setMatrixAt, setInstanceDataAt). Separate Mesh3D nodes batch into instanced draws on their own when they share a geometry, the same kind of material and the same texture sources: the frames of one sprite sheet count as one source, so Sprite3Ds or textured meshes showing different frames of one sheet still draw together. Pack one effect's images into one sheet.
  • 2D over 3D. HUD text, buttons and sprites are ordinary Pixi objects added to the stage after the view. view.worldToScreen(point) places a 2D label at a 3D position; it always draws over the 3D. For a picture inside the scene that walls can hide, use new Sprite3D({ texture, height, billboardMode, parent: view.root }).
  • The app around it is pixi.js. Application and await app.init, Assets, Text, pointer events and the ticker are pixi.js v8; when the pixijs skill is installed, use it for those.
  • Renderers. app.init uses WebGL unless you pass preference: 'webgpu'; nothing else in your code changes. MSAA is app.init({ antialias: true }); View3D has no antialias option.
  • No enums. Options like shadowQuality, alphaMode and mode are string literals. There is no LightType or ShadowQuality enum.

Pitfalls that fail silently

Each line is the fix; its link owns the rule. These run without errors and draw or behave wrongly. Check the groups for what you built.

Scene graph and math

  • lookAt, reparentChild and loaded glTF nodes set quaternion, and a node turns by whichever of rotation or quaternion was written last: on those nodes rotation.y += x replaces the real turn, so turn them with quaternion.multiply(q). scene-graph
  • addChild keeps a node's local numbers, so it jumps to the same offset under its new parent; reparentChild keeps its place in the world. scene-graph
  • view.root holds the camera: clearing or hiding view.root makes rendering throw. Put level content under its own Container3D and clear that. scene-graph
  • getLocalBounds() is in the node's own space and leaves out hidden children: for a world box use getLocalBounds().applyMatrix4(node.getGlobalTransform()). math
  • Vector3 math works in place (a.add(b) changes a; pass an out to keep it) and uses subtract, multiplyScalar, magnitude and copyFrom. A node's position is live, so copy what you keep. math
  • A ground plane at height h is new Plane(new Vector3(0, 1, 0), -h) (note the minus), or setFromNormalAndCoplanarPoint. math

Light and colour

  • Views default to toneMapping: 'none', where lit colour clips above 1: set toneMapping: 'aces' for strong lights, HDR environments or bloom. environment-and-sky
  • Porting from Three.js: a HemisphereLight(sky, ground, i) becomes environment: { skyColor, groundColor, intensity: i / Math.PI }; directional, point, spot and ambient intensities port 1:1. from-threejs
  • Direct lights and AmbientLight are divided by π and the hemisphere is not: a sun near 3 and a hemisphere near 0.7 light baseColor fully, and an AmbientLight of 0.2 is barely visible. scene-and-lighting
  • Vertex colours are linear light: convert sRGB picks with srgbToLinear, or mid tones come out pale. geometry
  • A view shades 32 lights and 16 shadow maps; past 256 casters the sun's shadow box is measured once, so call sun.fitShadowBounds() after the scene changes. scene-and-lighting

Surfaces

  • alphaMode defaults to 'opaque', which ignores alpha and texture alpha (transparent PNG texels draw black): set 'blend' or 'mask'. materials
  • A 'mask' cut-out, or a shader bit that moves or discards vertices (dissolveBit), still casts the whole undisplaced shadow and outline: give it castShadow: false and material.disablePass('outline') if that shows. materials, custom-shaders
  • Images show upside down on PlaneGeometry unless flipV: true, and on CubeGeometry faces unless the material has uvTransform: new Matrix(1, 0, 0, -1, 0, 1) (Matrix from pixi.js). from-threejs
  • A ContainerTexture on an opaque material draws black where the 2D is transparent: add a backdrop, clearColor, or alphaMode: 'blend'. render-to-texture

Models and animation

  • A glTF file's own node transforms already size it and stand it Y-up facing +Z: read getLocalBounds() before scaling and add no fix-up rotation. models-and-animation
  • A loaded model draws its source's materials, so a write to one changes every model from that file: give one model copies with model.materials = (m) => m.clone(), and build a changed loaded material with clone(options), not new Material3D, which drops its textures. models-and-animation
  • Most bones aren't scene nodes, so getChildByLabel('Hand', true) returns null: use model.skeletons[0]. models-and-animation
  • Write into mesh.weights; assigning a new array disconnects it from the clips that animate it. models-and-animation
  • A Mesh3D with no geometry or material draws nothing and raises no error. geometry

Input and cameras

  • OrbitCamera, FPSCamera, ParticleSystem3D and a model's animation player update themselves on Ticker.shared, not app.ticker, so their step can land after your frame's code or a frame late: pass autoUpdate: false and call update(ticker) from your app.ticker callback when order matters (orbit.update() returns true when the camera moved). cameras

  • 3D nodes default to eventMode: 'passive': set 'static' (also a Mesh3D option) or nothing picks. pointertap fires for every mouse button, so check e.button. picking-and-input

  • A full-screen view hit-tests its whole rectangle, so it blocks clicks to 2D objects behind it: put interactive 2D above the view or set view.hitArea. 2d-and-3d-together

  • OrbitCamera.enabled = false only stops input; update() keeps re-aiming the camera, so also set autoUpdate = false (or destroy()) before moving the camera yourself. cameras

  • FPSCamera walking follows the pitch, so looking down sinks the camera: re-pin position.y after update() for a ground walker. cameras

Effects and render to texture

  • BloomEffect's threshold is 1 in linear light: make glowing things emissive with strength above 1; a threshold near 0.5 blooms every lit surface. MSAA carries through effects, so add FxaaEffect only without antialias. post-processing
  • A camera feed shown on a mesh under a filmic curve ('aces') goes through the curve twice and looks washed out; format: 'rgba16float' is the documented fix with bloom-style effects, but on a FlatMaterial monitor it currently draws too dark, so compare the screen with the scene by eye, or show the feed in a 2D Sprite. Make feeds with antialias: true or their edges are jagged. render-to-texture
  • Toggle effects with enabled; adding the first or removing the last pre-curve effect recompiles every material. post-processing

Particles

  • ParticleContainer3D shows nothing until upload() after setParticleAt. particles

Current library limitations (workarounds until they're fixed)

  • A glTF mesh without normals (Fox.glb is one) lights as if every face pointed +Z, black when it turns away: rebuild flat normals with getAttributeData. from-threejs
  • SphereGeometry maps images mirrored left to right: uvTransform: new Matrix(-1, 0, 0, 1, 1, 0) plus rotation.y = Math.PI fixes it. from-threejs
  • A Sprite3D created with no position, scale or anchor draws 1×1 units instead of its texture size until one of them changes: always pass a position. 2d-and-3d-together

Which reference to open

jobfile
scene graph: parent and child, transforms, rotation vs quaternion, lookAt, local and world space, find by label, reparent, bounds and size, visibility, scene events, destroyreferences/scene-graph.md
vectors, quaternions, matrices, smooth turning, boxes, spheres, rays, planes, frustum tests, spherical orbitsreferences/math.md
scene, ground, sun, point and spot lights, shadowsreferences/scene-and-lighting.md
load a glTF, frame it, play and cross-fade clips, one model's own materials, dissolve, bones, morph targetsreferences/models-and-animation.md
PBR, unlit, toon, emissive, transparency, texturesreferences/materials.md
built-in geometries, custom vertex data, terrain, lines and pointsreferences/geometry.md
thousands of instances, per-instance data, batching, LODreferences/instancing.md
click, hover, drag, raycast, screen-to-world, keyboardreferences/picking-and-input.md
camera control, orbit, first-person, orthographic, clipping, followreferences/cameras.md
skybox, cubemaps, HDR (.hdr), image-based lighting, fog, tone mappingreferences/environment-and-sky.md
bloom, SSAO, tilt-shift, motion blur, FXAA, effect order, scene resolutionreferences/post-processing.md
emitters, bursts, hand-driven particlesreferences/particles.md
second camera to a texture, live 2D on a surface, portalsreferences/render-to-texture.md
HUD, labels, Sprite3D billboards, 2D filters and masks, several views, resolutionreferences/2d-and-3d-together.md
shader bits, custom material effectsreferences/custom-shaders.md
port a Three.js app: paired program, differences that change the picture, full name tablesreferences/from-threejs.md

If you know Three.js or the unrelated pixi3d package

you may reach foruse here
Scene, renderer.renderView3D on app.stage; Pixi renders it
renderer.setAnimationLoopapp.ticker.add
PerspectiveCamera, OrthographicCameraview.camera; camera.mode = 'orthographic' + orthographicSize
OrbitControls, CameraOrbitControlOrbitCamera (extras)
Mesh(geometry, material), Mesh3D.createCube()new Mesh3D({ geometry: new CubeGeometry(), material })
MeshStandardMaterial, StandardMaterialMaterial3D
MeshBasicMaterialFlatMaterial
ShaderMateriala ShaderBit in extraBits
HemisphereLight, LightingEnvironment, ImageBasedLightingthe view's environment
ShadowCastingLightcastShadow: true on a light
GLTFLoader, Model.fromAssets.load<Scene3DSource> + new Model3D({ source })
AnimationMixermodel.player
InstancedMeshBatchedMesh3D
Raycasterpointer events on meshes, or view.raycast
Box3node.getLocalBounds()
EffectComposerview.passes with effects from extras
CSS2DRendererPixi Text on the stage + worldToScreen

Every other Three.js name, and the behaviour that differs after a rename, is in references/from-threejs.md.

Read before you write

  1. List the files. Write down every router row below that your task touches: each class you construct, options object you pass, effect you build and symptom you fix. A whole app usually lists four to eight (an eraser paint app: application, assets, scene-sprite, events, blend-modes; a game: application, assets, scene-sprite, events, ticker, scene-text).
  2. Read each listed file before you write the code for that part, even for a one-line change. Open the file itself; a Grep hit is a fragment that drops the rule and the exception beside it. Each topic file links to its sub-pages for rarer branches.
  3. Done when every file on your list has been opened. Then check your code against the pitfall group below for each feature you built.

No row fits: scan references/index.md (sub-pages, long-tail keywords, error strings), then the project's local PixiJS docs.

For a signature or option this skill doesn't cover, fetch the class's API page: https://pixijs.download/release/docs/<module>.<Class>.html.md (app.Application, scene.Graphics, rendering.Texture, assets.Assets). To find a class's module, look it up in https://pixijs.download/release/docs/llms.txt.

Pitfalls that fail silently

Each line is the fix; its link owns the rule and the code. These run without errors and draw the wrong thing, and a Vite build doesn't type-check, so run npx tsc --noEmit to catch wrong option names.

App setup and the frame loop

  • const app = new Application(); await app.init({ ... }). Constructor options are ignored; until init resolves app.renderer is undefined and app.canvas/app.screen throw. application
  • Top-level await fails vite build on Vite 6 and older; wrap init in an async IIFE. create
  • With resizeTo, lay out in app.renderer.on('resize', (w, h) => ...); your own window resize listener reads the old app.screen. An element target also needs new ResizeObserver(() => app.queueResize()). application
  • Ticker callbacks receive the Ticker: app.ticker.add((t) => (s.x += 2 * t.deltaTime)). deltaTime is ~1 per 60 fps frame, deltaMS is milliseconds. ticker
  • app.ticker.update() already renders, even with autoStart: false; skip the extra app.render(). ticker
  • Per-object frame logic: obj.onRender = () => { ... } (replaces v7 updateTransform overrides); it also runs while the object is invisible. Name subclass methods anything but _onRender. ticker
  • Read canvas pixels from a listener at UPDATE_PRIORITY.UTILITY, which runs after the render. ticker

Loading assets and textures

  • await Assets.init({ basePath, manifest }) before the first load, loadBundle or backgroundLoad; a later init is dropped. assets
  • Assets.load([a, b]) resolves an object keyed by URL or alias: read res[a]. assets
  • A URL with no file extension (?id=, blob:, API route) needs Assets.load({ src, parser: 'texture' }); without it the result is null with only a warning. Audio files have no loader and also resolve null; play sound with @pixi/sound or HTMLAudioElement. assets
  • Texture.from(url) and Sprite.from(url) read the cache only (v7 fetched): await Assets.load(url) first. scene-sprite
  • Wrap a TextureSource (CanvasSource, texture.source): Sprite.from(source) or new Sprite(Texture.from(source)); new Sprite(source) draws nothing. scene-sprite
  • Show another region with sprite.texture = new Texture({ source, frame: new Rectangle(...) }), or create the texture with dynamic: true and call texture.update(). scene-sprite
  • After drawing into a source canvas, call texture.source.update(). sprite
  • Per-asset data (scaleMode, resolution) applies on the first load of a src only; set texture.source.scaleMode on the result instead. assets

Sprites and animation

  • AnimatedSprite: animationSpeed is frames per 60 fps tick (12 fps is 0.2), and it needs autoPlay: true or play(). It runs on Ticker.shared, so app.ticker.stop() doesn't pause it. animated-sprite
  • Call play() after each anim.textures = ... swap; replay a finished one-shot with gotoAndPlay(0). animated-sprite
  • Rotate or scale about a point with origin; pivot also moves the object, and anchor (0-1) shifts only the texture. scene-sprite

Graphics

  • Shape first, then style: new Graphics().rect(0, 0, 100, 50).fill(0xff0000).stroke({ width: 2, color: 0x000000 }). beginFill, drawRect and lineStyle are v7. scene-graphics
  • FillGradient: options object, every colour stop set before the first draw, textureSpace: 'global' for pixel coordinates (the default 'local' is 0-1 across the shape). scene-graphics
  • Draw-time transforms apply in call order, the reverse of Canvas 2D: rotateTransform(a).translateTransform(x, y). scene-graphics
  • Stroke alignment is 1 inside, 0 outside (inverted from v7). scene-graphics
  • Animate a stable Graphics by its transform; clear() and redraw every frame re-tessellates. scene-graphics

Drawing into textures (paint, eraser, scratch-off, fog of war, baking)

  • The render root's own blendMode is ignored: put an 'erase' brush inside a plain Container and pass the wrapper to renderer.render({ container: wrapper, target, clear: false }). clear: false keeps earlier strokes. blend-modes
  • 'erase' clears everything under it in the same target, background included; give the erasable layer its own RenderTexture and erase into that. blend-modes
  • Brush coordinates are texture pixels: sprite.toLocal(e.global) plus the anchor offset. blend-modes
  • generateTexture({ target, frame: new Rectangle(...) }): frame is a real Rectangle (a plain object throws copyTo is not a function), and the capture ignores the target's own position, scale and rotation. renderers
  • A cacheAsTexture(true) container shows changes to its children only after updateCacheTexture(). performance

Particles

  • Fill a ParticleContainer with addParticle(...particles); the particles option draws nothing until update(). Type it new ParticleContainer<Particle>(...) to reach tint and alpha. scene-particle-container
  • Mark every property you change per frame in dynamicProperties: position, rotation, vertex (scale, anchor), color (tint, alpha), uvs (texture). A static one changes only after update(), and v7's tint/scale keys are ignored. scene-particle-container
  • All particles share one texture source (frames of one atlas). Give the container boundsArea (its bounds are empty, so culling and filters skip it) and hitArea plus eventMode for pointer events. scene-particle-container

Filters and blend modes

  • Assign a new array to change filters: c.filters = [...(c.filters ?? []), blur]. filters
  • Custom GLSL: Filter.from({ gl: { vertex: defaultFilterVert, fragment }, resources }). In the fragment sample uTexture, get 0-1 coordinates from vTextureCoord * uInputSize.xy / uOutputFrame.zw (both highp), and keep colour premultiplied (invert with vec4(c.a - c.rgb, c.a)). filters
  • On the WebGPU renderer (preference: 'webgpu') every filter needs a gpu program too, or all filters on that container are skipped. The Canvas renderer skips filters. filters
  • Effects that reach past the shape (glow, wave, outline) need padding; a full-screen stage filter needs app.stage.filterArea = app.screen; use resolution: 'inherit' on a high-DPI renderer. filters
  • DisplacementFilter takes a Sprite that is on the stage; animate the distortion by moving that sprite (map texture addressMode = 'repeat'). A TilingSprite's tilePosition is never read. filters
  • A filtered container composites with its last filter's blendMode: new BlurFilter({ strength: 8, blendMode: 'add' }). blend-modes
  • Modes beyond normal/add/multiply/screen/erase/min/max need import 'pixi.js/advanced-blend-modes' and, on WebGL, app.init({ useBackBuffer: true }). blend-modes

Text

  • new Text({ text, style: { fill: 0xffffff } }): the default fill is black, invisible on the default black background. scene-text
  • Strings that change every frame (score, timer, FPS) go in BitmapText; each Text change redraws a canvas and re-uploads it. scene-text
  • Load web fonts with await Assets.load({ src, data: { family } }) before creating text; HTMLText sees only fonts loaded this way. html-text
  • Raise style.padding when a stroke or drop shadow is clipped. text

Input

  • Give every listening object eventMode = 'static' (the default 'passive' never fires its own listeners) and cursor = 'pointer' (v7 buttonMode). events
  • Clicks on empty canvas: app.stage.eventMode = 'static' and app.stage.hitArea = app.screen. A plain Container is hit only on its children; give it a hitArea to cover the gaps. events
  • visible = false and renderable = false remove an object from hit testing; an invisible target uses alpha = 0 or a hitArea. scene-container
  • Buttons listen to pointertap (click is mouse only, tap touch only); a double click is e.detail === 2. events
  • Drag with globalpointermove (plain pointermove fires only over the object), end on pointerup and pointerupoutside, convert with parent.toLocal(e.global), and keep points with p.copyFrom(e.global) (event objects are reused). events
  • Stop page scroll with a native app.canvas.addEventListener('wheel', (e) => e.preventDefault(), { passive: false }). events

Scene order, coordinates and masks

  • zIndex orders siblings only and sorts at the next render; call parent.sortChildren() before reading children. scene-container
  • Depth-sort across parents with new RenderLayer({ sortableChildren: true }) and layer.attach(obj); attach again after reparenting, and hide or move the objects themselves (the layer's own visible, alpha and position do nothing). layers
  • Add a mask as a child of the masked Container; a Sprite mask reads the red channel unless setMask({ mask, channel: 'alpha' }). masking
  • Map pointers into rotated or scaled containers with container.toLocal(e.global); getBounds() returns Bounds, so hit-test with getBounds().rectangle.contains(x, y). scene-container
  • Matrix methods apply in call order and a.append(b) applies b first; Container-style is scale().rotate().translate(), applied with setFromMatrix. math
  • Copy points with copyFrom(p) or set(x, y); pixi.js/math-extras methods return a new point, so update in place with pos.add(v, pos). math
  • Color reads a plain number[] as 0-1 ([180, 60, 90] is white); pass 0-255 as a Uint8Array, and alpha as '#rrggbbaa' (0xRRGGBBAA throws). color

Teardown

  • Destroy a subtree with destroy({ children: true }) and free loaded files with Assets.unload(key). destroy(true) also destroys shared textures, atlases and GraphicsContexts, and every later render of another user throws. scene-container
  • Call app.destroy() after init resolves (in React effects, chain it on the init promise); pass releaseGlobalResources: true when re-creating an app in the same tab. application
  • Destroy textures you create (generateTexture, canvases) with texture.destroy(true); defer a destroy from inside onRender with app.ticker.addOnce(() => obj.destroy()). performance, scene-container

Renderers and builds

  • Application picks WebGL unless preference: 'webgpu'. The Canvas renderer skips filters and draws nothing for Mesh. renderers
  • pixi.js/math-extras, pixi.js/prepare, pixi.js/gif and pixi.js/advanced-blend-modes work only after a side-effect import; with skipExtensionImports: true, also import pixi.js/events, pixi.js/filters, pixi.js/accessibility and pixi.js/dom. environments

Reference router

Foundations

ReferenceRead when your code touches...
applicationApplication, app.init() options and defaults, app.stage/renderer/canvas/screen, resizeTo, queueResize, layout on resize, resolution/autoDensity/HiDPI (also after init), autoStart, sharedTicker, app.start()/stop(), CullerPlugin, Application plugins, app.destroy() and React StrictMode cleanup.
core-conceptsChoosing WebGL/WebGPU/Canvas, autoDetectRenderer, checking the backend, renderer.render() options (clear, transform, target), RenderTexture/RenderTarget, generateTexture, systems and pipes, renderer loaders, Three.js interop (resetState), context and device loss.
tickerPer-frame logic: app.ticker.add, deltaTime vs deltaMS, UPDATE_PRIORITY and frame order, maxFPS/minFPS, speed, onRender (v7 updateTransform), Ticker.shared, a manual loop with ticker.update(), pausing.
environmentsWeb Workers and OffscreenCanvas, Node/SSR/headless, strict CSP (pixi.js/unsafe-eval), DOMAdapter and custom fetch (auth headers), custom or tree-shaken builds (skipExtensionImports, side-effect imports), bundle size.
createScaffolding with npm create pixi.js and its templates, adding pixi.js to an existing project, tsconfig for TypeScript 5-7, Vite top-level-await build errors, @webgpu/types conflicts.
migration-v8Porting a whole v7 codebase: @pixi/* imports, BaseTexture, DisplayObject, settings and utils, renderer.plugins, renamed options and enums (SCALE_MODES, BLEND_MODES). For one API, its topic file is enough.

Scene

ReferenceRead when your code touches...
scene-core-conceptsThe scene graph as a whole: containers vs leaves, render order, which class to use; sub-pages for coordinate spaces and worldTransform, render groups (isRenderGroup, panning a world), constructor options, RenderLayer (depth sort across parents), and masks (mask, setMask, inverse, sprite-mask channel).
scene-containerContainer: addChild/removeChildren/reparentChild, pivot vs origin, hiding (visible/renderable/alpha), zIndex and sortChildren(), getBounds, toGlobal/toLocal, setSize, container events, onRender, destroy options.
scene-spriteSprite, Texture vs TextureSource, Sprite.from/Texture.from, sub-textures and frame, dynamic and canvas textures, shared-texture destroy; AnimatedSprite (speed, swapping or replaying animations, onComplete), NineSliceSprite (panels, borders), TilingSprite (tilePosition, scrolling backgrounds).
scene-graphicsGraphics beyond a colour-filled shape: paths, holes (cut), strokes, FillGradient, FillPattern, texture fills, draw-time transforms, GraphicsContext sharing, SVG import and export (svg(), graphicsContextToSvg), hit testing, smooth edges without MSAA (SmoothGraphics), dashed lines (DashLineShader), v7 beginFill/lineStyle ports.
scene-textText, TextStyle, BitmapText (BitmapFont.install, .fnt, MSDF), HTMLText (fonts, tag styles), SplitText/SplitBitmapText, per-frame text cost, shaped scripts.
scene-meshMesh, MeshGeometry (positions, uvs, indices, topology), MeshSimple, MeshPlane, MeshRope (trails), PerspectiveMesh, UVs and addressMode, mesh hit testing.
scene-particle-containerParticleContainer, Particle, dynamicProperties, update(), emitters and particle pools, fading or tinting particles, pointer events on particles.
scene-dom-containerHTML elements over the canvas: DOMContainer, inputs and iframes, click-through pointer-events, domContainerRoot, removing the element.
scene-gifAnimated GIFs: pixi.js/gif, GifSprite, GifSource, GIF frame rate, cleanup.
html-sourceLive HTML/DOM rendered into a texture (experimental HTML-in-Canvas): HTMLSource, ElementImageSource, pixi.js/html-source, requestPaint.

Utilities

ReferenceRead when your code touches...
assetsAssets.init/load/add/get/unload, load result shapes, extension-less or blob: URLs (parser), retries and errors, bundles, manifests, background loading, progress bars, spritesheets, fonts, video, SVG, compressed textures, @2x resolution.
eventsPointer, mouse, touch, wheel: eventMode, pointertap vs click/tap, double click, propagation and capture, hitArea, interactiveChildren, clicks on empty canvas, drag (globalpointermove), cursor, FederatedPointerEvent, eventFeatures.
mathPoint/ObservablePoint (set, copyFrom), Matrix (order, append/prepend, decompose, setFromMatrix), Rectangle and hit-area shapes, pixi.js/math-extras vector methods, DEG_TO_RAD.
colorColor and ColorSource: input ranges (hex with alpha, arrays, Uint8Array), conversions (toHex, toRgba, toNumber), tint and alpha, premultiply, v7 utils.string2hex.
accessibilityScreen readers and keyboard navigation: accessible, accessibleTitle, tabIndex, accessibilityOptions, no overlay element appearing.

Effects and rendering

ReferenceRead when your code touches...
blend-modesAny blendMode (add, multiply, screen, erase), an eraser, scratch-off or fog of war, painting into a RenderTexture, blend mode of the render root or of a filtered container, overlay and other advanced modes.
filtersBlurFilter, ColorMatrixFilter, DisplacementFilter, NoiseFilter, AlphaFilter, custom Filter.from (GLSL, WGSL), filter uniforms, padding, filterArea, resolution, blendRequired, pixi-filters, multi-pass filters (bloom).
custom-renderingCustom shaders on a Mesh: Shader.from, GlProgram/GpuProgram, UniformGroup and uniform types, textures as resources, built-in shader inputs (aPosition, uProjectionMatrix); custom batchers, pipes, render bundles, 3D/array/storage textures.
performanceFPS, draw calls, memory leaks, first-frame hitches: teardown (destroy, Assets.unload), GCSystem, PrepareSystem, render groups, cacheAsTexture, batching order, culling (cullable), pooling, filter and mask cost.

Sponsors

Details

Marketplace
pixijs/pixijs-skills
Author
PixiJS
Category
Productivity