Skip to content

v7 Migration Guide

Matt Karl edited this page Sep 27, 2022 · 18 revisions

Overview

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. Please check out polyfill.io.

💬 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.

👂 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 exports the following packages.

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

While it should still work to use these packages directly, it's recommended that you 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';

☝️ 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