v7 マイグレーションガイド

まず第一に、PixiJS v7 は、PixiJS が 6 年以上前に初めて公開されてからのエコシステムの変更を反映した現代化リリースです。ブラウザは改善されましたが、PixiJS は fetch、Workers、最新の JavaScript 言語構文などの新機能を利用していませんでした。このリリースでは、ほとんどの高レベルの DisplayObject（Sprite、Graphics、Mesh など）はそのまま維持されています。いくつかの点を除けば、このリリースはほとんどのユーザーにとって中程度から低程度の影響になるはずです。

👋 Internet Explorer のサポート終了

マイクロソフトは IE のサポートを公式に終了したので、私たちもそれに従うことにしました。IE は Safari/Chrome/Firefox/Edge およびモバイルブラウザからの外れ値だったため、多くの現代化が簡素化されました。IE のサポートが必要な場合は、Babel またはその他のトランスパイルツールを使用することを検討してください。

🗑️ ポリフィルの削除

requestAnimationFrame や Promise などのバンドルされたポリフィルを削除しました。これらのものは現在ブラウザで広く利用可能です。プロジェクトでそれらが必要な場合は、開発者は後方互換性のために必要なポリフィルを含める必要があります。

💬 ES2020（モジュール）と ES2017（ブラウザ）を出力

PixiJS は歴史的に ES5（クラスなし！）のみを公開していました。新しい出力標準により、以前は使用できなかった ES2017 の機能（String.prototype.startsWith、Array.prototype.containsなど）を使用できます。コードが読みやすくなるだけでなく、出力も見栄えが良くなります。モジュールについては、nullish coalescing（??）のような構文を含む ES2020 を出力しています。プロジェクトで後方互換性が必要な場合は、Babel を使用してトランスパイルまたはポリフィルできます。

🐭 InteractionManager を EventSystem に置き換え

InteractionManager は複雑になり、保守が困難になっていました。コードを理解しているコアチームメンバーはほとんどいませんでした。そこで、簡潔で DOM により適合し、バブリングなどをサポートする FederatedEvents に移行することにしました。幸いなことに、ほぼドロップイン置換なので、コードを変更する必要はないはずです。DOM と同じシグネチャを持ち、on および off の代わりに使用できる addEventListener および removeEventListener API を DisplayObject に追加しました。

📦 Loader を Assets に置き換え

同様に、Loader はレガシーなアプローチ（例：XMLHttpRequest）のため、削除したいと考えていました。これは、PixiJS で長い間使用されてきたresource-loader からフォークされました。Loader の元の設計のインスピレーションは、主に Flash/AS3 によって推進されましたが、現在では時代遅れに見えます。新しいイテレーションで求めていたものがいくつかありました。静的ロード、ワーカーを使用したロード、バックグラウンドロード、Promise ベース、キャッシュのレイヤーの削減。これがどのように変化するかの簡単な例を次に示します。

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);
});

現在、次のようになります。

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

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

🤝 peerDependencies の使用を放棄

PixiJS は、各パッケージ内の package.json で peerDependencies を多用しています。この設計上の選択は、Pixi に多くの問題をもたらしました。削除するのは破壊的な変更なので、今が良い時期でした。peerDependencies を完全に削除し、代わりに何もしないことを選択しました。これにより、pixi.js のインストールとアップグレードがはるかに簡単になるはずです。カスタムバージョンをパッケージで構成するためのツールの更新に取り組んでいます。 編集：7.2.0 以降、一部のモジュールベースの CDN との互換性を維持するために、この変更を元に戻しました。

👂 その他の変更点

• pixi.js と pixi.js-legacy を除くすべてのパッケージで、ブラウザビルドが削除されました。
• Graphics.nextRoundedRectBehavior を削除しました。これはデフォルトの動作になりました
• Text.nextLineHeightBehavior を削除しました。これはデフォルトの動作になりました
• AbstractBatchRenderer および BatchPluginFactory が削除されました。BatchRenderer を拡張するか、デフォルトの BatchRenderer で setShaderGenerator を使用します（例：renderer.plugins.batch）
• BatchRenderer はデフォルトで @pixi/core にインストールされます。Renderer.registerPlugin('batch', BatchRenderer) は不要になりました

@pixi/core からのエクスポート

@pixi/core パッケージは、次のパッケージに依存し、再エクスポートするようになりました。

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

一部のパッケージは直接インストールした場合でも引き続き機能しますが、@pixi/core と並行してインストールすると、事実上同じコードの 2 つのコピーをインポートすることになるため、機能しないものもあります。 これにより、@pixi/settings の設定を変更しても、@pixi/core に独自のバージョンのパッケージがあるため、何も効果がないというエラーが発生します。プロジェクトからこれらをアンインストールし、代わりに @pixi/core を使用することをお勧めします。

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

現在、次のようになります。

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

const { string2hex } = utils;

抽出および準備システム

抽出および準備プラグインが Renderer 「システム」に変換されました。

renderer.plugins.extract
renderer.plugins.prepare

現在、次のようになります。

renderer.extract
renderer.prepare

拡張機能の自己インストール

拡張機能が自動的にインストールされるようになったため、使用するにはクラスをインポートするだけで済みます。たとえば、v6 では次のようになります。

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

現在、次のようになります。

import '@pixi/accessibility';

イベントでの hitTest の使用

新しいイベントシステムでは、変更された一般的な API の 1 つが `hitTest` です。

import {Application} from 'pixi.js';

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

現在、次のようになります。

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

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

新しい非同期抽出メソッド

次のメソッドが非同期になり、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();

現在、次のようになります。

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

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

インタラクティブな移動イベント

PixiJS のインタラクションイベントは、v7 では DOM のように動作するようになりました。これは、開発者にとって馴染みのある動作を中心に調整するために意図的なものでしたが、pointermove、mousemove、および touchmove を使用した動作に影響を与えることは明らかです。

DOM のように、移動イベントは ローカル になりました。つまり、オブジェクトの境界外にいる場合、移動イベントは受信されません。一般に、移動イベントは DisplayObject 自体ではなく、ステージまたは親に追加することを検討する必要があります。

動作例：https://jsfiddle.net/bigtimebuddy/spnv4wm6/

インタラクティブなプロパティハンドラーが削除されました

プロパティベースのハンドラーがイベントから削除されました。これは古い InteractionManager の機能でした。例えば

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

現在、次のようになります。

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

プロパティ buttonMode が削除されました

プロパティ buttonMode は、cursor プロパティを pointer と null の間で切り替えるための便利な機能でした。これは削除されました。

sprite.buttonMode = true;

現在、次のようになります。

sprite.cursor = 'pointer';

この機能を再度追加する場合は、DisplayObject のプロトタイプをパッチできます。

import { DisplayObject } from 'pixi.js';

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

☝️ アップグレードの提案

v6 からコードを移行することを計画している場合は、v7 にアップグレードする前に、まず v6 でより劇的な変更の一部を実装すると役立ちます。

• 最新の v6.5.x にアップデートします。
• @pixi/events をインストールし、InteractionManager を入れ替えることで、イベントパッケージに切り替えます。

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');

• @pixi/assets をインストールし、Loader を入れ替えることで、Assets パッケージに切り替えます。Assets の実装の詳細については、このガイドを参照してください。
• Graphics.nextRoundedRectBehavior = true を設定します。これにより、コーナー半径にベジェ曲線ではなく弧が使用されます。
• Text.nextLineHeightBehavior = true を設定します。これにより、行の高さに DOM のような動作がデフォルトになります。

🏗️ プラグインサポート

プラグイン	互換性	サポートされているプラグインのバージョン
PixiJS サウンド	✅	v5.0.0+
PixiJS HTMLText	✅	v3.0.0+
PixiJS フィルター	✅	v5.0.0+
PixiJS GIF	✅	v2.0.0+
PixiJS Spine	✅	v4.0.0+
PixiJS パーティクルエミッター	✅	v5.0.8+
PixiJS アニメート	❌
PixiJS レイヤー	✅	v2.0.0+
PixiJS ライト	✅	v4.0.0+
PixiJS グラフィックス スムーズ	✅	v1.0.0+
PixiJS タイルマップ	❌