v3-to-v4-migration

Phaser v3 から v4 への移行ガイド

このガイドでは、Phaser v3 プロジェクトを Phaser v4 にアップグレードする際に変更が必要なすべての項目を扱います。影響の大きい変更から細かい詳細へと並んでいるため、上から順に進めることができます。

関連スキル: ../v4-new-features/SKILL.md, ../game-setup-and-config/SKILL.md, ../filters-and-postfx/SKILL.md

---

目次

1. レンダラー: パイプラインからレンダーノードへ
2. Canvas レンダラーの非推奨化
3. FX とマスクがフィルターに
4. ティントシステム
5. カメラシステム
6. テクスチャ座標と GL の向き
7. DynamicTexture と RenderTexture
8. シェーダー API
9. GLSL の読み込み
10. ライティング
11. TileSprite
12. Graphics と Shape
13. ジオメトリ: Point が Vector2 に置き換え
14. 数学定数
15. データ構造
16. ラウンドピクセル
17. 削除されたゲームオブジェクト
18. 削除されたプラグインとエントリポイント
19. 削除されたユーティリティとポリフィル
20. Spine プラグイン
21. その他の破壊的変更
22. 移行チェックリスト

---

1. レンダラー: パイプラインからレンダーノードへ

Phaser v4 にはまったく新しい WebGL レンダラーが含まれています。v3 のレンダリングパイプラインはすべて置き換えられました。これは v4 における最大の変更です。

削除されたもの:

v3 の Pipeline システムは完全に削除されました。パイプラインはしばしば複数の責務を担っており(たとえば Utility パイプラインはさまざまな異なるレンダリングタスクを処理していました)、それぞれが独立して WebGL の状態を管理しなければならなかったため、あるパイプラインが別のパイプラインの前提を壊してしまう競合が発生していました。

置き換えられたもの:

新しい RenderNode アーキテクチャです。各レンダーノードは単一のレンダリングタスクを処理するため、システムはより保守しやすくなっています。すべてのレンダーノードには run メソッドがあり、一部には run を呼び出す前に複数のソースから状態を組み立てる batch メソッドがあります。

これがあなたにとって意味すること:

• ゲームが標準の Phaser API(スプライト、テキスト、タイルマップなど)のみを使用している場合、新しいレンダラーは透過的に動作するはずです。
• v3 で カスタム WebGL パイプラインを作成していた場合、それらはレンダーノードとして書き直す必要があります。起動時にカスタムレンダーノードを登録するには RenderConfig#renderNodes を使用してください。
• WebGLRenderer の内部に直接アクセスしていた場合は、多くの内部プロパティが削除または再構成されていることに注意してください:
  • WebGLRenderer.textureIndexes は削除されました。代わりに glTextureUnits.unitIndices を使用してください。
  • WebGLRenderer#genericVertexBuffer と #genericVertexData は削除されました(約 16MB の RAM/VRAM が解放されます)。BatchHandler レンダーノードは独自の WebGL データバッファを作成するようになりました。
  • WebGLAttribLocationWrapper は削除されました。
• Phaser v4 のゲームで WebGL の gl を直接呼び出さないでください。これは内部の WebGLGlobalWrapper を更新せずに WebGL の状態を変更してしまい、予測できない動作を引き起こす可能性があります。直接 WebGL にアクセスする必要がある場合は Extern ゲームオブジェクトを使用してください。これは終了後に状態をリセットします。

---

2. Canvas レンダラーの非推奨化

Canvas レンダラーはまだ利用可能ですが、非推奨と見なすべきです。Canvas レンダリングは、v4 の高度なレンダリング機能で使用される WebGL 技術を一切サポートしていません。WebGL のサポートは今日では事実上の標準であるため、すべての新規プロジェクトには WebGL を推奨します。

Canvas には 1 つ利点が残っています。27 個のブレンドモードに対し、WebGL のネイティブモードは 4 個(NORMAL、ADD、MULTIPLY、SCREEN)です。v4 では、新しい Blend フィルターが WebGL ですべての Canvas ブレンドモードを再現できますが、CaptureFrame、DynamicTexture などを介した間接化が必要です。

---

3. FX とマスクはフィルターに

これは、FX またはマスクシステムに依存していた v3 ユーザーにとって最も影響の大きい変更のひとつです。

変更点:

FX (プリおよびポスト) とマスクは、単一のフィルターシステムに統合されました。フィルターは入力画像を受け取り、通常は単一のシェーダーを介して出力画像を生成します。すべてのフィルターは相互に互換性があります。

v3 との主な違い:

• preFX/postFX の区別がなくなりました。 フィルターは、内部 (そのオブジェクトのみに影響) と外部 (レンダリングコンテキスト内、通常は全画面でそのオブジェクトに影響) のリストに分かれています。
• オブジェクトの制限がなくなりました。 v3 では、FX をサポートするオブジェクトは限られていました。v4 では、フィルターは Extern オブジェクトを含むあらゆるゲームオブジェクトまたはシーンカメラに適用できます。
• BitmapMask は削除されました。 代わりに新しい Mask フィルターを使用してください。GeometryMask は Canvas のみで引き続き利用できます。

削除された派生 FX とその代替:

v3 FX	v4 での代替
Bloom	Phaser.Actions.AddEffectBloom()
Shine	Phaser.Actions.AddEffectShine()
Circle	Phaser.Actions.AddMaskShape()
Gradient	Gradient ゲームオブジェクト

ColorMatrix の変更:

ColorMatrix フィルターは、そのカラーマネジメントメソッドを colorMatrix プロパティに移しました:

// v3
colorMatrix.sepia();

// v4
colorMatrix.colorMatrix.sepia();

マスクの移行:

// v3 - BitmapMask
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskObject);
sprite.setMask(mask);

// v4 - Mask filter
sprite.filters.internal.addMask(maskObject);

---

4. Tint システム

Tint システムは、新しい API と追加のブレンドモードを備えて全面的に刷新されました。

削除:

• tintFill プロパティ
• setTintFill() メソッド

代替:

• 新しい tintMode プロパティまたは setTintMode() メソッドを使用して、tint のブレンドを制御してください。
• Phaser.TintModes は利用可能なモードを列挙します: MULTIPLY、FILL、ADD、SCREEN、OVERLAY、HARD_LIGHT。

コードの変換方法:

// v3
sprite.setTintFill(0xff0000);

// v4
sprite.setTint(0xff0000).setTintMode(Phaser.TintModes.FILL);

その他の tint の変更:

• tint と setTint() は、純粋にカラー設定にのみ影響するようになりました。v3 では、これらを呼び出すとフィルモードが暗黙的に無効化されていました。
• FILL モードは、部分的なアルファを正しく処理するようになりました。
• BitmapText の tint が正しく機能するようになりました。

---

5. カメラシステム

カメラマトリックスシステムが書き直されました。標準的なカメラプロパティ (scrollX、scrollY、zoom、rotation) のみを使用している場合、コードは変更なしで動作するはずです。ただし、カメラマトリックスに直接アクセスしている場合は、コードを更新する必要があります。

変更点:

v3	v4
Camera#matrix = 位置 + 回転 + ズーム	Camera#matrix = 回転 + ズーム + スクロール (位置なし)
スクロールは別途追加	スクロールは Camera#matrix の一部
相当するものなし	Camera#matrixExternal = 位置のみ
相当するものなし	Camera#matrixCombined = matrix * matrixExternal

スクロールファクターを手動で操作していた場合:

// v3
spriteMatrix.e -= camera.scrollX * src.scrollFactorX;

// v4
TransformMatrix.copyWithScrollFactorFrom(matrix, scrollX, scrollY, scrollFactorX, scrollFactorY);

その他のカメラの変更:

• GetCalcMatrix() は、追加の ignoreCameraPosition パラメーターを受け取るようになりました。
• GetCalcMatrixResults に matrixExternal プロパティが含まれるようになりました。

---

6. テクスチャ座標と GL の向き

Phaser v3 はテクスチャに左上を基準とした向きを使用していたため、内部的に不一致が生じていました (フレームバッファーが上下逆に描画され、その後反転されていました)。Phaser v4 では、Y=0 が下端となる GL の向きを一貫して使用します。

必要な対応:

• 圧縮テクスチャを使用している場合は、Y 軸が下端から始まり上方向に増加するように再圧縮する必要があります。これは通常、テクスチャ圧縮ソフトウェアの「flip Y」オプションとして利用できます。
• 標準的な画像テクスチャ (PNG、JPG など) は自動的に処理されます -- 対応は不要です。
• カスタムシェーダーを作成している場合は、テクスチャ座標が GL の慣例に従い、Y=0 が画像の下端となることに注意してください。

---

7. DynamicTexture と RenderTexture

v3 では、DynamicTexture を使用してバッチを定義し、複雑な描画操作を直接実行できました。v4 では、これらの複雑なメソッドの多くが削除され、バッチ処理を自動的に処理する標準のレンダリングシステムを使用するようになりました。

破壊的変更: DynamicTexture と RenderTexture は、バッファリングされたすべての描画コマンドを実行するために render() を呼び出す必要があります。以前は、描画コマンドは即座に実行されていました。

新しい機能:

• DynamicTexture#preserve() は、レンダリング後も再利用できるようにコマンドバッファを保持し、変化するゲームオブジェクトを描画するコマンドを再レンダリングできるようにします。
• DynamicTexture#callback() は、コマンドバッファの実行中に実行するコールバックを挿入します。
• DynamicTexture#capture は、draw よりも正確にゲームオブジェクトをレンダリングし、現在のカメラビューをキャプチャします。
• RenderTexture.renderMode プロパティ: "render"（Image のように描画）、"redraw"（描画せずにレンダリングループ中にテクスチャを更新）、または "all"（両方）。"redraw" モードでは、同一フレームのシェーダー出力のためにレンダリングループの途中でテクスチャを更新できます。
• TextureManager#addDynamicTexture に forceEven パラメータが追加されました。

---

8. シェーダー API

Shader ゲームオブジェクトは大幅に書き直されました。既存の v3 シェーダーは更新が必要です。

変更点:

• コンストラクタのシグネチャは、個別のパラメータではなく設定オブジェクト（ShaderQuadConfig）を受け取るようになりました。
• Shadertoy スタイルのユニフォーム（resolution、time など）は自動的に設定されなくなりました。必要に応じて設定にエンコードしてください。
• テクスチャ座標は GL の規約（Y=0 が下端）を使用するようになりました。
• プログラムのユニフォームを個別に設定するための新しい Shader#setUniform(name, value) メソッド。
• 通常のレンダリングループ外でレンダリングするための新しい Shader#renderImmediate メソッド。

---

9. GLSL の読み込み

Phaser が GLSL コードを読み込む方法が変更されました:

• GLSL コードは、読み込み時に「fragment」または「vertex」として分類されなくなりました。新しいシステムでは、どちらか一方、または両方になる可能性があります。シェーダーを個別に読み込み、Shader を作成するときにそれらを結合します。
• カスタムテンプレートは #pragma プリプロセッサディレクティブに置き換えられました。これは有効な GLSL であり、自動構文チェッカーと互換性があります。プラグマはコンパイル前に削除されます。

---

10. ライティング

ライティングは簡素化され、強化されました。

コードを変換する方法:

// v3 - Pipeline-based lighting
sprite.setPipeline('Light2D');

// v4 - Simple method call
sprite.setLighting(true);

その他のライティングの変更点:

• ライティングは多くのゲームオブジェクトで利用できます: BitmapText、Blitter、Graphics、Shape、Image、Sprite、Particles、SpriteGPULayer、Stamp、Text、TileSprite、Video、TilemapLayer、および TilemapGPULayer。
• オブジェクトは、テクスチャの明るさに基づいて表面の特徴からの影をシミュレートするシェーダーを使用して、セルフシャドウを落とせるようになりました。ゲーム全体またはオブジェクトごとに設定可能です。
• ライトに z 値が追加され、高さを明示的に設定できるようになりました。これは v3 のゲーム解像度に基づく暗黙の高さを置き換えます。
• 注意: ライティングはシェーダーを変更するため、レンダーバッチが壊れます。
• イメージベースのライティングには ImageLight フィルターも使用できますが、これはコアのライティングシステムとは別のものです。

---

11. TileSprite

TileSprite は、WebGL のテクスチャラッピングパラメータに依存する代わりに、テクスチャ座標のラッピングを手動で制御する新しいシェーダーを使用するように内部的に書き直されました。

変更点:

• TileSprite はテクスチャのクロッピングをサポートしなくなりました。
• TileSprite は各次元に個別にデフォルトの寸法を割り当てるようになりました。

新しい機能:

• TileSprite は、アトラスおよびスプライトシート内のテクスチャフレームをサポートするようになりました（v3 ではテクスチャファイル全体を繰り返すことしかできませんでした）。
• 新しい tileRotation プロパティにより、繰り返しテクスチャを回転できます。
• 圧縮テクスチャ、2 の累乗ではないテクスチャ、および DynamicTextures で正しく動作します（v3 ではすべて問題がありました）。

---

12. グラフィックスとシェイプ

• Graphics に新しい pathDetailThreshold プロパティが追加されました（ゲーム設定オプションとしても利用可能）。これは、互いに一定距離内にある頂点をスキップし、狭い領域における複雑な曲線のパフォーマンスを向上させます。
• Grid シェイプのプロパティ名が変更されました。他の Shape オブジェクトの慣例に合わせて、outline の代わりに stroke を使用するようになりました。また Grid には、セル間にガターを描画するかどうか、およびアウトラインをグリッドの外側に描画するかセル間のみに描画するかを制御する新しいオプションが追加されました。
• Rectangle が角丸をサポートするようになりました。

---

13. ジオメトリ: Point が Vector2 に置き換え

Geom.Point クラスとすべての関連関数が削除されました。代わりに Vector2 を使用してください。

メソッドの置き換え早見表:

v3 (Point)	v4 (Vector2 / Math)
Point.Ceil	Vector2.ceil
Point.Floor	Vector2.floor
Point.Clone	Vector2.clone
Point.CopyFrom(src, dest)	dest.copy(src)
Point.Equals	Vector2.equals
Point.GetCentroid	Math.GetCentroid
Point.GetMagnitude	Vector2.length
Point.GetMagnitudeSq	Vector2.lengthSq
Point.Invert	Vector2.invert
Point.Negative	Vector2.negate
Point.SetMagnitude	Vector2.setLength
Point.Project	Vector2.project
Point.ProjectUnit	Vector2.projectUnit
Point.Interpolate	Math.LinearXY
Point.GetRectangleFromPoints	Math.GetVec2Bounds

すべてのジオメトリクラスが Point ではなく Vector2 を返すようになりました:

以下のクラスとその静的ヘルパー関数（getPoint、getPoints、getRandomPoint、CircumferencePoint、Random など）はすべて Vector2 インスタンスを返します:

• Geom.Circle
• Geom.Ellipse
• Geom.Line
• Geom.Polygon
• Geom.Rectangle
• Geom.Triangle

instanceof Phaser.Geom.Point をチェックしているコードがある場合は、Phaser.Math.Vector2 をチェックするように更新してください。

---

14. 数学定数

v3	v4	備考
Math.TAU（PI / 2 だった）	Math.TAU（PI * 2 になった）	値が変更されました！ これは数学的に正しい tau になりました。
Math.PI2	削除	代わりに Math.TAU を使用してください。
相当するものなし	Math.PI_OVER_2	PI / 2 の新しい定数です（v3 の TAU が誤って表していた値）。

対応が必要: v3 で PI / 2 を期待して Math.TAU を使用していた場合は、Math.PI_OVER_2 に置き換えてください。Math.PI2 を使用していた場合は、Math.TAU に置き換えてください。

---

15. データ構造

Phaser.Struct.Set はネイティブの JavaScript Set に置き換えられました。iterateLocal などのメソッドはなくなりました。標準の Set メソッド（forEach、has、add、delete など）を使用してください。

Phaser.Struct.Map はネイティブの JavaScript Map に置き換えられました。contains や setAll などのメソッドはなくなりました。標準の Map メソッド（has、get、set、delete など）を使用してください。

---

16. ラウンドピクセル

roundPixels ゲーム設定オプションのデフォルトが false になりました（v3 では true でした）。動作も改良されています:

• roundPixels は、オブジェクトが軸に沿って整列され、スケールされていない場合にのみ機能し、変形中のオブジェクトでのちらつきを防ぎます。
• オブジェクトごとの制御には、新しい GameObject#vertexRoundMode プロパティを使用します:
  • "off" -- 常に丸めません。
  • "safe" -- トランスフォームが位置のみの場合（スケール・回転なし）にのみ丸めます。
  • "safeAuto"（デフォルト） -- "safe" と同様ですが、カメラで roundPixels が有効な場合にのみ適用されます。
  • "full" -- 常に丸めます（回転したスプライトではぐらつきが発生する可能性があります。PS1 スタイル）。
  • "fullAuto" -- "full" と同様ですが、カメラで roundPixels が有効な場合にのみ適用されます。
• TransformMatrix#setQuad の roundPixels パラメータは削除されました。

---

17. 削除されたゲームオブジェクト

• Mesh と Plane が削除されました。これらは限定的な 3D 実装でした。正式な 3D サポートは将来計画されています。

---

18. 削除されたプラグインとエントリーポイント

以下が完全に削除されました:

• Camera3D プラグイン
• Layer3D プラグイン
• Facebook プラグインの検出定数
• phaser-ie9.js エントリーポイント（IE9 はサポートされなくなりました）

---

19. 削除されたユーティリティとポリフィル

Create.GenerateTexture およびすべての Create パレット / create フォルダーが削除されました。その結果、TextureManager.generate も削除されました。

Math.SinCosTableGenerator が削除されました。

すべてのレガシーポリフィルが削除されました:

• Array.forEach
• Array.isArray
• AudioContextMonkeyPatch
• console
• Math.trunc
• performance.now
• requestAnimationFrame
• Uint32Array

これらの機能はすべて、モダンブラウザーがネイティブで提供しています。

---

20. Spine プラグイン

Phaser にバンドルされている Spine 3 および Spine 4 プラグインは、今後更新されません。代わりに、Esoteric Software が作成した公式の Phaser Spine プラグインを使用してください。

---

21. その他の破壊的変更

• Shader#setTextures() は、テクスチャ配列に追加するのではなく、テクスチャ配列を置き換えるようになりました。テクスチャを積み重ねるために複数回呼び出していた場合は、完全な配列を指定して一度だけ呼び出してください。
• DOMElement は、コンテナーを持たない場合にエラーをスローするようになりました。DOM 要素に親コンテナーがあることを確認してください。
• GameObject#enableLighting は、シーンのライトマネージャーが有効になっていなくても設定できるようになりました。ライトをレンダリングするにはマネージャーを有効にする必要がありますが、フラグ自体は制限されなくなりました。
• Gamepad の Button クラス は、シーン遷移を通じて状態を正しく初期化するための isPressed パラメーターを受け入れるようになりました。
• BatchHandlerConfig#createOwnVertexBuffer の型プロパティが削除されました。
• WebGLRenderer#genericVertexBuffer と #genericVertexData が削除されました (約 16MB の RAM/VRAM が解放されます)。

---

移行チェックリスト

このチェックリストを使用して、移行の進捗状況を追跡してください:

• npm install phaser@4 (または同等のもの) を更新する
• カスタム WebGL パイプラインをレンダーノードに置き換える
• BitmapMask の使用を Mask フィルターに置き換える
• 削除された FX (Bloom、Shine、Circle、Gradient) を対応する Action/GameObject に置き換える
• ColorMatrix の呼び出しを更新する (メソッドは .colorMatrix プロパティに移動しました)
• setTintFill() の呼び出しを setTint().setTintMode(Phaser.TintModes.FILL) に置き換える
• Geom.Point の使用を Vector2 に置き換える
• Math.TAU の使用を更新する (PI / 2 ではなく PI * 2 になりました)
• Math.PI2 を Math.TAU に置き換える
• Phaser.Struct.Set をネイティブの Set に置き換える
• Phaser.Struct.Map をネイティブの Map に置き換える
• DynamicTexture / RenderTexture の使用に render() 呼び出しを追加する
• 新しい Y 軸の向きに合わせて、圧縮テクスチャを再圧縮する
• Camera#matrix への直接アクセスを新しいマトリックスシステムを使用するように更新する
• Shader ゲームオブジェクトを新しい ShaderQuadConfig コンストラクターを使用するように更新する
• GLSL 読み込みコードを更新する (フラグメント/バーテックスの分類がなくなり、#pragma ディレクティブを使用)
• sprite.setPipeline('Light2D') を sprite.setLighting(true) に置き換える
• ライトの高さのコードを新しい z プロパティを使用するように更新する
• TileSprite のテクスチャクロッピングコードを削除する
• Grid シェイプのコードを更新する (outline プロパティは stroke に名前が変更されました)
• Mesh または Plane の使用を削除する
• Phaser にバンドルされている Spine プラグインの使用を、Esoteric Software の公式プラグインに置き換える
• Create.GenerateTexture または TextureManager.generate への依存を削除する
• roundPixels の動作をテストする (デフォルトが false になりました)
• 削除されたポリフィル、プラグイン、またはエントリポイントの使用を削除する
• カスタムシェーダーのテクスチャ座標を確認する (Y=0 が最下部になりました)