phaser-best-practices

Phaser ゲームの構築

このスキルを使う場面

ユーザーが次のことを希望している場合に、このスキルを使います。

• 新しい Phaser 3 ゲームやプロトタイプを作成する
• シーン、エンティティ、UI、物理演算、タイルマップ、入力、オーディオ、カメラを追加またはリファクタリングする
• シーンの再起動、ぼやけたピクセルアート、コライダーの不具合、アセットの読み込み問題、アニメーションの問題など、Phaser 固有の動作をデバッグする
• Phaser プロジェクトのアーキテクチャ、保守性、実行時パフォーマンスを改善する

ユーザーが Phaser 風のパターンを他の環境向けに応用することを明示的に希望している場合を除き、Phaser 以外のエンジンにはこのスキルを使わないでください。

進め方

1. 依頼を分類する

コードを書く前に、タスクを分類します。

• 新規プロジェクト：スキャフォールディング、フォルダー構成、ゲーム設定、最初のシーン
• 機能開発：ゲームプレイ、UI、オーディオ、トランジション、タイルマップ、敵、アイテムの追加
• バグ修正：シーンのライフサイクル、アセット、物理演算、入力、カメラ、レンダリングの問題を切り分ける
• 最適化：ボトルネックのプロファイリング、プーリング、カリング、スロットリング、アセット戦略
• アート／アセットパイプライン：スプライトシートの寸法、アニメーション設定、ナインスライス／スリースライス UI、タイルマップの統合

2. まず調査し、その後に判断する

既存のリポジトリがある場合は、構成の変更を提案する前に調査します。

• package.json、バンドラー設定、tsconfig/jsconfig
• Phaser のバージョンと、コードベースが JS か TS か
• ゲームの起動処理、シーン一覧、物理演算の設定、スケールの設定
• アセットフォルダーと命名規則
• 現在の状態共有方法（シーンデータ、レジストリー、サービス、グローバル）
• プロジェクトがピクセルアート、HD アート、デスクトップ優先、モバイル優先、または複合入力向けかどうか

ボイラープレートに置き換えるよりも、既存のコードベースに合わせることを優先してください。

3. 技術選択のデフォルト

タスクで別の選択が明らかに適切な場合を除き、次の設定をデフォルトとして使います。

• 新規プロジェクトには、公式の Vite + TypeScript スタイルのセットアップを優先する
• プラットフォーマー、シューティング、見下ろし型アクション、簡単なアイテム取得、軽量な衝突判定には Arcade Physics を優先する
• 回転による衝突、複合ボディ、拘束、積み重ねの安定性、またはより現実的なシミュレーションが必要な場合に限り、Matter Physics を使う
• コードはまず シーンを中心に構成し、各シーン内にエンティティ／システムを配置する
• 入力はシーンが所有するものとし、エンティティは独自のリスナーを登録せず、入力状態を利用する
• 複数のスプライトで同じアニメーションデータを共有する場合は、グローバルアニメーションを使う
• 起動に必須のアセットは事前に読み込み、起動時間の短縮につながる場合はレベル固有のアセットを後から読み込む
• テクスチャのレイアウトが対応している場合、スケーラブルな UI アートには組み込みの NineSlice / ThreeSlice を使う。透明な余白や不連続なアートによって組み込みのスライス処理がうまく機能しない場合に限り、カスタム合成に切り替える
• ほとんどのゲームではスケーリングに FIT を使い、エディターのようなレイアウトや UI が中心のレイアウトでは RESIZE を使う。NONE はキャンバスサイズを手動で制御する場合に限り使う
• ピクセルアートでは pixelArt モードを有効にし、可能な限り整数倍のスケーリングを優先して、カメラのサブピクセル移動を避ける

4. 出力の要件

新しいゲームでは、次の内容を提示します。

• 推奨するフォルダー構成
• ゲーム設定
• シーン一覧と各シーンの役割
• 実行できるスターターコード
• 各アーキテクチャ上の選択が、依頼されたジャンルに適している理由の説明

機能開発またはバグ修正では、次の内容を提示します。

• 対象を絞った最小限の変更
• 根本原因の説明
• パッチ
• ユーザーがすぐに実行できる検証手順

アーキテクチャに関するアドバイスでは、次の内容を提示します。

• 現在の問題を解決する最小限の構成
• 選択肢を同等に並べるのではなく、推奨する方法を1つ提示する
• 選択が重要な場合は、明確なトレードオフを説明する（たとえば Arcade と Matter の比較）

妥協できない実装ルール

• ユーザーから移行を求められない限り、プロジェクトで既に採用されている JS と TS の選択を尊重してください
• シーンキー、アセットキー、衝突カテゴリ、バランス調整用定数を一元管理してください
• update() は処理のオーケストレーションに専念させ、詳細なロジックはエンティティまたはシステムに移してください
• リスナー、タイマー、トゥイーン、または長期間保持される参照を設定した場合、シーンのシャットダウン／破棄時にクリーンアップを登録してください
• プロファイリングで問題がないと確認できない限り、頻繁に実行される update() ループ内で新しいオブジェクトを作成しないでください
• すべてのオブジェクトをデフォルトでインタラクティブまたは物理演算有効にしないでください
• スプライトシートのフレーム寸法を推測せず、確認して検証してください
• Arcade で問題なく解決できる場合に、Matter を使うようユーザーに勧めないでください
• 便利だからという理由だけで、ゲーム全体を 1 つの Boot シーンにプリロードしないでください

推奨される開発ワークフロー

Phaser プロジェクトの新規作成

1. アーキテクチャの規模を選択します：
   • 小規模／ゲームジャム向け：2〜4 個のシーン、軽量なサービスモジュール
   • 中規模ゲーム：シーン + エンティティ + システム + 定数
   • 大規模なコンテンツ重視のゲーム：データ駆動型コンテンツ、シーンサービス、専用の状態レイヤー
2. 基本設定を定義します：レンダラー、スケールモード、物理演算、ピクセルアート設定
3. まず起動時のシーンを作成します：Boot、Menu、Game、UI。Pause／GameOver は必要な場合にのみ追加します
4. コアとなるゲームループが機能することを実証する垂直スライスを 1 つ追加します
5. 次に、参考資料に基づくシステムを追加します：オーディオ、保存可能な状態、敵のスポーン、タイルマップ、UI の仕上げ

機能の追加またはリファクタリング

1. 担当するシーンと影響を受けるシステムを特定します
2. 正しく実装できる最小の挿入箇所を特定します
3. 既存のヘルパー、定数、マネージャー、プールを再利用します
4. 変更とあわせてクリーンアップと検証の手順を追加します
5. シーンを安全に再起動できる状態を維持します

デバッグ

1. コードと設定から問題を再現します
2. 問題が次のどれに該当するかを特定します：
   • ライフサイクル／再起動
   • アセットの寸法またはローダーの設定
   • 物理ボディの設定またはコライダーの順序
   • スケール／カメラ／ピクセルの丸め
   • 古いリスナー、タイマー、またはプールされたオブジェクトの状態
3. 症状だけでなく、根本原因を修正します
4. 簡単な再現手順または検証チェックリストを提示します

参考資料マップ

タスクに関連するファイルだけを読んでください：

• セットアップ／ブートストラップ／設定：references/setup-and-build.md
• シーン／共有状態／アーキテクチャ：references/scenes-state-architecture.md
• 物理演算／エンティティ／プーリング：references/physics-and-entities.md
• アセット／アニメーション／UI パネル：references/assets-animation-ui.md
• タイルマップ／カメラ／入力／オーディオ：references/tilemaps-camera-input-audio.md
• パフォーマンス／デバッグ／クリーンアップ：references/performance-debugging.md
• コードレビュー／アーキテクチャのチェックリスト：references/review-checklist.md

具体例

例：「Phaser でトップダウンシューティングゲームを作成する」

このスキルを使用してください。デフォルトでは次を採用します：

• Vite + TypeScript の構成
• Arcade Physics
• Boot、Menu、Game、UI の各シーン
• シーンが所有する入力マッピング
• 弾丸のプーリング
• グローバルアニメーション
• カメラ追従とワールド境界
• 定数内のアセットキー／シーンキー

そのうえで、実行可能なスターターコードと、最初にプレイできるゲームループを提供します。

例：「モバイルでピクセルアートがぼやけます」

このスキルを使用してください。次を確認します：

• pixelArt と roundPixels の設定
• カメラ追従時の丸め処理
• スケールモードとズーム方法
• キャンバスコンテナー周辺の CSS
• アートが整数倍ではない倍率で拡大されていないか

そのうえで、必要最小限の設定とカメラ設定を修正します。

例：「Paper UI のパネルに奇妙なサイドバーが表示される」

このスキルを使用してください。まず、元のテクスチャを調べてください。次に、以下を行ってください。

• アートが本当に 3 スライスまたは 9 スライスのレイアウトであれば、組み込みの ThreeSlice / NineSlice を試してください
• フレームに大きな透明の余白がある場合や、アートが不連続な場合は、トリミングしたスライスまたは合成した代替スライスを使用してください
• 測定したフレームサイズ、間隔、マージン、使用したオーバーラップを記録してください

よくある落とし穴

ユーザーが明示的に希望しない限り、以下は避けてください。

• メニュー、HUD、ゲームプレイ、一時停止、画面遷移をすべて管理する巨大な GameScene
• window、ランダムなモジュールグローバル、または場当たり的なシングルトンの寄せ集めに状態を保存すること
• エンティティがキーボードリスナーを所有すること
• シャットダウン時のクリーンアップ漏れによるシーン再起動時の不具合
• 今後使用するすべてのアセットを最初のシーンで読み込むこと
• 組み込みの NineSlice がアセットに適しているのに、手動でナインスライスを構成すること
• 少数のエンティティクラスで十分な小規模ゲームに ECS を導入するなど、過剰に設計すること

回答前の最終確認

回答が以下を満たしていることを確認してください。

• ユーザーのジャンル、プラットフォーム、アートスタイルに合っている
• Phaser 4 RC API ではなく、Phaser 3 API を使用している
• 物理システムを意図的に選択している
• SKILL.md レベルのアドバイスは簡潔に保ち、詳細はリファレンスに記載している
• コードを作成した場合、検証手順が含まれている