pixijs

PixiJS 8.x -- HTML5 Game Development

Build high-performance 2D browser games with PixiJS 8.x (WebGL2 / WebGPU).

References

Read these on demand -- not upfront:

File	When to read
references/game-architecture.md	Scene managers, state machines, ECS-lite patterns, save/load
references/ecosystem.md	Detailed setup for each ecosystem library
references/performance.md	Deep optimization: batching, masks, filters, memory, mobile
references/api-patterns.md	Full API: shapes, text, assets, filters, interaction, Spine
references/migration-v8.md	v7-to-v8 breaking changes table

---

Game Project Setup

npm create pixi.js@latest            # scaffold (recommended)
# -- or existing project --
npm install pixi.js
npm install @pixi/sound               # audio

Bundler: Use Vite. Wrap bootstrap in an async function (avoid bare top-level await with Vite <= 6.0.6).

---

Game Bootstrap

import { Application, Assets } from 'pixi.js';

async function startGame() {
  const app = new Application();
  await app.init({
    width: 960,
    height: 540,
    backgroundColor: 0x1a1a2e,
    antialias: true,
  });
  document.getElementById('game-container').appendChild(app.canvas);

  // ---- Asset manifest with bundles ----
  await Assets.init({
    basePath: '/assets/',
    manifest: {
      bundles: [
        {
          name: 'preload',
          assets: [
            { alias: 'loading-bar', src: 'ui/loading-bar.png' },
          ],
        },
        {
          name: 'game',
          assets: [
            { alias: 'hero-sheet', src: 'sprites/hero.json' },
            { alias: 'tileset', src: 'maps/tileset.json' },
            { alias: 'bgm', src: 'audio/bgm.mp3' },
          ],
        },
      ],
    },
  });

  await Assets.loadBundle('preload');
  Assets.backgroundLoadBundle('game');

  // ---- Responsive canvas ----
  function resize() {
    const parent = app.canvas.parentElement;
    if (!parent) return;
    app.renderer.resize(parent.clientWidth, parent.clientHeight);
  }
  window.addEventListener('resize', resize);
  resize();

  // ---- Start game loop ----
  const game = new Game(app);
  app.ticker.add((ticker) => game.update(ticker.deltaTime));
}

startGame();

---

Core Game Architecture

Scene Management

Scenes are Containers swapped on/off the stage. A minimal SceneManager:

import { Container } from 'pixi.js';

class SceneManager {
  constructor(app) {
    this.app = app;
    this.currentScene = null;
  }

  async switchTo(SceneClass, data) {
    if (this.currentScene) {
      this.currentScene.onExit?.();
      this.app.stage.removeChild(this.currentScene);
      this.currentScene.destroy({ children: true });
    }
    this.currentScene = new SceneClass(this.app, this);
    this.app.stage.addChild(this.currentScene);
    await this.currentScene.onEnter?.(data);
  }
}

// Base scene pattern
class GameScene extends Container {
  constructor(app, scenes) {
    super();
    this.app = app;
    this.scenes = scenes;
  }
  async onEnter(data) { /* load assets, build UI */ }
  update(dt) { /* per-frame logic */ }
  onExit() { /* cleanup */ }
}

See references/game-architecture.md for state machines, ECS-lite, and save/load patterns.

Input System

Track keyboard state for continuous movement (not just events):

class Keyboard {
  constructor() {
    this.keys = new Set();
    window.addEventListener('keydown', (e) => this.keys.add(e.code));
    window.addEventListener('keyup', (e) => this.keys.delete(e.code));
  }
  isDown(code) { return this.keys.has(code); }
  destroy() {
    window.removeEventListener('keydown', this._onDown);
    window.removeEventListener('keyup', this._onUp);
  }
}

// Usage in update loop
if (keyboard.isDown('ArrowRight')) player.x += speed * dt;

For pointer/touch input, use PixiJS events on the stage:

app.stage.eventMode = 'static';
app.stage.hitArea = app.screen;
app.stage.on('pointermove', (e) => {
  crosshair.position.copyFrom(e.global);
});

Game Loop: Fixed Timestep

Use fixed timestep for deterministic physics, variable for rendering:

class Game {
  constructor(app) {
    this.app = app;
    this.fixedStep = 1 / 60;   // 60 Hz physics
    this.accumulator = 0;
  }

  update(dt) {
    const deltaSec = dt / 60;  // ticker.deltaTime is frame-based, convert to seconds
    this.accumulator += deltaSec;

    while (this.accumulator >= this.fixedStep) {
      this.fixedUpdate(this.fixedStep);
      this.accumulator -= this.fixedStep;
    }

    this.render(this.accumulator / this.fixedStep); // interpolation alpha
  }

  fixedUpdate(step) { /* physics, collision */ }
  render(alpha) { /* visual interpolation, particles, animations */ }
}

---

Game Objects

Sprites and Animated Sprites

import { Sprite, AnimatedSprite, Assets } from 'pixi.js';

// Static sprite
const texture = Assets.get('hero-sheet');
const hero = new Sprite(texture);
hero.anchor.set(0.5);

// Animated sprite from spritesheet
const sheet = Assets.get('hero-sheet');
const walkFrames = Object.keys(sheet.textures)
  .filter((k) => k.startsWith('walk_'))
  .map((k) => sheet.textures[k]);

const animHero = new AnimatedSprite(walkFrames);
animHero.anchor.set(0.5);
animHero.animationSpeed = 0.15;
animHero.play();

BitmapText for HUD

Use BitmapText for scores, timers, and any text that updates every frame:

import { BitmapText, BitmapFont } from 'pixi.js';

BitmapFont.install({ name: 'GameFont', style: { fontSize: 32, fill: 0xffffff } });

const scoreText = new BitmapText({
  text: 'Score: 0',
  style: { fontFamily: 'GameFont', fontSize: 32 },
});
scoreText.position.set(16, 16);

// Update cheaply every frame
scoreText.text = `Score: ${score}`;

Object Pooling

Reuse objects instead of create/destroy (bullets, particles, enemies):

class Pool {
  constructor(factory, reset) {
    this.factory = factory;
    this.reset = reset;
    this.available = [];
  }

  get() {
    const obj = this.available.length > 0
      ? this.available.pop()
      : this.factory();
    this.reset(obj);
    return obj;
  }

  release(obj) {
    obj.visible = false;
    this.available.push(obj);
  }
}

// Example: bullet pool
const bulletPool = new Pool(
  () => { const s = new Sprite(bulletTex); s.anchor.set(0.5); return s; },
  (s) => { s.visible = true; s.alpha = 1; },
);

---

Game World

Camera (Scrolling World)

Manual camera -- move a world container opposite to the target:

const world = new Container({ isRenderGroup: true });
app.stage.addChild(world);

function updateCamera(target, screen) {
  world.x = -target.x + screen.width / 2;
  world.y = -target.y + screen.height / 2;
}

For zoom, bounds clamping, and inertia, use pixi-viewport:

import { Viewport } from 'pixi-viewport';

const viewport = new Viewport({
  screenWidth: app.screen.width,
  screenHeight: app.screen.height,
  worldWidth: 3000,
  worldHeight: 3000,
  events: app.renderer.events,
});
app.stage.addChild(viewport);
viewport.drag().pinch().wheel().decelerate();
viewport.follow(player, { speed: 10 });

Collision Detection

AABB (axis-aligned bounding box):

function aabb(a, b) {
  return (
    a.x < b.x + b.width &&
    a.x + a.width > b.x &&
    a.y < b.y + b.height &&
    a.y + a.height > b.y
  );
}

Circle collision:

function circleHit(a, b) {
  const dx = a.x - b.x;
  const dy = a.y - b.y;
  const dist = a.radius + b.radius;
  return dx * dx + dy * dy < dist * dist;
}

For complex physics (rigid bodies, joints, platformers), integrate Matter.js -- see references/ecosystem.md.

Tilemaps

Use @pixi/tilemap for efficient grid-based maps:

import { CompositeTilemap } from '@pixi/tilemap';

const tilemap = new CompositeTilemap();
for (let y = 0; y < mapHeight; y++) {
  for (let x = 0; x < mapWidth; x++) {
    const tileId = mapData[y][x];
    tilemap.tile(tileTextures[tileId], x * tileSize, y * tileSize);
  }
}
world.addChild(tilemap);

---

Ecosystem Libraries

Package	Version (v8-compat)	Purpose
@pixi/sound	^6.x	Audio playback, sprites, filters
pixi-viewport	^5.x	Camera: pan, zoom, follow, cull
@pixi/tilemap	^4.x	Fast tilemap rendering
@pixi/ui	^2.x	Buttons, sliders, scroll, list
@pixi/particle-emitter	^5.x	Configurable particle systems
matter-js	^0.20	2D physics engine
@esotericsoftware/spine-pixi-v8	^4.2	Spine skeletal animation
pixi-filters	^6.x	40+ post-processing filters

Install only what you need. See references/ecosystem.md for integration patterns.

---

Performance Essentials

Draw call budget: aim for < 100 on mobile, < 300 on desktop.

Technique	When to use
Sprite sheets / atlases	Always -- consolidate into few textures
Object pooling	Any object created/destroyed frequently (bullets, particles, pickups)
isRenderGroup: true	Separate game layers (world, HUD, particles)
ParticleContainer	Mass identical sprites (rain, stars, bullets) -- only accepts Particle objects in v8
BitmapText over Text	Any text that updates per frame
cacheAsTexture()	Complex static sub-trees that rarely change
Reduce filter count	Each filter = extra render pass

Mobile-specific:

• Disable antialiasing: antialias: false
• Set backgroundAlpha: 1 (avoids compositing cost)
• Use @0.5x resolution textures
• Cap resolution: resolution: Math.min(window.devicePixelRatio, 2)
• Minimize filters and blend mode switches

See references/performance.md for full optimization guide.

---

v8 Gotchas Checklist

Common mistakes when writing PixiJS 8.x game code:

• Forgot async init: new Application() then await app.init({...}) -- constructor alone does nothing
• Used app.view: renamed to app.canvas
• Used container.name: renamed to container.label
• Used Texture.from(url): must await Assets.load(url) first -- no lazy loading in v8
• Used cacheAsBitmap = true: replaced by cacheAsTexture() method
• Used updateTransform(): replaced by onRender() callback
• Added children to Sprite: only Container can have children in v8
• Ticker callback expects raw delta: callback receives Ticker instance -- use ticker.deltaTime
• Used beginFill/endFill: Graphics uses chainable .rect().fill() API
• Used positional constructor args: most classes take config objects -- new BlurFilter({ strength: 8 })
• Forgot eventMode = 'static': default is 'passive' (no events) -- must opt in
• ParticleContainer with Sprites: v8 only accepts Particle objects, not Sprite
• Used getBounds() as Rectangle: returns Bounds object -- access .rectangle for the rect
• Imported from sub-packages: use import { ... } from 'pixi.js' -- single entry point
• Used PIXI.settings: removed -- use AbstractRenderer.defaultOptions