v5移行ガイド

このドキュメントは、**v4からv5へのアップグレード**を試みている開発者にとって役立ちます。これには、v4のコードで微妙な変更が必要になる理由を理解するための注意点と重要なコンテキストが含まれています。一般的に、`console`で非推奨警告を使用することにより、v5では後方互換性を維持しようと努力しています。しかし、変更が大きすぎて追加のヘルプが必要になる場合もあります。

🚧 APIの変更点

WebGLのファーストクラス化

PixiJS v5では、WebGLをファーストクラスのレンダラーにし、CanvasRendererをセカンドクラスにしました。機能的にはv4から大きく変更された点はありませんが、v5にアップグレードする際に一部の開発者を混乱させる可能性のある、多くの微妙な内部的な名前の変更があります。例えば

• WebGLRendererはRendererになります
• renderWebGLはrenderになります（DisplayObject、Sprite、Containerなど）
• _renderWebGLは_renderになります（DisplayObject、Containerなど）

Containerでrenderを使用していたプラグインまたはプロジェクトを作成した場合（#5510参照）、プロジェクトが正しくレンダリングされない可能性があります。ユーザー定義のrenderを別の名前に変更することを検討してください。ほとんどの場合、WebGL関連のクラスまたはメソッド（例：new PIXI.WebGLRenderer()）を呼び出そうとすると、非推奨警告が表示されます。

レンダラーパラメータ

Rendererコンストラクタの第3パラメータとしてoptionsを指定することは正式に廃止されました（PIXI.Application、PIXI.autoDetectRenderer、PIXI.CanvasRendererも同様です）。v4では2つの関数シグネチャをサポートしていましたが、v5ではwidth, height, optionsシグネチャを廃止しました。widthとheightをoptionsに追加してください。

const renderer = new PIXI.Renderer(800, 600, { transparent: true }); // bad
const renderer = new PIXI.Renderer({ width: 800, height: 600, transparent: true }); // good

• 注：RendererまたはApplicationコンストラクタオプションにtransparent: trueを追加すると、一部のデバイスで発生する奇妙なアーティファクトを軽減できる可能性がありますが、FPSが低下する可能性があります。preserveDrawingBuffer: trueよりもはるかに優れています。

• CSSピクセルを使用してキャンバスのサイズ変更を行うv4のデフォルトの動作が必要な場合は、オプションにautoDensity: trueを追加してください。

すべてのパラメータに変更されたわけではありません。WebGL2が使用できる場合でもWebGL1を有効にするには、以下を使用します。

PIXI.settings.PREFER_ENV = PIXI.ENV.WEBGL;

Mesh、Plane、Rope

PixiJS v5では、PIXI.Meshという新しいクラスが導入されました。これにより、デフォルトのシェーダーをオーバーライドし、ジオメトリに属性を追加できます。例として、頂点に色を追加できます。

古いv4のMeshクラスはPIXI.mesh.MeshからPIXI.SimpleMeshに移動しました。これはPIXI.Meshを拡張します。

PIXI.mesh.Rope、PIXI.mesh.Plane、PIXI.mesh.NineSlicePlaneはそれぞれPIXI.SimpleRope、PIXI.SimplePlane、PIXI.NineSlicePlaneに移動しました。

v4でカスタムシェーダーまたは生成されたメッシュを使用していた場合、v5でのこれらの変更の影響を受ける可能性があります。

PIXI.SimpleMeshのフィールドvertices、uvs、indicesはmesh.geometry属性バッファ内にラップされています。例えば、mesh.uvBufferプロパティを介して提供されるバッファへのアクセス方法は次のとおりです。

get uvBuffer()
{
    return this.geometry.buffers[1];
}

indicesプロパティのショートカットもありませんが、mesh.geometry.indexBuffer内のデータにアクセスできます。

バッファデータをオーバーライドし、データが変更されたことを通知できます。この場合、バッファは遅延してGPUにアップロードされます。以前のv4のメッシュには、更新する必要がある属性を示すいくつかのフラグがあり、それらの名前は人を混乱させました。

グラフィックの穴

v4では、グラフィックで穴を描くことは非常に限られていました。これは、lineTo、bezierCurveToなどを使用する非シェイプ描画のみをサポートしていました。v5では、シェイプをサポートすることで穴APIを改善しました。残念ながら、v4 APIをサポートするための非推奨戦略はありません。例えば、v4では

const graphic = new PIXI.Graphics()
  .beginFill(0xff0000)
  .moveTo(0, 0)
  .lineTo(100, 0)
  .lineTo(100, 100)
  .lineTo(0, 100)
  .moveTo(10, 10)
  .lineTo(90, 10)
  .lineTo(90, 90)
  .lineTo(10, 90)
  .addHole();

v4.xのライブサンプル

v5では、Graphicsが簡素化され、APIがaddHoleからbeginHoleとendHoleに変更されました。

const graphic = new PIXI.Graphics()
  .beginFill(0xff0000)
  .drawRect(0, 0, 100, 100)
  .beginHole()
  .drawCircle(50, 50, 30)
  .endHole();

devのライブサンプル

フィルタのパディング

v4のフィルタはデフォルトのパディングが4でしたが、v5では0に変更されました。これにより、使用されている一部のフィルタが壊れて見える可能性があります。この問題を解決するには、作成するフィルタにパディングを追加するだけです。

// Glow filter from https://github.com/pixijs/pixi-filters
const filter = new PIXI.filters.GlowFilter();
filter.padding = 4;

BlurFilterなどの一部のフィルタは、パディングを自動的に計算するため、変更は不要な場合があります。

フィルタのデフォルト頂点シェーダー

座標系変換専用のすべてのユニフォームを再編成し、名前を変更しました。フィルタが機能しなくなった場合は、デフォルトの頂点シェーダーを使用しているかどうかを確認してください。その場合は、古いv4の頂点シェーダーコードを使用できます。

すべての変更は[[フィルタの作成|v5-Creating-filters]]

RenderTextureのMipmappingを有効にする

以前は、v4でこのようなコードを使用していた可能性があります（特にIvanのコメント/JSFiddleを参照）。

const renderer = PIXI.autoDetectRenderer();
renderer.bindTexture(baseRenderTex, false, 0);
const glTex = baseRenderTex._glTextures[renderer.CONTEXT_UID];
glTex.enableMipmap(); // this is what actually generates mipmaps in WebGL
glTex.enableLinearScaling(); // this is what tells WebGL to USE those mipmaps

v5では、このコードは不要になりました。

BaseTextureリソース

v5の最新機能の1つは、アセット固有の機能をBaseTextureから分離したこととです。「リソース」という新しいシステムを作成し、各BaseTextureには、特定のアセットタイプをラップするリソースが持つようになりました。例えば：VideoResource、SVGResource、ImageResource、CanvasResource。将来的には、他のリソースタイプを追加できることを期待しています。以前にアセット固有のメソッドやプロパティが呼び出されていた場合、それらはおそらくbaseTexture.resourceにあります。

また、BaseTextureからすべてのfrom*メソッドを削除したので、BaseTexture.fromを呼び出して、任意のリソースを渡すことができます。fromの詳細については、ドキュメントを参照してください。

const canvas = document.createElement('canvas');
const baseTexture = PIXI.BaseTexture.from(canvas);

そのAPIは、純粋なWebGLと2Dコンテキスト呼び出しの使用も可能にします。グラデーションの例を参照してください。

BaseTexture.source

baseTexture.resource.sourceに移動しました。BaseTextureに対応するリソースに移動しました。baseTexture.resourceはRenderTextureには存在せず、sourceはsourceを持たないリソースには存在しません。

グラフィックのインタラクション

透過インタラクティブグラフィックのトリックを使用する場合は、要素の一部ではなく、すべての要素に対してalpha=0を指定してください。PixiJSがalpha=0のシェイプをどのように扱うかは、未定義の動作と見なされます。元に戻す可能性がありますが、それについては保証できません。

graphics.beginFill(0xffffff, 0.0); //bad
graphics.alpha = 0; //good

📦 公開の変更点

Canvasがレガシーになる

WebGLとWebGL2がファーストクラスになったため、デフォルトのpixi.jsパッケージからキャンバスベースのフォールバックを削除しました。CanvasRendererが必要な場合は、代わりにpixi.js-legacyを使用するように切り替える必要があります。

import * as PIXI from "pixi.js";
// Will NOT return CanvasRenderer because canvas-based
// functionality was removed from "pixi.js"
const renderer = PIXI.autoDetectRenderer(); // return PIXI.Renderer or throws error

代わりに、レガシーバンドルを使用してキャンバスレンダリングにアクセスしてください。

import * as PIXI from "pixi.js-legacy";
const renderer = PIXI.autoDetectRenderer(); // returns PIXI.Renderer or PIXI.CanvasRenderer

バンドリングの変更点

Rollup、Parcel、または他のバンドラーを使用してPixiJSをプロジェクトに追加する場合、v5に移行するときにいくつかの微妙な変更があります。つまり、グローバルPIXIオブジェクトは自動的に作成されなくなりました。これは、1）バンドラーのツリーシェイキングを改善するため、2）PIXIを保護することによりセキュリティを確保するために、バンドリングから削除されました。

これは、インポートする有効な方法ではなくなりました。

import "pixi.js";
const renderer = PIXI.autoDetectRenderer(); // INVALID! No more global.PIXI!

代わりに、名前空間または個々の要素としてインポートする必要があります。

import * as PIXI from "pixi.js";
const renderer = PIXI.autoDetectRenderer();

// or even better:
import { autoDetectRenderer } from "pixi.js";
const renderer = autoDetectRenderer();

最後に、一部のサードパーティプラグインはwindow.PIXIを期待している可能性があるため、このようにグローバルを明示的に公開する必要がある場合がありますが、これは推奨されません。

import * as PIXI from 'pixi.js';
window.PIXI = PIXI; // some bundlers might prefer "global" instead of "window"

Webpack

Webpackとpixi-spineなどのサードパーティプラグインを使用すると、グローバルPIXIオブジェクトを構築する際に問題が発生し、ランタイムエラーReferenceError: PIXI is not definedが発生する可能性があります。通常、これはWebpackのグローバルシミングを使用することで解決できます。

例えば、インポートコードは次のようになります。

import * as PIXI from 'pixi.js';
import 'pixi-spine'; // or other plugins that need global 'PIXI' to be defined first

WebpackにグローバルPIXI変数がpixi.jsモジュールを参照することを知らせるために、webpack.config.jsにpluginsセクションを追加します。例えば

const webpack = require('webpack');

module.exports = {
    entry: '...',
    output: {
        ...
    },
    plugins: [
     new webpack.ProvidePlugin({
       PIXI: 'pixi.js'
     })
   ]
}