Skip to main content

v7 Migration Guide

First and foremost, PixiJS v7 is a modernization release that reflects changes in the ecosystem since PixiJS was first published over six years ago. Browsers have gotten better, but PixiJS hasn't really taken advantage of some of the new features like fetch, Workers, modern JavaScript language syntax. This release keeps intact much of the high-level DisplayObjects (e.g., Sprite, Graphics, Mesh, etc). Aside from a few things, this release should be medium to low impact for most users.

👋 Dropping Internet Explorer​

Microsoft officially ended support for IE, so we decided to follow. It simplified many of our modernizations since IE was an outliner from Safari/Chrome/Firefox/Edge and mobile browsers. If you need support for IE, please consider using Babel or some other trans-piling tool.

🗑️ Remove Polyfills​

We removed the bundled polyfills such as requestAnimationFrame and Promise. These things are widely available in browsers now. If projects require them, developers should include the polyfills they need for backward-compatibility.

💬 Output ES2020 (modules) and ES2017 (browser)​

PixiJS historically only published ES5 (no classes!). A new output standard allows us to use ES2017 features that previously we couldn't use (e.g., String.prototype.startsWith, Array.prototype.contains, etc). Not only does it make the code more readable, but the output looks nicer as well. For modules we are outputting ES2020, which contains syntax like nullish coalescing (??). If your project needs to have backward compatibility, you can use Babel to transpile or polyfill.

🐭 Replaces InteractionManager with EventSystem​

InteractionManager was getting complex and difficult to maintain. Few core team members understood the code. We decided to move to FederatedEvents, which is concise, better aligned with the DOM, and supports things like bubbling. The good news, is you shouldn't have to change code, as it is largely a drop-in replacement. We added addEventListener and removeEventListener APIs to DisplayObject which have the same DOM signature and can be used instead of on and off.

📦 Replaces Loader with Assets​

Similarly, we've been wanting to remove the Loader because of its legacy approach (e.g., XMLHttpRequest). This was forked from resource-loader that has been with PixiJS for a long time. The original design inspiration for Loader was driven largely by Flash/AS3, which now seem dated. There were a few things we wanted out of a new iteration: static loading, loading with Workers, background loading, Promise-based, fewer layers of caching. Here's a quick example of how this will change:

import { Loader, Sprite } from 'pixi.js';

const loader = new Loader();
loader.add('background', 'path/to/assets/background.jpg');
loader.load((loader, resources) => {
  const image = Sprite.from(resources.background.texture);
});

Now becomes:

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

const texture = await Assets.load('path/to/assets/background.jpg');
const image = Sprite.from(texture);

🤝 Abandon the use of peerDependencies​

PixiJS heavily uses peerDependencies in the package.json within each package. This design choice has plagued Pixi with many issues. It's a breaking change to remove, so now was a good time. We have decided to completely remove peerDependencies, instead opting for nothing. This should make installing and upgrading pixi.js much easier. We are working on updating our tooling for composing a custom version with packages. Edit: As of 7.2.0, we have reverted this change to keep compatibility with some module-based CDNs.

👂 Other Changes​

  • Browser builds have been removed for all packages, with the exception of pixi.js and pixi.js-legacy.
  • Removes Graphics.nextRoundedRectBehavior this is now the default behavior
  • Removes Text.nextLineHeightBehavior this is now the default behavior
  • AbstractBatchRenderer and BatchPluginFactory has been removed. Either extends BatchRenderer or use setShaderGenerator on the default BatchRenderer, (e.g., renderer.plugins.batch)
  • BatchRenderer is installed by default in @pixi/core, no need to Renderer.registerPlugin('batch', BatchRenderer) anymore

Exports from @pixi/core​

The @pixi/core package now depends and re-exports the following packages.

  • @pixi/math
  • @pixi/contants
  • @pixi/utils
  • @pixi/runner
  • @pixi/settings
  • @pixi/ticker

While some packages will still work when installed directly, others will not, since by installing them alongside @pixi/core you will be effectively importing two copies of the same code.  This will lead to errors where changing settings from @pixi/settings doesn't do anything since @pixi/core has its own version of that package. It is recommended that you uninstall these from your project and use @pixi/core instead.

import { Rectangle } from '@pixi/math';
import { settings } from '@pixi/settings';
import { ALPHA_MODES } from '@pixi/constants';
import { string2hex } from '@pixi/utils';

Now becomes:

import { Rectangle, settings, ALPHA_MODES, utils } from '@pixi/core';

const { string2hex } = utils;

Extract and Prepare Systems​

Extract and prepare plugins have been converted to Renderer "systems".

renderer.plugins.extract
renderer.plugins.prepare

Now becomes:

renderer.extract
renderer.prepare

Extensions Self-Install​

Extensions now install themselves, so you should only need to import the class in order to use. For example, in v6:

import { AccessibilityManager } from '@pixi/accessibility';
import { extensions } from '@pixi/core';
extensions.add(AccessibilityManager);

Now becomes:

import '@pixi/accessibility';

Using hitTest with Events​

With the new events system, one of the common APIs that changed is `hitTest.

import {Application} from 'pixi.js';

const app = new Application();
app.renderer.plugins.interaction.hitTest({x, y});

Now becomes:

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

const app = new Application();
const boundary = new EventBoundary(app.stage);
boundary.hitTest(x, y);

New Async Extract Methods​

The following methods are now async and return a Promise.

  • CanvasExtract.base64()
  • CanvasExtract.image()
  • Extract.base64()
  • Extract.image()
import {Application, EventBoundary} from 'pixi.js';

const app = new Application();
const dataUri = app.renderer.extract.base64();

Now becomes:

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

const app = new Application();
const dataUri = await app.renderer.extract.base64();

Interactive Move Events​

Interaction events in PixiJS now behave like the DOM in v7. This was intentional to align around behavior that would be familiar with developers, but obviously impacts the behavior with pointermove, mousemove, and touchmove.

Like the DOM, move events are now local. This means that if you are outside the bounds of the object, you will not receive a move event. Generally, you should consider adding move events to the stage or parent instead of the DisplayObject itself.

Working example: https://jsfiddle.net/bigtimebuddy/spnv4wm6/

Interactive Property Handlers are Removed​

Property-based handlers were removed from events. This was a feature of the old InteractionManager. For instance:

sprite.pointertap = () => {
 // handler the pointertap
};

Now becomes:

sprite.on('pointertap', () => {
 // handler the pointertap
});

Property buttonMode has been removed​

The property buttonMode was a convenience for toggling the cursor property between pointer and null. It has now been removed.

sprite.buttonMode = true;

Now becomes:

sprite.cursor = 'pointer';

If you would like to re-add this functionality, you can patch DisplayObject's prototype:

import { DisplayObject } from 'pixi.js';

Object.defineProperty(DisplayObject.prototype, 'buttonMode', {
  get() { return this.cursor === 'pointer'; },
  set(value) { this.cursor = value ? 'pointer' : null; },
});

☝️ Suggestions for Upgrading​

If you're planning on transitioning your code from v6, it would be helpful to implement some of the more dramatic changes in v6 first before upgrading to v7:

import { InteractionManager, extensions, Application } from 'pixi.js';
import { EventSystem } from '@pixi/events';

// Uninstall interaction
extensions.remove(InteractionManager);

// Create the renderer or application
const app = new Application();

// Install events
app.renderer.addSystem(EventSystem, 'events');
  • Switch to the Assets package by installing @pixi/assets and swapping for Loader. For more information on implementing Assets, see this guide.
  • Set Graphics.nextRoundedRectBehavior = true, this uses arcs for corner radius instead of bezier curves.
  • Set Text.nextLineHeightBehavior = true, this defaults to the DOM-like behavior for line height.

🏗️ Plugin Supported​

PluginCompatiblePlugin Version Supported
PixiJS Sound✅v5.0.0+
PixiJS HTMLText✅v3.0.0+
PixiJS Filters✅v5.0.0+
PixiJS GIF✅v2.0.0+
PixiJS Spine✅v4.0.0+
PixiJS Particle Emitter✅v5.0.8+
PixiJS Animate❌
PixiJS Layers✅v2.0.0+
PixiJS Lights✅v4.0.0+
PixiJS Graphics Smooth✅v1.0.0+
PixiJS Tilemap❌