pixijs-rendering

# PixiJS v8 assets & display objects

Depth on the v8 asset pipeline and the display-object types beyond `Sprite`. The
`SKILL.md` covers the boot path and scene graph; this file fills in textures and
the other things you draw.

## The `Assets` system (v8)

`Assets` replaces the v7 `Loader`. It caches by URL/alias, so calling
`Assets.load` twice for the same source resolves immediately the second time.

```js
import { Assets } from 'pixi.js';

// Single asset.
const tex = await Assets.load('assets/hero.png');

// Register aliases up front, load later by name.
Assets.add({ alias: 'hero', src: 'assets/hero.png' });
const hero = await Assets.load('hero');

// Load several at once (object form keeps results keyed).
const sheet = await Assets.load([ 'a.png', 'b.png' ]);

// Background-load without blocking, then `load` resolves instantly when needed.
Assets.backgroundLoad(['level-2-bg.png']);

// Free GPU + CPU memory when a screen is done.
await Assets.unload('hero');
```

Supported source types include images, sprite-sheet JSON (atlases), bitmap fonts,
web fonts, and audio (with the right loader installed). Atlases load as a
`Spritesheet`; access frames by name:

```js
const sheet = await Assets.load('assets/characters.json'); // TexturePacker JSON
const idle = new Sprite(sheet.textures['hero_idle.png']);
const runFrames = sheet.animations['hero_run'];            // Texture[] for animation
```

## Texture settings

```js
import { Texture } from 'pixi.js';

texture.source.scaleMode = 'nearest';  // crisp pixel art ('linear' is the default)
const sub = new Texture({ source: texture.source, frame: new Rectangle(0, 0, 16, 16) });
```

`Texture` is a view into a `TextureSource` (the GPU resource). Many `Texture`s can
share one source — that's how atlases avoid extra uploads.

`Texture.from(id)` only reads the Assets cache in v8; it does not fetch a URL. Call
`await Assets.load(url)` first (use its return value), or `Texture.from` a source
that is already loaded.

## Display object types

### AnimatedSprite

```js
import { AnimatedSprite } from 'pixi.js';
const anim = new AnimatedSprite(sheet.animations['hero_run']);
anim.animationSpeed = 0.2;   // fraction of a frame per ticker tick
anim.play();
app.stage.addChild(anim);
```

### Graphics (vector drawing)

v8 uses a fluent, retained API: define the shape, then call a fill/stroke.

```js
import { Graphics } from 'pixi.js';
const g = new Graphics()
  .roundRect(0, 0, 120, 60, 12)
  .fill(0x4488ff)
  .stroke({ width: 2, color: 0xffffff });
app.stage.addChild(g);
```

(In v7 the order was `beginFill` → draw → `endFill`; v8 draws the shape first, then
fills/strokes it.)

### Text & BitmapText

```js
import { Text, TextStyle } from 'pixi.js';
const score = new Text({
  text: 'Score: 0',
  style: new TextStyle({ fontFamily: 'Arial', fontSize: 24, fill: '#ffffff' }),
});
```

Use `BitmapText` for frequently changing strings (HUD counters): it re-uses glyph
textures instead of rasterising new ones each change.

### TilingSprite (scrolling backgrounds)

```js
import { TilingSprite } from 'pixi.js';
const bg = new TilingSprite({ texture: skyTexture, width: app.screen.width, height: app.screen.height });
app.ticker.add((t) => { bg.tilePosition.x -= 0.5 * t.deltaTime; });
```

### ParticleContainer (many simple sprites)

For thousands of cheap, same-texture sprites (bullets, particles), a
`ParticleContainer` trades per-child features for throughput. In v8 it holds
`Particle` instances added with `addParticle` (not `Sprite`s via `addChild`), and
you declare which per-particle fields change at runtime via `dynamicProperties` so
only those are re-uploaded each frame:

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

const container = new ParticleContainer({
  // Static fields are uploaded once; mark only what actually changes as dynamic.
  dynamicProperties: { position: true, rotation: true, color: false },
  // It does not measure its particles: give it bounds by hand (see below).
  boundsArea: new Rectangle(0, 0, app.screen.width, app.screen.height),
});
app.stage.addChild(container);

const p = new Particle(bulletTexture);
p.x = 100; p.y = 50;
container.addParticle(p);   // NOT container.addChild(new Sprite(...))
```

Particles are lightweight records, not full display objects: no children, no
per-particle events, no filters. Keep every particle on one shared texture (an
atlas frame) so the batch never breaks.

A `ParticleContainer` reports empty bounds (0, 0, 0, 0) to save work. Without a
`boundsArea`, `getBounds()` is empty and the container vanishes once it is
`cullable`; set `boundsArea` to the region the particles cover. Its own hit test
also reads those empty bounds, so to make the container clickable give it a
`hitArea` (for example the same `Rectangle`).

## Filters

Filters are GPU post-process effects applied to a display object and its children:

```js
import { BlurFilter } from 'pixi.js';
container.filters = [new BlurFilter({ strength: 4 })];
```

Filters render the subtree to a temporary texture, so they cost memory and fill
rate — apply sparingly and remove (`obj.filters = null`) when not needed.

## Cleanup

- `removeChild(child)` detaches but does **not** free GPU memory.
- `child.destroy()` frees the display object; pass options to also destroy its
  texture: `sprite.destroy({ texture: true, textureSource: true })`.
- Destroy a whole subtree with `container.destroy({ children: true })`. If a
  container has `cacheAsTexture(true)` on it, turn it off with
  `cacheAsTexture(false)` before destroying. (`cacheAsBitmap` from v7 is renamed to
  the `cacheAsTexture()` method.)
- `Assets.unload(urlOrAlias)` frees a loaded asset's GPU/CPU memory.
- Tearing down the whole app to re-create it in the same tab: use
  `app.destroy({ removeView: true, releaseGlobalResources: true })`. Without
  `releaseGlobalResources`, pooled batches/textures survive and corrupt the next app.
- On WebGL/WebGPU context loss, textures are restored from their sources; keep the
  source (or be ready to reload) for anything generated at runtime.

---
name: pixijs-rendering
description: >
  Build a PixiJS v8 render layer: create the async Application, load textures with
  Assets, compose the scene graph with Container and Sprite, drive the ticker loop,
  wire pointer events, and group draws with render groups. Use when building or
  debugging PixiJS v8 — when the user mentions PixiJS, Pixi, Application, app.stage,
  Container, Sprite, Assets.load, app.ticker, or eventMode. Pins the v8 async
  init() API (examples checked against 8.22).
---

# PixiJS 8.22 Rendering

Set up and structure a PixiJS **8.22** application: the async `Application`, asset
loading via `Assets`, the `Container`/`Sprite` scene graph, the ticker loop,
pointer events, and render groups. Pins the 8.22 API (async `init`, unified
`Assets`, `eventMode`).

## When to use

- Use when starting a PixiJS v8 project, fixing a blank canvas, structuring the
  display list, loading textures, animating via the ticker, or handling pointer
  input.
- Use when `package.json` depends on `pixi.js` (v8) and code does
  `import { Application } from 'pixi.js'`.

**When *not* to use:** Phaser's scene/loader model → `phaser-core`. 3D scenes →
`threejs-scene-setup`. PixiJS v7-and-earlier code (synchronous `new
Application({...})`, `Loader`, `beginFill`/`endFill`) needs the v8 migration first;
this skill targets v8 only. (`interactive = true` still works in v8 as an alias for
`eventMode = 'static'`, but prefer the explicit `eventMode`.)

## Core workflow

1. **Create and `await` the Application.** In v8, `new Application()` is empty;
   configuration happens in `await app.init({...})`. Append `app.canvas` (not
   `app.view`) to the DOM. Wrap top-level `await` in an async function for bundlers.
2. **Load assets with `Assets`.** `await Assets.load(url)` returns a `Texture`. For
   many assets, register a manifest/bundle and load by name. There is no v7 `Loader`.
3. **Build the scene graph.** Everything descends from `app.stage` (a `Container`).
   Group related objects in `Container`s; child transforms are relative to the
   parent. Draw order = insertion order (later = on top).
4. **Animate with the ticker.** `app.ticker.add((ticker) => {...})`. Scale motion by
   `ticker.deltaTime` (frames, ~1 at 60fps) or `ticker.deltaMS` (milliseconds) so
   speed is frame-rate independent.
5. **Enable events per object** by setting `eventMode = 'static'` (or `'dynamic'`),
   then `obj.on('pointerdown', ...)`. Federated pointer events cover mouse/touch/pen.
6. **Promote big static subtrees to render groups** (`isRenderGroup: true`) so the
   GPU caches their transforms. Profile before and after; confirm pixels on screen.

## Patterns

### 1. Async Application boot (the v8 entry point)

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

(async () => {
  // v8: construct empty, then await init(). Config does NOT go in the constructor.
  const app = new Application();
  await app.init({
    background: '#1099bb',
    resizeTo: window,        // track the window size
    antialias: true,
    // preference: 'webgpu',  // hint only; default order tries 'webgl' first.
    //                        // Pixi falls back if the backend is unavailable —
    //                        // branch on app.renderer.name, don't assume it took.
  });

  document.body.appendChild(app.canvas); // v8 uses app.canvas, not app.view

  const texture = await Assets.load('https://pixijs.com/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. Containers for a relative-transform scene graph

```js
import { Container, Sprite } from 'pixi.js';

const world = new Container();
app.stage.addChild(world);

// Children are positioned relative to `world`; move/scale/rotate the whole group
// by transforming the parent.
for (let i = 0; i < 10; i++) {
  const coin = new Sprite(coinTexture);
  coin.x = i * 40;
  world.addChild(coin);
}
world.position.set(100, 100);
world.scale.set(2);            // every coin scales with the container
```

### 3. The ticker loop (frame-rate independent)

```js
let elapsed = 0;
app.ticker.add((ticker) => {
  // deltaTime ≈ 1 at 60fps; deltaMS is milliseconds since last frame.
  elapsed += ticker.deltaMS;
  bunny.rotation += 0.05 * ticker.deltaTime;          // smooth at any frame rate
  bunny.y = app.screen.height / 2 + Math.sin(elapsed / 500) * 50;
});
```

### 4. Pointer events (federated)

```js
bunny.eventMode = 'static';   // 'static' = interactive, doesn't move on its own
bunny.cursor = 'pointer';     // hover cursor; `buttonMode` was removed in v8
bunny.on('pointerdown', (event) => {
  bunny.tint = 0xff0000;
  // event.global is the pointer position in stage space.
});
bunny.on('pointerover', () => bunny.scale.set(1.1));
bunny.on('pointerout',  () => bunny.scale.set(1.0));
```

Dragging needs `globalpointermove`, not `pointermove`. In v8 `pointermove` fires
**only while the pointer is over the object**, so a drag that follows the cursor
past the object's edge stops updating. `globalpointermove` fires on every move:

```js
let dragging = false;
bunny.on('pointerdown', () => { dragging = true; });
bunny.on('pointerup', () => { dragging = false; });
bunny.on('pointerupoutside', () => { dragging = false; }); // release off the object
bunny.on('globalpointermove', (event) => {
  if (dragging) bunny.position.copyFrom(event.global);
});
```

### 5. Loading many assets by name (bundles)

```js
import { Assets } from 'pixi.js';

await Assets.init({
  manifest: {
    bundles: [{
      name: 'level-1',
      assets: [
        { alias: 'hero',  src: 'assets/hero.png' },
        { alias: 'tiles', src: 'assets/tiles.png' },
      ],
    }],
  },
});

const bundle = await Assets.loadBundle('level-1'); // { hero: Texture, tiles: Texture }
const hero = new Sprite(bundle.hero);
```

### 6. Render groups for large static layers

```js
// A big, rarely-changing background subtree: let the GPU cache its transforms.
const background = new Container({ isRenderGroup: true });
app.stage.addChild(background);
// Add hundreds of static tiles to `background`. Moving `background` itself stays
// cheap; constantly re-adding/removing children negates the benefit.
```

## Pitfalls

- **Blank canvas, or `TypeError` reading `canvas`/`screen` of undefined** → you didn't
  `await app.init()`, or you configured the constructor. In v8 the constructor is
  empty; all options go to `init()`. `app.stage` exists right away, but
  `app.renderer` is `undefined` until the `init()` promise resolves, so `app.canvas`
  and `app.screen` throw before then.
- **`app.view` logs a deprecation warning** → v8 renamed it to `app.canvas`; the old
  getter still returns the canvas for now.
- **Porting v7 code** → `Loader`/`loader.add` → `Assets.load` (the `Loader` class is
  gone); synchronous `new Application({...})` → empty constructor + async `init()`
  (options in the constructor are ignored with a deprecation warning, not an error);
  `beginFill()`/`endFill()` → shape-first `.rect(...).fill(...)`. `interactive = true`
  and `app.view` still work as deprecated aliases.
- **Ticker callback arg is the Ticker, not a delta number** → `app.ticker.add((dt) =>
  { obj.rotation += dt; })` compiles, but `dt` is the whole `Ticker` object, so the
  math yields `NaN` and nothing animates. Read `ticker.deltaTime` off the argument.
- **Top-level await build error (Vite ≤6.0.6)** → wrap boot in `(async () => { ... })()`.
- **Speed varies with frame rate** → multiply movement by `ticker.deltaTime` (~1 at
  60fps) or scale by `ticker.deltaMS`; never assume 60fps. `deltaTime` is a
  dimensionless multiplier, not milliseconds.
- **Clicks do nothing** → the object's `eventMode` is still `'passive'` (the v8
  default: self not interactive, children still are); set it to `'static'` (or
  `'dynamic'` for objects that move under a stationary cursor).
- **Drag stops at the object's edge** → `pointermove` fires only while the pointer is
  over the object in v8; use `globalpointermove` for drag/global tracking.
- **Right-click opens the browser menu over the game** → PixiJS does not block it.
  From 8.22, listen for `contextmenu` on the object and call
  `event.preventDefault()`; cancelling `rightdown`/`rightclick` does not stop the menu.
  On older 8.x, add a native `contextmenu` listener to `app.canvas` instead.
- **`addChild` on a `Sprite`/`Graphics`/`Text` logs a deprecation warning** → in v8
  only `Container`s should hold children; put the sprite and its children side by side
  in a `Container`.
- **`Texture.from(url)` returns a blank/undefined texture** → in v8 it only reads the
  Assets cache; `await Assets.load(url)` first, then use the returned `Texture`.
- **WebGPU features error out** → `preference` is a hint. If the backend is
  unavailable Pixi falls back (WebGL, then Canvas); branch on `app.renderer.name`
  before using backend-specific code.
- **Textures look blurry on pixel art** → set
  `texture.source.scaleMode = 'nearest'` (or pass it when loading).
- **Memory grows** → `removeChild` does not free GPU memory; call
  `sprite.destroy()` and `Assets.unload(url)` for assets you're done with.
- **Flicker/corruption after tearing down and re-creating an app in the same tab** →
  destroy with `app.destroy({ releaseGlobalResources: true })`; otherwise pooled
  batches/textures from the old app leak into the new one.

## References

- For the texture/asset pipeline (sprite sheets/atlases, `Assets.add`, background
  loading, unloading) and Graphics/Text/`TilingSprite`/`ParticleContainer` plus
  filters, read `references/assets-and-display.md`.

## Related skills

- `phaser-core` — a batteries-included 2D framework (scenes, physics, input).
- `threejs-scene-setup` — 3D in the browser with three.js.
- `prototype-fast` — greybox a playable slice quickly (often cites PixiJS).