pixijs-migration-v8

このスキルは、v7 のコードベースを v8 に移行するための、破壊的変更のチェックリストです。カテゴリを上から順に確認してください。各項目では、v7 のパターンと v8 で置き換えるパターンを示しています。

クイックスタート

単一のパッケージをインストールしたら、次の順に移行します：インポート → Application の初期化 → Graphics → Text → イベント → シェーダー／フィルター → クリーンアップ。

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（非同期初期化）、pixijs-scene-graphics（新しい塗りつぶし／ストローク API）、pixijs-custom-rendering（シェーダーの再構成）、pixijs-scene-text（Text コンストラクターの変更）、pixijs-performance（破棄パターン）。

移行チェックリスト：v7 から v8 へ

各カテゴリを順に確認してください。各項目では、想定される v8 のパターンと、置き換える必要がある v7 のパターンを示しています。

初期化

非同期の app.init() -- 想定されるパターン：

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

不可：new Application({...}) にオプションを渡して、同期的に使用する。

app.view は app.canvas に置き換え -- 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

図形を描画してから塗りつぶす -- 想定されるパターン：

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

穴には 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)。

テキスト

Options オブジェクトコンストラクター -- 正しい例：

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') を呼び出す必要があります。

NineSlicePlane は NineSliceSprite に置き換わりました -- 正しい例：

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

Mesh の名称変更： 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))。

イベント

interactive は eventMode に置き換わりました -- 正しい例：

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

Uniforms には型が必要です -- new UniformGroup({ uTime: { value: 1, type: 'f32' } })。誤り：new UniformGroup({ uTime: 1 })。

テクスチャは Uniforms ではなくリソースです -- UniformGroup の中ではなく、トップレベルのリソースエントリー（texture.source、texture.style）として渡してください。

テクスチャ

Sprite はテクスチャの UV 変更を自動検出しなくなりました -- 作成後にテクスチャのフレームを変更した場合は、texture.update() を呼び出して UV を再計算し、その後 sprite.onViewUpdate() を呼び出してスプライトを更新してください。この順序で両方の呼び出しが必要です。ソースデータの更新（動画テクスチャなど）は引き続き自動で行われます。

texture.frame.width = texture.frame.width / 2;
texture.update(); // recalculate texture UVs first
sprite.onViewUpdate(); // then refresh the sprite's display

ミップマップ -- BaseTexture.mipmap は autoGenerateMipmaps に名称変更されました。RenderTextures では、ミップマップを手動で更新する必要があります：

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

アダプター

settings.ADAPTER は DOMAdapter に置き換わりました -- 正しい例：

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

誤り：settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();。

組み込みアダプター：BrowserAdapter（デフォルト）、WebWorkerAdapter（Web ワーカー用）。

その他

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' を使用してください。

テキストパーサーの名称変更：

• 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 などの補助パッケージは問題ありません）
• すべてのコア @pixi/* インポートを pixi.js に変更済み
• すべての new Application({...}) を await app.init({...}) に変更済み
• すべての Graphics コードが図形を作成してから塗りつぶすパターンを使用
• すべてのコンストラクターがオプションオブジェクトを使用（Text、Mesh、NineSliceSprite など）
• シェーダー／Filter コードが型付きユニフォームを含む {gl, resources} パターンを使用
• ParticleContainer コードが Sprite ではなく Particle を使用
• Ticker コールバックが第 1 引数を delta として扱わず、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/* サブパッケージは非推奨のため、使用してはいけません（上記「インポート」の全リストを参照）。@pixi/sound などの補助パッケージは引き続き有効です。

[CRITICAL] DisplayObject を基底クラスとして使用する

誤り：class MyObject extends DisplayObject { ... } 正しい例：class MyObject extends Container { ... }

v8 では DisplayObject が削除されました。Container はすべての表示オブジェクトの基底クラスです。

[HIGH] 古い SCALE_MODES／WRAP_MODES／DRAW_MODES 列挙型を使用する

誤り：texture.source.scaleMode = SCALE_MODES.NEAREST; 正しい例：texture.source.scaleMode = 'nearest';

v8 では文字列値を使用します。古い列挙型は非推奨のエイリアスとして動作する場合がありますが、置き換えてください。

［HIGH］eventMode の代わりに interactive = true を使用する

従来：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 移行ガイド
• v7 移行ガイド
• Application
• Graphics
• Container