
pixijs-skills
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add pixijs/pixijs-skills.
Contents
Discovered from sourceSkills 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(aContainer3D); a mesh onapp.stagedoes nothing useful. Nodes haveposition,rotation(Euler radians),quaternion,scale,visible,lookAt(point),addChild,traverse(callback)over a subtree, and bounds viagetLocalBounds(). - 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.camerais aCamera3D:fovis the vertical field of view in degrees (default 60),near0.1,far1000,mode'perspective'or'orthographic'withorthographicSize(half the view's width in world units, default 5). Aim it withposition.set(...)andlookAt(point). - Facing. Cameras and lights look down their local -Z; meshes and glTF models face +Z. A
DirectionalLightis aimed by itsrotation(orlookAt), not a target. - Planes.
PlaneGeometrylies 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 })(noradius),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,AmbientLightare nodes. Soft fill comes from the view'senvironment:{ skyColor, groundColor, intensity }for a hemisphere, or aCubeTexture(.cubemapor.hdrviaAssets.load) for image-based lighting. Shadows:castShadowon the light,castShadow/receiveShadowon meshes,shadowQuality('low' | 'medium' | 'high' | 'ultra') on the view. - Materials.
Material3Dis physically based (baseColor,metallic,roughness,baseColorTexture,alphaMode,alpha); glow is an opt-in group,emissive: { color, strength }, never a plain colour.FlatMaterialis unlit. Custom looks come from shader bits inextraBits, not a ShaderMaterial class.material.clone(options)copies a material with options changed or bits added. - Models.
Assets.load<Scene3DSource>(url)thennew Model3D({ source }). Animation clips play throughmodel.player. Models from one source share its materials;model.materialsgives one model its own. - Extras.
OrbitCamera,FPSCamera,ParticleSystem3D,BloomEffect,SsaoEffect,TiltShiftEffect,MotionBlurEffect,TintEffect,FxaaEffect,ToonMaterial,PortalPass,PortalMaterial,dissolveBitlive in@pixi/3d/extras. - Many copies.
BatchedMesh3Ddraws thousands of instances in one call (setMatrixAt,setInstanceDataAt). SeparateMesh3Dnodes 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, soSprite3Ds 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, usenew Sprite3D({ texture, height, billboardMode, parent: view.root }). - The app around it is pixi.js.
Applicationandawait app.init,Assets,Text, pointer events and the ticker are pixi.js v8; when thepixijsskill is installed, use it for those. - Renderers.
app.inituses WebGL unless you passpreference: 'webgpu'; nothing else in your code changes. MSAA isapp.init({ antialias: true });View3Dhas noantialiasoption. - No enums. Options like
shadowQuality,alphaModeandmodeare string literals. There is noLightTypeorShadowQualityenum.
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,reparentChildand loaded glTF nodes setquaternion, and a node turns by whichever ofrotationorquaternionwas written last: on those nodesrotation.y += xreplaces the real turn, so turn them withquaternion.multiply(q). scene-graphaddChildkeeps a node's local numbers, so it jumps to the same offset under its new parent;reparentChildkeeps its place in the world. scene-graphview.rootholds the camera: clearing or hidingview.rootmakes rendering throw. Put level content under its ownContainer3Dand clear that. scene-graphgetLocalBounds()is in the node's own space and leaves out hidden children: for a world box usegetLocalBounds().applyMatrix4(node.getGlobalTransform()). mathVector3math works in place (a.add(b)changesa; pass anoutto keep it) and usessubtract,multiplyScalar,magnitudeandcopyFrom. A node'spositionis live, so copy what you keep. math- A ground plane at height
hisnew Plane(new Vector3(0, 1, 0), -h)(note the minus), orsetFromNormalAndCoplanarPoint. math
Light and colour
- Views default to
toneMapping: 'none', where lit colour clips above 1: settoneMapping: '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
AmbientLightare divided by π and the hemisphere is not: a sun near 3 and a hemisphere near 0.7 lightbaseColorfully, and anAmbientLightof 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
alphaModedefaults to'opaque', which ignoresalphaand 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 itcastShadow: falseandmaterial.disablePass('outline')if that shows. materials, custom-shaders - Images show upside down on
PlaneGeometryunlessflipV: true, and onCubeGeometryfaces unless the material hasuvTransform: new Matrix(1, 0, 0, -1, 0, 1)(Matrixfrom pixi.js). from-threejs - A
ContainerTextureon an opaque material draws black where the 2D is transparent: add a backdrop,clearColor, oralphaMode: '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 withclone(options), notnew Material3D, which drops its textures. models-and-animation - Most bones aren't scene nodes, so
getChildByLabel('Hand', true)returns null: usemodel.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
Mesh3Dwith no geometry or material draws nothing and raises no error. geometry
Input and cameras
-
OrbitCamera,FPSCamera,ParticleSystem3Dand a model's animationplayerupdate themselves onTicker.shared, notapp.ticker, so their step can land after your frame's code or a frame late: passautoUpdate: falseand callupdate(ticker)from yourapp.tickercallback when order matters (orbit.update()returnstruewhen the camera moved). cameras -
3D nodes default to
eventMode: 'passive': set'static'(also aMesh3Doption) or nothing picks.pointertapfires for every mouse button, so checke.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 = falseonly stops input;update()keeps re-aiming the camera, so also setautoUpdate = false(ordestroy()) before moving the camera yourself. cameras -
FPSCamerawalking follows the pitch, so looking down sinks the camera: re-pinposition.yafterupdate()for a ground walker. cameras
Effects and render to texture
BloomEffect's threshold is 1 in linear light: make glowing thingsemissivewithstrengthabove 1; a threshold near 0.5 blooms every lit surface. MSAA carries through effects, so addFxaaEffectonly withoutantialias. 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 aFlatMaterialmonitor it currently draws too dark, so compare the screen with the scene by eye, or show the feed in a 2DSprite. Make feeds withantialias: trueor 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
ParticleContainer3Dshows nothing untilupload()aftersetParticleAt. 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 SphereGeometrymaps images mirrored left to right:uvTransform: new Matrix(-1, 0, 0, 1, 1, 0)plusrotation.y = Math.PIfixes it. from-threejs- A
Sprite3Dcreated with noposition,scaleoranchordraws 1×1 units instead of its texture size until one of them changes: always pass aposition. 2d-and-3d-together
Which reference to open
| job | file |
|---|---|
| scene graph: parent and child, transforms, rotation vs quaternion, lookAt, local and world space, find by label, reparent, bounds and size, visibility, scene events, destroy | references/scene-graph.md |
| vectors, quaternions, matrices, smooth turning, boxes, spheres, rays, planes, frustum tests, spherical orbits | references/math.md |
| scene, ground, sun, point and spot lights, shadows | references/scene-and-lighting.md |
| load a glTF, frame it, play and cross-fade clips, one model's own materials, dissolve, bones, morph targets | references/models-and-animation.md |
| PBR, unlit, toon, emissive, transparency, textures | references/materials.md |
| built-in geometries, custom vertex data, terrain, lines and points | references/geometry.md |
| thousands of instances, per-instance data, batching, LOD | references/instancing.md |
| click, hover, drag, raycast, screen-to-world, keyboard | references/picking-and-input.md |
| camera control, orbit, first-person, orthographic, clipping, follow | references/cameras.md |
| skybox, cubemaps, HDR (.hdr), image-based lighting, fog, tone mapping | references/environment-and-sky.md |
| bloom, SSAO, tilt-shift, motion blur, FXAA, effect order, scene resolution | references/post-processing.md |
| emitters, bursts, hand-driven particles | references/particles.md |
| second camera to a texture, live 2D on a surface, portals | references/render-to-texture.md |
| HUD, labels, Sprite3D billboards, 2D filters and masks, several views, resolution | references/2d-and-3d-together.md |
| shader bits, custom material effects | references/custom-shaders.md |
| port a Three.js app: paired program, differences that change the picture, full name tables | references/from-threejs.md |
If you know Three.js or the unrelated pixi3d package
| you may reach for | use here |
|---|---|
Scene, renderer.render | View3D on app.stage; Pixi renders it |
| renderer.setAnimationLoop | app.ticker.add |
| PerspectiveCamera, OrthographicCamera | view.camera; camera.mode = 'orthographic' + orthographicSize |
| OrbitControls, CameraOrbitControl | OrbitCamera (extras) |
Mesh(geometry, material), Mesh3D.createCube() | new Mesh3D({ geometry: new CubeGeometry(), material }) |
| MeshStandardMaterial, StandardMaterial | Material3D |
| MeshBasicMaterial | FlatMaterial |
| ShaderMaterial | a ShaderBit in extraBits |
| HemisphereLight, LightingEnvironment, ImageBasedLighting | the view's environment |
| ShadowCastingLight | castShadow: true on a light |
GLTFLoader, Model.from | Assets.load<Scene3DSource> + new Model3D({ source }) |
| AnimationMixer | model.player |
| InstancedMesh | BatchedMesh3D |
| Raycaster | pointer events on meshes, or view.raycast |
| Box3 | node.getLocalBounds() |
| EffectComposer | view.passes with effects from extras |
| CSS2DRenderer | Pixi 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
- 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).
- 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.
- 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; untilinitresolvesapp.rendererisundefinedandapp.canvas/app.screenthrow. application- Top-level
awaitfailsvite buildon Vite 6 and older; wrap init in an async IIFE. create - With
resizeTo, lay out inapp.renderer.on('resize', (w, h) => ...); your ownwindowresize listener reads the oldapp.screen. An element target also needsnew ResizeObserver(() => app.queueResize()). application - Ticker callbacks receive the
Ticker:app.ticker.add((t) => (s.x += 2 * t.deltaTime)).deltaTimeis ~1 per 60 fps frame,deltaMSis milliseconds. ticker app.ticker.update()already renders, even withautoStart: false; skip the extraapp.render(). ticker- Per-object frame logic:
obj.onRender = () => { ... }(replaces v7updateTransformoverrides); 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 firstload,loadBundleorbackgroundLoad; a laterinitis dropped. assetsAssets.load([a, b])resolves an object keyed by URL or alias: readres[a]. assets- A URL with no file extension (
?id=,blob:, API route) needsAssets.load({ src, parser: 'texture' }); without it the result isnullwith only a warning. Audio files have no loader and also resolvenull; play sound with@pixi/soundorHTMLAudioElement. assets Texture.from(url)andSprite.from(url)read the cache only (v7 fetched):await Assets.load(url)first. scene-sprite- Wrap a
TextureSource(CanvasSource,texture.source):Sprite.from(source)ornew 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 withdynamic: trueand calltexture.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 asrconly; settexture.source.scaleModeon the result instead. assets
Sprites and animation
AnimatedSprite:animationSpeedis frames per 60 fps tick (12 fps is0.2), and it needsautoPlay: trueorplay(). It runs onTicker.shared, soapp.ticker.stop()doesn't pause it. animated-sprite- Call
play()after eachanim.textures = ...swap; replay a finished one-shot withgotoAndPlay(0). animated-sprite - Rotate or scale about a point with
origin;pivotalso moves the object, andanchor(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,drawRectandlineStyleare 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
alignmentis1inside,0outside (inverted from v7). scene-graphics - Animate a stable
Graphicsby 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
blendModeis ignored: put an'erase'brush inside a plainContainerand pass the wrapper torenderer.render({ container: wrapper, target, clear: false }).clear: falsekeeps earlier strokes. blend-modes 'erase'clears everything under it in the same target, background included; give the erasable layer its ownRenderTextureand 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(...) }):frameis a realRectangle(a plain object throwscopyTo 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 afterupdateCacheTexture(). performance
Particles
- Fill a
ParticleContainerwithaddParticle(...particles); theparticlesoption draws nothing untilupdate(). Type itnew ParticleContainer<Particle>(...)to reachtintandalpha. 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 afterupdate(), and v7'stint/scalekeys 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) andhitAreapluseventModefor 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 sampleuTexture, get 0-1 coordinates fromvTextureCoord * uInputSize.xy / uOutputFrame.zw(bothhighp), and keep colour premultiplied (invert withvec4(c.a - c.rgb, c.a)). filters - On the WebGPU renderer (
preference: 'webgpu') every filter needs agpuprogram 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 needsapp.stage.filterArea = app.screen; useresolution: 'inherit'on a high-DPI renderer. filters DisplacementFiltertakes aSpritethat is on the stage; animate the distortion by moving that sprite (map textureaddressMode = 'repeat'). ATilingSprite'stilePositionis 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/maxneedimport '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; eachTextchange redraws a canvas and re-uploads it. scene-text - Load web fonts with
await Assets.load({ src, data: { family } })before creating text;HTMLTextsees only fonts loaded this way. html-text - Raise
style.paddingwhen a stroke or drop shadow is clipped. text
Input
- Give every listening object
eventMode = 'static'(the default'passive'never fires its own listeners) andcursor = 'pointer'(v7buttonMode). events - Clicks on empty canvas:
app.stage.eventMode = 'static'andapp.stage.hitArea = app.screen. A plainContaineris hit only on its children; give it ahitAreato cover the gaps. events visible = falseandrenderable = falseremove an object from hit testing; an invisible target usesalpha = 0or ahitArea. scene-container- Buttons listen to
pointertap(clickis mouse only,taptouch only); a double click ise.detail === 2. events - Drag with
globalpointermove(plainpointermovefires only over the object), end onpointerupandpointerupoutside, convert withparent.toLocal(e.global), and keep points withp.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
zIndexorders siblings only and sorts at the next render; callparent.sortChildren()before readingchildren. scene-container- Depth-sort across parents with
new RenderLayer({ sortableChildren: true })andlayer.attach(obj); attach again after reparenting, and hide or move the objects themselves (the layer's ownvisible,alphaand position do nothing). layers - Add a mask as a child of the masked
Container; aSpritemask reads the red channel unlesssetMask({ mask, channel: 'alpha' }). masking - Map pointers into rotated or scaled containers with
container.toLocal(e.global);getBounds()returnsBounds, so hit-test withgetBounds().rectangle.contains(x, y). scene-container Matrixmethods apply in call order anda.append(b)appliesbfirst; Container-style isscale().rotate().translate(), applied withsetFromMatrix. math- Copy points with
copyFrom(p)orset(x, y);pixi.js/math-extrasmethods return a new point, so update in place withpos.add(v, pos). math Colorreads a plainnumber[]as 0-1 ([180, 60, 90]is white); pass 0-255 as aUint8Array, and alpha as'#rrggbbaa'(0xRRGGBBAAthrows). color
Teardown
- Destroy a subtree with
destroy({ children: true })and free loaded files withAssets.unload(key).destroy(true)also destroys shared textures, atlases andGraphicsContexts, and every later render of another user throws. scene-container - Call
app.destroy()afterinitresolves (in React effects, chain it on the init promise); passreleaseGlobalResources: truewhen re-creating an app in the same tab. application - Destroy textures you create (
generateTexture, canvases) withtexture.destroy(true); defer a destroy from insideonRenderwithapp.ticker.addOnce(() => obj.destroy()). performance, scene-container
Renderers and builds
Applicationpicks WebGL unlesspreference: 'webgpu'. The Canvas renderer skips filters and draws nothing forMesh. rendererspixi.js/math-extras,pixi.js/prepare,pixi.js/gifandpixi.js/advanced-blend-modeswork only after a side-effect import; withskipExtensionImports: true, also importpixi.js/events,pixi.js/filters,pixi.js/accessibilityandpixi.js/dom. environments
Reference router
Foundations
| Reference | Read when your code touches... |
|---|---|
| application | Application, 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-concepts | Choosing 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. |
| ticker | Per-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. |
| environments | Web 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. |
| create | Scaffolding 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-v8 | Porting 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
| Reference | Read when your code touches... |
|---|---|
| scene-core-concepts | The 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-container | Container: addChild/removeChildren/reparentChild, pivot vs origin, hiding (visible/renderable/alpha), zIndex and sortChildren(), getBounds, toGlobal/toLocal, setSize, container events, onRender, destroy options. |
| scene-sprite | Sprite, 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-graphics | Graphics 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-text | Text, TextStyle, BitmapText (BitmapFont.install, .fnt, MSDF), HTMLText (fonts, tag styles), SplitText/SplitBitmapText, per-frame text cost, shaped scripts. |
| scene-mesh | Mesh, MeshGeometry (positions, uvs, indices, topology), MeshSimple, MeshPlane, MeshRope (trails), PerspectiveMesh, UVs and addressMode, mesh hit testing. |
| scene-particle-container | ParticleContainer, Particle, dynamicProperties, update(), emitters and particle pools, fading or tinting particles, pointer events on particles. |
| scene-dom-container | HTML elements over the canvas: DOMContainer, inputs and iframes, click-through pointer-events, domContainerRoot, removing the element. |
| scene-gif | Animated GIFs: pixi.js/gif, GifSprite, GifSource, GIF frame rate, cleanup. |
| html-source | Live HTML/DOM rendered into a texture (experimental HTML-in-Canvas): HTMLSource, ElementImageSource, pixi.js/html-source, requestPaint. |
Utilities
| Reference | Read when your code touches... |
|---|---|
| assets | Assets.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. |
| events | Pointer, mouse, touch, wheel: eventMode, pointertap vs click/tap, double click, propagation and capture, hitArea, interactiveChildren, clicks on empty canvas, drag (globalpointermove), cursor, FederatedPointerEvent, eventFeatures. |
| math | Point/ObservablePoint (set, copyFrom), Matrix (order, append/prepend, decompose, setFromMatrix), Rectangle and hit-area shapes, pixi.js/math-extras vector methods, DEG_TO_RAD. |
| color | Color and ColorSource: input ranges (hex with alpha, arrays, Uint8Array), conversions (toHex, toRgba, toNumber), tint and alpha, premultiply, v7 utils.string2hex. |
| accessibility | Screen readers and keyboard navigation: accessible, accessibleTitle, tabIndex, accessibilityOptions, no overlay element appearing. |
Effects and rendering
| Reference | Read when your code touches... |
|---|---|
| blend-modes | Any 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. |
| filters | BlurFilter, ColorMatrixFilter, DisplacementFilter, NoiseFilter, AlphaFilter, custom Filter.from (GLSL, WGSL), filter uniforms, padding, filterArea, resolution, blendRequired, pixi-filters, multi-pass filters (bloom). |
| custom-rendering | Custom 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. |
| performance | FPS, 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