phaser-migrate

Phaser 3 → Phaser 4 マイグレーション

Phaser 3 から Phaser 4 へのマイグレーションは、ほぼそのまま進められます。コアの公開 API は維持されています。このスキルでは、すべての破壊的変更とその修正方法を扱います。さらに、Phaser 4 のポイントリリース間（4.0 → 4.1 → 4.2）の移行や、問題なくコンパイルできるのに予期しない挙動を引き起こすランタイムの動作についても扱います。

ステップ 1 — パッケージを更新する

npm uninstall phaser
npm install phaser

インストール済みバージョンを確認します：

node -e "const p = require('phaser'); console.log(p.VERSION)"

4.2.1（またはそれ以降の RC）が出力されるはずです。

ステップ 2 — 破壊的変更をスキャンする

以下の grep 検索を実行して、src/ ディレクトリ内の問題をすべて洗い出します：

# 1. Point → Vector2
grep -rn "Geom\.Point\|new Phaser\.Geom\.Point\|Geom\.Point\." src/

# 2. Math.PI2 → Math.TAU
grep -rn "Math\.PI2\b" src/

# 3. Phaser.Structs
grep -rn "Phaser\.Structs\." src/

# 4. DynamicTexture / RenderTexture (check for missing .render())
grep -rn "DynamicTexture\|RenderTexture\|addDynamicTexture\|addRenderTexture" src/

# 5. Removed plugins
grep -rn "Camera3D\|Layer3D\|FacebookInstant\|SpinePlugin\|SpineFile" src/

# 6. TileSprite crop (setCrop on TileSprite — no longer supported)
grep -rn "tileSprite.*setCrop\|setCrop.*tileSprite" src/

# 7. Create.GenerateTexture (removed)
grep -rn "Create\.GenerateTexture\|Phaser\.Create\." src/

# 8. Spine (use official Esoteric plugin instead)
grep -rn "spine\|Spine" src/ -i

# 9. phaser-ie9 entry point
grep -rn "phaser-ie9" . 

# 10. WebGL geometry masks (stencil-based masks changed in Phaser 4 — use scissor/viewport instead)
grep -rn "createGeometryMask\|createBitmapMask\|BitmapMask\|setMask\b\|clearMask\|setScissor" src/ 

ステップ 3 — 修正を適用する

修正 1: Geom.Point → Vector2

Phaser.Geom.Point は完全に削除されました。Phaser.Math.Vector2 を使用してください。

// BEFORE (Phaser 3)
const point = new Phaser.Geom.Point(x, y);
point.x = 100;
const distance = Phaser.Geom.Point.GetMagnitude(point);
const clone = Phaser.Geom.Point.Clone(point);
Phaser.Geom.Point.SetMagnitude(point, 50);

// AFTER (Phaser 4)
const point = new Phaser.Math.Vector2(x, y);
point.x = 100;
const distance = point.length();
const clone = point.clone();
point.setLength(50);

Point → Vector2 のメソッド対応表（全体）：

Phaser 3（静的）	Phaser 4（インスタンス）
Point.GetMagnitude(pt)	pt.length()
Point.Clone(pt)	pt.clone()
Point.SetMagnitude(pt, n)	pt.setLength(n)
Point.Ceil(pt)	pt.ceil()
Point.Floor(pt)	pt.floor()
Point.Invert(pt)	pt.invert()
Point.Negative(pt)	pt.negate()
Point.Project(pt, target, out)	pt.project(target)
Point.GetCentroid(points)	Phaser.Math.GetCentroid(points)
Point.GetRectangleFromPoints(pts)	Phaser.Math.GetVec2Bounds(pts)

すべての Geometry クラス（Circle、Ellipse、Line、Rectangle、Triangle、Polygon）は、点に関連する結果として Point ではなく Vector2 を返すようになりました。

修正 2: Math.PI2 → Math.TAU

// BEFORE (Phaser 3) — NOTE: Math.PI2 was INCORRECTLY π in v3
const fullRotation = Math.PI2;  // was wrong!

// AFTER (Phaser 4)
const fullRotation = Math.TAU;       // Correct π×2
const halfRotation = Math.PI_OVER_2; // π/2 (new constant)

修正 3: Phaser.Structs → ネイティブ JS

// BEFORE (Phaser 3)
const myMap = new Phaser.Structs.Map([]);
myMap.set('key', value);
myMap.get('key');
myMap.delete('key');
myMap.getArray();

const mySet = new Phaser.Structs.Set();
mySet.set(value);
mySet.delete(value);
mySet.contains(value);

// AFTER (Phaser 4)
const myMap = new Map<string, any>();
myMap.set('key', value);
myMap.get('key');
myMap.delete('key');
[...myMap.values()];

const mySet = new Set<any>();
mySet.add(value);
mySet.delete(value);
mySet.has(value);

修正 4: DynamicTexture / RenderTexture — render() を追加する

// BEFORE (Phaser 3) — drawing happened immediately
const dynTex = this.textures.addDynamicTexture('key', 200, 200);
dynTex.draw('sprite', 0, 0);
// visible immediately

// AFTER (Phaser 4) — must call render() to commit drawing
const dynTex = this.textures.addDynamicTexture('key', 200, 200);
dynTex.draw('sprite', 0, 0);
dynTex.render();   // ← REQUIRED in v4

修正 5: 削除されたプラグイン

Camera3D — 代替はありません。Phaser 4 は 2D 専用です。3D が必要な場合は、Phaser と併用して Three.js を使用してください。

Layer3D — 代替はありません。Camera3D とともに削除されました。

Facebook Instant Games — 削除されました。Facebook はこのプラットフォームをすでにサポートしていません。

Spine プラグイン（公式の v3/v4 Spine サポート）— 代わりに公式の Esoteric Software Phaser プラグイン を使用してください。Phaser に同梱されていた Spine プラグインは、もはやメンテナンスされていません。

修正 6: TileSprite のクロッピング

Phaser 4 では、TileSprite はテクスチャのクロッピングをサポートしなくなりました。

// BEFORE (Phaser 3)
const ts = this.add.tileSprite(x, y, w, h, 'texture');
ts.setCrop(0, 0, 100, 100);  // no longer works in v4

// AFTER (Phaser 4) — use RenderTexture instead if cropping is needed
const rt = this.add.renderTexture(x, y, 100, 100);
rt.draw('texture', 0, 0);
rt.render();

修正 7: Create.GenerateTexture の削除

Phaser.Create.GenerateTexture とすべての Create パレットが削除されました。

// BEFORE (Phaser 3)
const texture = Phaser.Create.GenerateTexture({ data: palettes, pixelWidth: 2 });

// AFTER (Phaser 4) — use a pre-made image asset, or draw with Graphics
const gfx = this.add.graphics();
gfx.fillStyle(0xff0000);
gfx.fillRect(0, 0, 16, 16);
gfx.generateTexture('red-square', 16, 16);
gfx.destroy();

修正 8: 削除された IE9 エントリポイント

// BEFORE — some projects imported the IE9-compatible build
import Phaser from 'phaser/src/phaser-ie9.js';

// AFTER — just use the standard import
import Phaser from 'phaser';

修正 9: マスク → カメラビューポートまたはマスクフィルター

Phaser 4 では v3 のマスククラスが削除されました。BitmapMask は完全になくなり、 createGeometryMask() も createBitmapMask() もゲームオブジェクトには存在しません。GeometryMask はクラスとしては残っていますが、それを利用するのは（非推奨の）Canvas レンダラーだけです — Beam では何も起きません。

// BEFORE (Phaser 3) — geometry mask via stencil buffer
const shape = this.add.graphics().fillRect(x, y, w, h);
const mask = shape.createGeometryMask();   // removed in v4
targetSprite.setMask(mask);

// AFTER (Phaser 4), rectangular clip — give the content its own camera:
const clipCam = this.cameras.add(x, y, w, h);
clipCam.ignore(this.children.list.filter(c => c !== targetSprite));
this.cameras.main.ignore(targetSprite);

// AFTER (Phaser 4), arbitrary shape — the Mask filter:
targetSprite.enableFilters();                  // filters is null until you call this
targetSprite.filters!.internal.addMask(shape); // texture key or GameObject
targetSprite.filters!.internal.addMask(shape, true);  // inverted

Phaser 4 には camera.setScissor() はありません — そのメソッドは Phaser.Cameras.Scene2D.Camera に存在しません。setViewport() を使用してください。

Phaser.Actions.AddMaskShape() は、Shape を作成し、1 回の呼び出しでマスクとして設定する 便利なメソッドです — これが v3 の Circle FX の代替です。

ステップ 4 — TypeScript 設定を更新する

TypeScript を使用している場合は、tsconfig.json が v4 に対して正しいことを確認します：

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src"]
}

Phaser 4 は自身の package.json 内の exports マップを通じて型を公開しているため、 モダンなリゾルバーであれば、追加の設定なしで import Phaser from 'phaser'; からそのまま型を 取得できます。

v3 の tsconfig に typeRoots: ["./node_modules/phaser/types"] と types: ["Phaser"] がある場合は 削除してください。 Phaser 4 に対してこのペアは TS2688: Cannot find type definition file for 'Phaser' で失敗します — v4 は 1 つの types/phaser.d.ts ファイルを同梱しており、これは有効な type-root パッケージではありません。

ステップ 5 — 検証とテスト

# Type check — must pass with 0 errors
npx tsc --noEmit

# Start dev server and check browser console
npm run dev

ブラウザで確認します：

1. 起動時にコンソールエラーがないこと
2. すべてのシーンが正しく読み込まれること
3. 物理演算が v3 と同じように動作すること
4. アニメーションが正しく再生されること

クイック移行チェックリスト

• npm install phaser を実行済み
• tsconfig.json の v3 時代の typeRoots + types: ["Phaser"] を削除済み。moduleResolution は bundler/node16
• すべての Phaser.Geom.Point を Phaser.Math.Vector2 に置換済み
• すべての Math.PI2 を Math.TAU に置換済み
• すべての Phaser.Structs.Map/Set をネイティブの Map/Set に置換済み
• すべての DynamicTexture/RenderTexture で、描画後に render() を呼び出している
• 削除されたプラグインへの参照を削除済み (Camera3D、Layer3D、Facebook、旧 Spine)
• TileSprite.setCrop() の呼び出しを置換または削除済み
• Phaser.Create.GenerateTexture を Graphics/テクスチャに置換済み
• phaser-ie9 のインポートを phaser に置換済み
• WebGL マスク (createGeometryMask / createBitmapMask / BitmapMask) をカメラのビューポートまたは filters.internal.addMask() に置換済み。camera.setScissor() の呼び出しがない
• npx tsc --noEmit が通る
• node skills/phaser-playtest/scripts/playtest.mjs --project . が通る — tsc がグリーンでも、移行したゲームが描画されるかどうかは何も保証しません

追加リソース

リファレンスファイル

• references/v3-to-v4-changes.md — Phaser v3→v4 のすべての破壊的変更の完全な変更履歴。レンダラーの内部、非推奨となった API、挙動の違いを含みます
• references/runtime-gotchas.md — クリーンにコンパイルできても、それでも驚かされる挙動: マスキング、アニメーションの状態切り替え、カメラのフォロー、タイルマップの衝突判定、onFloor() のタイミング、シーン間の配線、スケールマネージャー。コンパイラーは満足しているのにゲームがそうでないときに読んでください。
• references/v4-release-notes.md — 4.0.0、4.1.0、4.2.0、4.2.1 で何が出荷されたか、およびそれらの間を移動するときに何を変更すべきか。Phaser 4 のポイントリリースをアップグレードするとき、または追いかけているバグがすでに上流で修正されているかどうかを確認したいときに読んでください。