gamedev-skills/awesome-gamedev-agent-skills / skills/web-engines/pixijs-rendering
pixijs-rendering
VerifiedBuilds and debugs 2D browser game rendering with PixiJS v8: async init, Assets loading, the Container and Sprite scene graph, pointer dragging and v7-to-v8 migration. Use when a game or playable ad uses pixi.js, or on a blank canvas, clicks not firing, or drag stopping at the sprite edge. Not for dashboards or charts, Phaser (`phaser-core`) or 3D (`threejs-scene-setup`).
PixiJS 8 rendering for games
Sets up and structures a PixiJS 8.22 game renderer: the async Application, asset
loading through Assets, the Container scene graph, the ticker loop, pointer events and
render groups. PixiJS draws; it has no scenes, physics or input mapping. A game that wants
those built in is usually better served by Phaser. With PixiJS you write the loop, the
screen manager and the collision code yourself.
When to use
- Starting a PixiJS v8 game or playable, fixing a blank canvas, structuring the display list, loading textures and sprite sheets, animating with the ticker, or handling pointer input.
package.jsondepends onpixi.js8.x and code imports from'pixi.js'.- Not for dashboards, charts or other non-game UIs, Phaser projects (
phaser-core) or 3D (threejs-scene-setup). PixiJS v7 code (new Application({...}),Loader,beginFill) must be migrated first; the Gotchas list the renames.
Workflow
- Read the installed version. v8 changed boot, loading, Graphics and events, so v7 answers from memory break here.
- Create, then
await app.init({...}). The v8 constructor takes no options. Appendapp.canvasto the page. - Load before you build.
await Assets.load(...)or a manifest bundle per screen; the returnedTextureis whatSpritetakes. - Build the display list from
Containers, one per layer (world, effects, HUD). Child transforms are relative to the parent; later children draw on top. - Run game logic in one ticker callback scaled by
ticker.deltaMS / 1000(seconds) orticker.deltaTime(≈1 per 60 Hz frame). Keep rules in plain modules the callback calls. - Turn on input per object with
eventMode = 'static', thenon('pointerdown', ...). - Clean up on screen changes:
destroy()what you remove andAssets.unload()what the next screen does not need. - Verify with Verify.
Patterns
1. Async boot
import { Application, Assets, Sprite } from 'pixi.js';
const app = new Application();
await app.init({
background: '#1099bb',
resizeTo: window,
antialias: true,
// preference: 'webgpu', // a hint; default order is webgl, webgpu, canvas
});
document.body.appendChild(app.canvas);
Object.assign(window, { app }); // for the smoke check and console debugging (TS-safe)
const texture = await Assets.load('assets/bunny.png');
const bunny = new Sprite(texture);
bunny.anchor.set(0.5);
bunny.position.set(app.screen.width / 2, app.screen.height / 2);
app.stage.addChild(bunny);
2. Layers as containers
import { Container } from 'pixi.js';
const world = new Container(); // camera: move or scale this, not every sprite
const hud = new Container(); // added last, so it draws over the world
app.stage.addChild(world, hud);
world.position.set(-camera.x, -camera.y);
world.scale.set(2);
3. One game loop on the ticker
app.ticker.add((ticker) => {
const dt = ticker.deltaMS / 1000; // seconds since the last frame
stepGame(state, input, dt); // rules live in a plain module
bunny.rotation += 1.5 * dt;
});
4. Pointer input and dragging
bunny.eventMode = 'static'; // the v8 default 'passive' ignores the object itself
bunny.cursor = 'pointer';
bunny.on('pointerdown', () => { dragging = true; });
bunny.on('pointerup', () => { dragging = false; });
bunny.on('pointerupoutside', () => { dragging = false; });
// pointermove fires only over the object in v8; globalpointermove fires on every move.
bunny.on('globalpointermove', (event) => {
if (dragging) bunny.position.copyFrom(event.global);
});
5. Load a screen's assets by name
// addBundle works at any time; Assets.init({ manifest }) only works before the first load.
Assets.addBundle('level-1', [
{ alias: 'hero', src: 'assets/hero.png' },
{ alias: 'atlas', src: 'assets/characters.json' }, // TexturePacker JSON
]);
Assets.addBundle('level-2', [{ alias: 'boss', src: 'assets/boss.png' }]);
const level = await Assets.loadBundle('level-1');
const hero = new Sprite(level.hero);
Assets.backgroundLoadBundle('level-2'); // warm the next screen while this one plays
6. Render group for a large static layer
const background = new Container({ isRenderGroup: true });
app.stage.addChildAt(background, 0);
// Hundreds of static tiles go in here. Moving `background` stays cheap;
// adding and removing children every frame cancels the benefit.
Verify
npm run build(ornpx tsc --noEmit) passes.- Smoke-test in a headless browser. With the dev server running and
window.appexposed (Pattern 1), runnode smoke.mjs <url>afternpm i -D playwrightandnpx playwright install chromium. Without browser automation, ask the user to open the page and report the console output and what is drawn.
// smoke.mjs: fails on page errors; prints the backend and the display list size.
import { chromium } from 'playwright';
const browser = await chromium.launch();
const page = await browser.newPage();
const errors = [];
page.on('pageerror', (e) => errors.push(e.message));
page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
await page.goto(process.argv[2]);
await page.waitForFunction(() => window.app?.renderer, null, { timeout: 15000 });
await page.waitForTimeout(1000); // let the first assets load
const state = await page.evaluate(() => ({
backend: window.app.renderer.name, // 'webgl', 'webgpu' or 'canvas'
stageChildren: window.app.stage.children.length,
tickerRunning: window.app.ticker.started,
canvasSize: [window.app.canvas.width, window.app.canvas.height],
}));
await page.screenshot({ path: 'smoke.png' });
await browser.close();
console.log(JSON.stringify({ ...state, errors }, null, 2));
process.exit(errors.length ? 1 : 0);
Expect a backend name, a non-zero child count, tickerRunning: true, a canvas size other
than 0 × 0, and no errors. Open smoke.png: a correct display list with missing textures
still renders blank sprites.
Gotchas
- Blank canvas, or
TypeErrorreadingcanvasorscreen→init()was not awaited, or options went to the constructor.app.stageexists at once, butapp.rendererisundefineduntilinit()resolves. - Ticker callback animates nothing (
NaN) → the callback's argument is theTicker, not a delta number. Readticker.deltaTimeorticker.deltaMSfrom it. - Speed changes with frame rate → movement was not scaled by delta.
deltaTimeis a multiplier (≈1 at 60 Hz), not milliseconds. - Clicks do nothing →
eventModeis still'passive'. Use'static', or'dynamic'for objects that move under a still cursor. - Drag stops at the object's edge →
pointermovefires only over the object in v8; useglobalpointermove. AssetManager already initializedwarning, thenloadBundlereturnsundefined→Assets.init({ manifest })ran after anAssets.load, so the manifest was ignored. Callinitonce before any load, or register bundles withAssets.addBundle.Texture.from(url)gives a blank texture → in v8 it only reads theAssetscache.await Assets.load(url)first and use the returned texture.addChildon aSprite,GraphicsorTextlogs a deprecation warning → onlyContainers should hold children in v8. Put the sprite and its children side by side in aContainer.- Right-click opens the browser menu over the game → listen for
contextmenuon the object and callevent.preventDefault()(PixiJS 8.22+); cancellingrightdowndoes not stop the menu. On older 8.x, add a nativecontextmenulistener toapp.canvas. - Pixel art is blurry or shimmers → set
TextureStyle.defaultOptions.scaleMode = 'nearest'before loading (ortexture.source.scaleMode = 'nearest'per texture), and passroundPixels: truetoinit(). - WebGPU-only code fails on some machines →
preferenceis a hint and PixiJS falls back. Branch onapp.renderer.namebefore using backend-specific features. - Memory grows across levels →
removeChildfrees nothing on the GPU.destroy()removed objects andAssets.unload()assets the next screen does not use. - Flicker or corrupt textures after re-creating the app in the same tab → destroy the old
one with
app.destroy({ removeView: true, releaseGlobalResources: true }). - Porting v7 code →
Loader/loader.addbecameAssets.load;new Application({...})became an empty constructor plusawait app.init({...});beginFill()/endFill()became shape-first.rect(...).fill(...);app.viewbecameapp.canvas;interactive = truebecameeventMode = 'static';buttonModebecamecursor = 'pointer';cacheAsBitmapbecamecacheAsTexture(). The oldapp.view, constructor options andinteractivestill work with deprecation warnings.
References
- Read
references/assets-and-display.mdwhen working with sprite sheets and animations, background loading and unloading,Graphics,TextandBitmapText,TilingSprite,ParticleContainer, filters, or teardown and context loss.
Related skills
phaser-core: a full 2D game framework with scenes, physics and input.create-game-assets: making and packing the sprites and atlases PixiJS loads.game-ui-ux: HUD and menu layout rules for thehudlayer.prototype-fast: greyboxing a playable slice.
Version notes
Last verified: 2026-11-11 against pixi.js 8.22.0 (npm latest, released 2026-10-01).
- 8.22 added the federated
contextmenuevent. - The renderer order
["webgl", "webgpu", "canvas"], the deprecation warnings for constructor options,app.viewand leafaddChild, and the cache-onlyTexture.fromwere checked in the 8.22.0 build. - PixiJS's Quick Start still says Vite 6.0.6 and older fail on top-level
awaitin the boot code; on those versions wrap boot in an async function. Current Vite is 8.x. - Sources: v8.22.0 release notes,
PixiJS v8 migration guide,
Quick Start,
npm view pixi.js dist-tags.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |