pixijs-migration-v8

このスキルは、v7 のコードベースを v8 に対応させるためのブレーキングチェンジチェックリストです。各カテゴリを上から下へ進みながら、各 v7 パターンを v8 の置き換えにマッピングします。

クイックスタート

単一パッケージをインストールしてから、この順序で対応します：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);

関連スキル: pixijs-application (async init), pixijs-scene-graphics (新しい fill/stroke API), pixijs-custom-rendering (シェーダー再構成), pixijs-scene-text (Text コンストラクタの変更), pixijs-performance (destroy パターン)。

マイグレーションチェックリスト：v7 から v8

各カテゴリを順番に進めてください。各項目は、期待される v8 パターンと置き換える必要がある v7 パターンを示しています。

初期化

Async app.init() -- 期待される形式：

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

不正な使用法：new Application({...}) にオプションを渡して同期的に使用する場合。

app.canvas が app.view を置き換える -- app.view は非推奨の警告を出力します。

Application 型パラメータ -- 期待される形式：new Application<Renderer<HTMLCanvasElement>>()。不正な使用法：new Application<HTMLCanvasElement>()。

インポート

単一パッケージ -- 期待される形式：

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

不正な使用法：非推奨の v7 コア @pixi/* サブパッケージからのインポート（以下のリストを参照）。@pixi/sound などの補助パッケージは引き続き有効で、使用し続ける必要があります。

非推奨の @pixi/* パッケージ（決して使用しないでください、どのバージョンでも）： @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。

カスタムビルド -- skipExtensionImports: true を設定し、必要な拡張機能のみをインポートします：

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

注記：manageImports: false は引き続きサポートされていますが @deprecated since 8.1.6；skipExtensionImports: true が推奨されます。

自動インポートされない拡張機能（デフォルトの自動インポートが有効になっていても明示的なインポートが必要）： 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。

コミュニティフィルター -- 期待される形式：import { AdjustmentFilter } from 'pixi-filters/adjustment'。不正な使用法：@pixi/filter-adjustment。

Graphics API

Shape-then-fill -- 期待される形式：

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

不正な使用法：beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill()。

メソッド名の変更：

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 が beginFill/beginTextureFill を置き換える -- 期待される形式：

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

不正な使用法：beginFill(color, alpha) または beginTextureFill({ texture, alpha, color })。

Stroke が lineStyle を置き換える -- 期待される形式：

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

不正な使用法：lineStyle(2, 'white') または lineTextureStyle({ texture, width, color })。

Holes は cut() を使用 -- 期待される形式：

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

不正な使用法：beginHole() / endHole()。

GraphicsContext が GraphicsGeometry を置き換える -- 期待される形式：

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

不正な使用法：new Graphics(graphics.geometry)。

Text

オプションオブジェクトコンストラクタ -- 期待される形式：

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

不正な使用法：new Text('Hello', { fontSize: 24 }) (位置引数)。

ビットマップフォントの読み込み -- Assets.load('font.fnt') の前に import 'pixi.js/text-bitmap' が必須です。

スプライト / メッシュ

Texture.from はもう URL を読み込まない -- 最初に await Assets.load('image.png') を呼び出してから、Texture.from('image.png') を呼び出す必要があります。

NineSliceSprite が NineSlicePlane を置き換える -- 期待される形式：

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

メッシュの名前変更： SimpleMesh -> MeshSimple, SimplePlane -> MeshPlane, SimpleRope -> MeshRope。すべてオプションオブジェクトを使用します。

MeshGeometry のオプション -- 期待される形式：

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

不正な使用法：new MeshGeometry(vertices, uvs, indices)。

ParticleContainer は Particle を使用 -- 期待される形式：

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

不正な使用法：container.addChild(new Sprite(texture))。

イベント

eventMode が interactive を置き換える -- 期待される形式：

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

レガシー：sprite.interactive = true; (引き続き eventMode = 'static' のエイリアスとして機能しますが、明示的な形式が推奨されます)。

デフォルトの eventMode は 'passive' (イベントなし) です。'static' または 'dynamic' を明示的に設定する必要があります。

Ticker コールバック -- 期待される形式：

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

不正な使用法：app.ticker.add((dt) => { bunny.rotation += dt; }) -- コンパイルされますが、dt は Ticker オブジェクトであり、数値ではありません。NaN に強制変換され、回転が暗黙的に破損します。

updateTransform 削除 -- コンストラクタ内で this.onRender = this._onRender.bind(this) を使用します。

シェーダー

Shader.from はオプションを使用 -- 期待される形式：

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

不正な使用法：Shader.from(vertex, fragment, uniforms)。

Filter コンストラクタ -- 期待される形式：

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

不正な使用法：new Filter(vertex, fragment, { uTime: 0 })。

ユニフォームは型が必須 -- new UniformGroup({ uTime: { value: 1, type: 'f32' } })。不正な使用法：new UniformGroup({ uTime: 1 })。

テクスチャはリソース、ユニフォームではない -- トップレベルのリソースエントリ（texture.source, texture.style）として渡します。UniformGroup 内に含めません。

テクスチャ

スプライトはテクスチャ UV 変更を自動検出しない -- 作成後にテクスチャの frame を修正する場合、texture.update() を呼び出して UV を再計算し、その後 sprite.onViewUpdate() を呼び出してスプライトをリフレッシュします。両方の呼び出しがこの順序で必須です。ソースデータの更新（例：ビデオテクスチャ）は引き続き自動です。

texture.frame.width = texture.frame.width / 2;
texture.update(); // 最初にテクスチャ UV を再計算
sprite.onViewUpdate(); // その後スプライトの表示をリフレッシュ

ミップマップ -- BaseTexture.mipmap は autoGenerateMipmaps に名前変更。RenderTextures の場合、ミップマップを手動で更新する必要があります：

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

アダプター

DOMAdapter が settings.ADAPTER を置き換える -- 期待される形式：

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

不正な使用法：settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();。

組み込みアダプター：BrowserAdapter (デフォルト), WebWorkerAdapter (web workers 用)。

その他

DisplayObject 削除 -- Container が基本クラスです。class MyObj extends DisplayObject は失敗します。

リーフノードは子を持つことができない -- Sprite, Graphics, Mesh, Text はリーフノードです。Container でラップします。

プロパティ名の変更（古い名前は非推奨のエイリアスとして警告付きで引き続き存在）：

• container.name -> container.label
• container.cacheAsBitmap = true -> container.cacheAsTexture(true)

getBounds() の戻り値の型が変更： getBounds() は Rectangle ではなく Bounds オブジェクトを返すようになりました。Bounds は .x, .y, .width, .height ゲッターを持つため、基本的な使用法は機能します。Rectangle インスタンスが必要な場合（例：.contains() の場合）は .rectangle を使用します。

settings オブジェクト削除 -- AbstractRenderer.defaultOptions.resolution = 1 と DOMAdapter.set(BrowserAdapter) を使用します。

utils 名前空間削除 -- utils.isMobile の代わりに import { isMobile } from 'pixi.js' を使用します。

Text パーサー名の変更：

• TextFormat -> bitmapFontTextParser
• XMLStringFormat -> bitmapFontXMLStringParser
• XMLFormat -> bitmapFontXMLParser

Assets.add -- Assets.add({ alias: 'bunny', src: 'bunny.png' })。不正な使用法：Assets.add('bunny', 'bunny.png')。

列挙定数を文字列に置き換え：

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'

カリングは手動 -- cullable = true を設定してから、レンダリング前に Culler.shared.cull(container, viewRect) を呼び出します。または extensions.add(CullerPlugin) を使用して CullerPlugin を追加します。

マイグレーション前のサマリー

• 依存関係に非推奨の v7 コア @pixi/* パッケージがない（@pixi/sound などの補助パッケージは OK）
• すべてのコア @pixi/* インポートが pixi.js に変換されている
• すべての new Application({...}) が await app.init({...}) に変換されている
• すべての Graphics コードが shape-then-fill パターンを使用している
• すべてのコンストラクタがオプションオブジェクトを使用している（Text, Mesh, NineSliceSprite など）
• Shader/Filter コードが {gl, resources} パターンと型付きユニフォームを使用している
• ParticleContainer コードが Sprite ではなく Particle を使用している
• Ticker コールバックが最初のパラメータではなく ticker.deltaTime にアクセスしている
• イベント処理が interactive ではなく eventMode を使用している
• settings と utils の参照が削除されている
• DisplayObject の参照が Container に置き換えられている
• テクスチャ UV 修正が必要に応じて sprite.onViewUpdate() を呼び出している
• RenderTexture ミップマップコードが source.updateMipmaps() を手動で呼び出している
• settings.ADAPTER が DOMAdapter.set() に置き換えられている

よくある間違い

[CRITICAL] 非推奨の v7 コア @pixi/* サブパッケージからのインポート

不正：

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

正しい：

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

v8 は単一の pixi.js パッケージを使用します。v7 コア @pixi/* サブパッケージは非推奨であり、使用してはいけません（上記の Imports セクションの完全なリストを参照）。@pixi/sound などの補助パッケージは引き続き有効です。

[CRITICAL] DisplayObject を基本クラスとして使用

不正：class MyObject extends DisplayObject { ... } 正しい：class MyObject extends Container { ... }

DisplayObject は v8 で削除されました。Container はすべてのディスプレイオブジェクトの基本クラスです。

[HIGH] 古い SCALE_MODES/WRAP_MODES/DRAW_MODES 列挙を使用

不正：texture.source.scaleMode = SCALE_MODES.NEAREST; 正しい：texture.source.scaleMode = 'nearest';

v8 は文字列値を使用します。古い列挙は非推奨のエイリアスとして機能する可能性がありますが、置き換える必要があります。

[HIGH] interactive = true を eventMode の代わりに使用

レガシー：sprite.interactive = true; (引き続き eventMode = 'static' のエイリアスとして機能) 推奨：sprite.eventMode = 'static';

デフォルトの eventMode は 'passive' (イベントなし) です。'static' (ヒットテスト可能、ティックチェックなし) または 'dynamic' (ヒットテスト可能、ティックチェック付き) を明示的に設定する必要があります。interactive = true は引き続き非推奨の警告なしで機能しますが、eventMode が正規の v8 API です。

[HIGH] utils 名前空間を使用

不正：import { utils } from 'pixi.js'; utils.isMobile.any(); 正しい：import { isMobile } from 'pixi.js'; isMobile.any();

utils 名前空間は削除されました。すべてのユーティリティ関数は直接インポートです。

[HIGH] テクスチャ UV の変更がスプライトを自動的に更新することを期待

不正：texture.frame を修正してスプライトが自動的に更新されると想定する。 正しい：テクスチャ UV を修正した後で sprite.onViewUpdate() を呼び出す。

パフォーマンスのため、スプライトはテクスチャ UV チェンジイベントをサブスクライブしなくなりました。ソースデータの更新（例：ビデオ）は引き続き自動的に反映されます。

API リファレンス

• v8 Migration Guide
• v7 Migration Guide
• Application
• Graphics
• Container