pixijs-migration-v8

This skill is a breaking-change checklist for bringing a v7 codebase up to v8. Work top-down through the categories; the list maps each v7 pattern to its v8 replacement.

Quick Start

Install the single package, then port in this order: imports → Application init → Graphics → Text → events → shaders/filters → cleanup.

const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

const g = new Graphics()
  .rect(0, 0, 100, 100)
  .fill({ color: 0xff0000 })
  .stroke({ width: 2, color: 0x000000 });
app.stage.addChild(g);

Related skills:

pixijs-application

(async init),

pixijs-scene-graphics

(new fill/stroke API),

pixijs-custom-rendering

(shader rework),

pixijs-scene-text

(Text constructor changes),

pixijs-performance

(destroy patterns).

Migration Checklist: v7 to v8

Work through each category. Each item shows the expected v8 pattern and the v7 pattern that must be replaced.

Initialization

Async app.init() -- Expected:

const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

Fail: passing options to

new Application({...})

and using synchronously.

app.canvas replaces app.view --

app.view

emits a deprecation warning.

Application type parameter -- Expected:

new Application<Renderer<HTMLCanvasElement>>()

. Fail:

new Application<HTMLCanvasElement>()

Imports

Single package -- Expected:

import { Sprite, Application, Assets, Graphics } from "pixi.js";

Fail: importing from any of the deprecated v7 core

@pixi/*

sub-packages (see list below). Supplemental packages like

@pixi/sound

are still valid and should continue to be used.

Deprecated

@pixi/*

packages (never use, any version):

@pixi/accessibility

@pixi/app

@pixi/assets

@pixi/compressed-textures

@pixi/core

@pixi/display

@pixi/events

@pixi/extensions

@pixi/extract

@pixi/filter-alpha

@pixi/filter-blur

@pixi/filter-color-matrix

@pixi/filter-displacement

@pixi/filter-fxaa

@pixi/filter-noise

@pixi/graphics

@pixi/mesh

@pixi/mesh-extras

@pixi/mixin-cache-as-bitmap

@pixi/mixin-get-child-by-name

@pixi/mixin-get-global-position

@pixi/particle-container

@pixi/prepare

@pixi/sprite

@pixi/sprite-animated

@pixi/sprite-tiling

@pixi/spritesheet

@pixi/text

@pixi/text-bitmap

@pixi/text-html

Custom builds -- Set

skipExtensionImports: true

and import only needed extensions:

import "pixi.js/graphics";
import "pixi.js/text";
import "pixi.js/events";
import { Application } from "pixi.js";
await app.init({ skipExtensionImports: true });

Note:

manageImports: false

is still accepted but

@deprecated since 8.1.6

; prefer

skipExtensionImports: true

Extensions not auto-imported (require explicit import even with default auto-imports enabled):

pixi.js/advanced-blend-modes

pixi.js/unsafe-eval

pixi.js/prepare

pixi.js/math-extras

pixi.js/dds

pixi.js/ktx

pixi.js/ktx2

pixi.js/basis

Community filters -- Expected:

import { AdjustmentFilter } from 'pixi-filters/adjustment'

. Fail:

@pixi/filter-adjustment

Graphics API

Shape-then-fill -- Expected:

const g = new Graphics().rect(50, 50, 100, 100).fill(0xff0000);

Fail:

beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill()

Renamed shape methods:

v7	v8
`drawRect`	`rect`
`drawCircle`	`circle`
`drawEllipse`	`ellipse`
`drawPolygon`	`poly`
`drawRoundedRect`	`roundRect`
`drawStar`	`star`
`drawRegularPolygon`	`regularPoly`
`drawRoundedPolygon`	`roundPoly`
`drawRoundedShape`	`roundShape`
`drawChamferRect`	`chamferRect`
`drawFilletRect`	`filletRect`

Fill replaces beginFill/beginTextureFill -- Expected:

graphics
  .rect(0, 0, 100, 100)
  .fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });

Fail:

beginFill(color, alpha)

beginTextureFill({ texture, alpha, color })

Stroke replaces lineStyle -- Expected:

graphics.rect(0, 0, 100, 100).fill("blue").stroke({ width: 2, color: "white" });

Fail:

lineStyle(2, 'white')

lineTextureStyle({ texture, width, color })

Holes use cut() -- Expected:

graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();

Fail:

beginHole()

endHole()

GraphicsContext replaces GraphicsGeometry -- Expected:

const context = new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000);
const g1 = new Graphics(context);
const g2 = new Graphics(context);

Fail:

new Graphics(graphics.geometry)

Text

Options object constructor -- Expected:

const text = new Text({ text: "Hello", style: { fontSize: 24 } });
const bmp = new BitmapText({ text: "Hello", style: { fontFamily: "MyFont" } });
const html = new HTMLText({ text: "<b>Hello</b>", style: { fontSize: 24 } });

Fail:

new Text('Hello', { fontSize: 24 })

(positional args).

Bitmap font loading -- Must

import 'pixi.js/text-bitmap'

before

Assets.load('font.fnt')

Sprites / Mesh

Texture.from no longer loads URLs -- Must call

await Assets.load('image.png')

first, then

Texture.from('image.png')

NineSliceSprite replaces NineSlicePlane -- Expected:

const ns = new NineSliceSprite({
  texture,
  leftWidth: 10,
  topHeight: 10,
  rightWidth: 10,
  bottomHeight: 10,
});

Mesh renames:

SimpleMesh

MeshSimple

SimplePlane

MeshPlane

SimpleRope

MeshRope

. All use options objects.

MeshGeometry options -- Expected:

const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});

Fail:

new MeshGeometry(vertices, uvs, indices)

ParticleContainer uses Particle -- Expected:

const container = new ParticleContainer({
  boundsArea: new Rectangle(0, 0, 800, 600),
});
const particle = new Particle(texture);
container.addParticle(particle);

Fail:

container.addChild(new Sprite(texture))

Events

eventMode replaces interactive -- Expected:

sprite.eventMode = "static";
sprite.cursor = "pointer";
sprite.on("pointertap", () => {
  /* handle */
});

Legacy:

sprite.interactive = true;

(still works as an alias for

eventMode = 'static'

, but prefer the explicit form).

Default

eventMode

'passive'

(no events). Must set

'static'

'dynamic'

explicitly.

Ticker callback -- Expected:

app.ticker.add((ticker) => {
  bunny.rotation += ticker.deltaTime;
});

Broken:

app.ticker.add((dt) => { bunny.rotation += dt; })

-- compiles but

dt

is a

Ticker

object, not a number. Coerces to

NaN

, silently corrupting rotation.

updateTransform removed -- Use

this.onRender = this._onRender.bind(this)

in constructor instead.

Shaders

Shader.from uses options -- Expected:

const shader = Shader.from({
  gl: { vertex: vertexSrc, fragment: fragmentSrc },
  resources: {
    myUniforms: new UniformGroup({ uTime: { value: 0, type: "f32" } }),
  },
});

Fail:

Shader.from(vertex, fragment, uniforms)

Filter constructor -- Expected:

const filter = new Filter({
  glProgram: GlProgram.from({ fragment, vertex }),
  resources: { filterUniforms: { uTime: { value: 0, type: "f32" } } },
});

Fail:

new Filter(vertex, fragment, { uTime: 0 })

Uniforms require type --

new UniformGroup({ uTime: { value: 1, type: 'f32' } })

. Fail:

new UniformGroup({ uTime: 1 })

Textures are resources, not uniforms -- Pass as top-level resource entries (

texture.source

texture.style

), not inside UniformGroup.

Textures

Sprite no longer auto-detects texture UV changes -- If you modify a texture's frame after creation, call

texture.update()

to recalculate UVs, then call

sprite.onViewUpdate()

to refresh the sprite. Both calls are required in this order. Updating source data (e.g. video textures) is still automatic.

texture.frame.width = texture.frame.width / 2;
texture.update(); // recalculate texture UVs first
sprite.onViewUpdate(); // then refresh the sprite's display

Mipmaps --

BaseTexture.mipmap

renamed to

autoGenerateMipmaps

. For RenderTextures, you must manually update mipmaps:

const rt = RenderTexture.create({
  width: 100,
  height: 100,
  autoGenerateMipmaps: true,
});
renderer.render({ target: rt, container: scene });
rt.source.updateMipmaps();

Adapters

DOMAdapter replaces settings.ADAPTER -- Expected:

import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();

Fail:

settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();

Built-in adapters:

BrowserAdapter

(default),

WebWorkerAdapter

(for web workers).

Other

DisplayObject removed --

Container

is the base class.

class MyObj extends DisplayObject

fails.

Leaf nodes cannot have children --

Sprite

Graphics

Mesh

Text

are leaf nodes. Wrap in

Container

Renamed properties (old names still exist as deprecated aliases with warnings):

```
container.name
```
->
```
container.label
```

container.cacheAsBitmap = true

container.cacheAsTexture(true)

getBounds() return type changed:

getBounds()

now returns a

Bounds

object, not a

Rectangle

Bounds

has

.x

.y

.width

.height

getters, so basic usage works. Use

.rectangle

when you need a

Rectangle

instance (e.g., for

.contains()

settings object removed -- Use

AbstractRenderer.defaultOptions.resolution = 1

and

DOMAdapter.set(BrowserAdapter)

utils namespace removed --

import { isMobile } from 'pixi.js'

instead of

utils.isMobile

Text parser renames:

```
TextFormat
```
->
```
bitmapFontTextParser
```

XMLStringFormat

bitmapFontXMLStringParser

```
XMLFormat
```
->
```
bitmapFontXMLParser
```

Assets.add --

Assets.add({ alias: 'bunny', src: 'bunny.png' })

. Fail:

Assets.add('bunny', 'bunny.png')

Enum constants replaced with strings:

v7	v8
`SCALE_MODES.NEAREST`	`'nearest'`
`SCALE_MODES.LINEAR`	`'linear'`
`WRAP_MODES.CLAMP`	`'clamp-to-edge'`
`WRAP_MODES.REPEAT`	`'repeat'`
`WRAP_MODES.MIRRORED_REPEAT`	`'mirror-repeat'`
`DRAW_MODES.TRIANGLES`	`'triangle-list'`
`DRAW_MODES.TRIANGLE_STRIP`	`'triangle-strip'`
`DRAW_MODES.LINES`	`'line-list'`
`DRAW_MODES.LINE_STRIP`	`'line-strip'`
`DRAW_MODES.POINTS`	`'point-list'`

Culling is manual -- Set

cullable = true

, then call

Culler.shared.cull(container, viewRect)

before render. Or add

CullerPlugin

via

extensions.add(CullerPlugin)

Pre-Migration Summary

No deprecated v7 core
```
@pixi/*
```
packages in dependencies (supplemental packages like
```
@pixi/sound
```
are fine)
All core
```
@pixi/*
```
imports converted to
```
pixi.js
```

All

new Application({...})

converted to

await app.init({...})

All Graphics code uses shape-then-fill pattern
All constructors use options objects (Text, Mesh, NineSliceSprite, etc.)
Shader/Filter code uses
```
{gl, resources}
```
pattern with typed uniforms
ParticleContainer code uses
```
Particle
```
, not
```
Sprite
```
Ticker callbacks access
```
ticker.deltaTime
```
, not first param as delta
Event handling uses
```
eventMode
```
instead of
```
interactive
```
```
settings
```
and
```
utils
```
references removed
```
DisplayObject
```
references replaced with
```
Container
```
Texture UV modifications call
```
sprite.onViewUpdate()
```
where needed
RenderTexture mipmap code calls
```
source.updateMipmaps()
```
manually
```
settings.ADAPTER
```
replaced with
```
DOMAdapter.set()
```

Common Mistakes

[CRITICAL] Importing from deprecated v7 core @pixi/* sub-packages

Wrong:

import { Sprite } from "@pixi/sprite";
import { Application } from "@pixi/app";

Correct:

import { Sprite, Application } from "pixi.js";

v8 uses a single

pixi.js

package. The v7 core

@pixi/*

sub-packages are deprecated and must not be used (see the full list under Imports above). Supplemental packages like

@pixi/sound

are still valid.

[CRITICAL] Using DisplayObject as base class

Wrong:

class MyObject extends DisplayObject { ... }

Correct:

class MyObject extends Container { ... }

DisplayObject

was removed in v8.

Container

is the base class for all display objects.

[HIGH] Using old SCALE_MODES/WRAP_MODES/DRAW_MODES enums

Wrong:

texture.source.scaleMode = SCALE_MODES.NEAREST;

Correct:

texture.source.scaleMode = 'nearest';

v8 uses string values. Old enums may work as deprecated aliases but should be replaced.

[HIGH] Using

interactive = true

instead of

eventMode

Legacy:

sprite.interactive = true;

(still works as an alias for

eventMode = 'static'

) Preferred:

sprite.eventMode = 'static';

Default

eventMode

'passive'

(no events). Must set

'static'

(hit-testable, no tick checks) or

'dynamic'

(hit-testable with tick checks) explicitly.

interactive = true

still works without a deprecation warning, but

eventMode

is the canonical v8 API.

[HIGH] Using utils namespace

Wrong:

import { utils } from 'pixi.js'; utils.isMobile.any();

Correct:

import { isMobile } from 'pixi.js'; isMobile.any();

The

utils

namespace was removed. All utility functions are direct imports.

[HIGH] Expecting texture UV changes to auto-update sprites

Wrong: modifying

texture.frame

and assuming the sprite updates automatically. Correct: call

sprite.onViewUpdate()

after modifying texture UVs.

Sprites no longer subscribe to texture UV change events for performance. Source data updates (e.g. video) still auto-reflect.

pixijs-migration-v8

NPX Install

Tags

SKILL.md Content

Quick Start

Migration Checklist: v7 to v8

Initialization

Imports

Graphics API

Text

Sprites / Mesh

Events

Shaders

Textures

Adapters

Other

Pre-Migration Summary

Common Mistakes

[CRITICAL] Importing from deprecated v7 core @pixi/* sub-packages

[CRITICAL] Using DisplayObject as base class

[HIGH] Using old SCALE_MODES/WRAP_MODES/DRAW_MODES enums

[HIGH] Using
`interactive = true`
instead of
`eventMode`

[HIGH] Using utils namespace

[HIGH] Expecting texture UV changes to auto-update sprites

API Reference