phaser-debugger

Phaser 4 デバッガー

このスキルは、推測ではなく証拠に基づいて Phaser 4 の問題を診断し修正するために使用します。

ワークフロー

1. 正確な症状、エラーテキスト、スタックトレース、ブラウザー/デバイスのコンテキスト、および可能であれば再現手順を収集します。
2. 編集する前に該当するコードを読みます。ブラックスクリーンの場合は、src/main.ts、シーン登録、シーン遷移、preload のパス、およびブラウザーのコンソール/ネットワークエラーを確認します。
3. Phaser のライフサイクル順序（config、preload、create、update、アセットキー、物理ボディの生成、衝突、入力、シーンの開始/停止状態、描画の depth）を用いて、考えられる根本原因を追跡します。
4. 根本原因に対処する最小限の修正を行います。
5. TypeScript プロジェクトでは npx tsc --noEmit で検証し、可能であればローカルの開発サーバーでスモークテストを行います。

デバッグチェックリスト

• アセットの 404 とテクスチャキーの不一致
• シーンが登録されていない、またはシーンキーが誤っている
• シーンの初期化前に this.physics、this.input、または this.anims を使用している
• 物理なしでオブジェクトを生成したために Arcade ボディが存在しない
• 誤ったオブジェクトまたはグループに対して Collider/overlap を登録している
• アニメーションのキー/フレームの不一致
• depth/alpha/カメラの境界によってオブジェクトが隠れている
• Phaser 4 へアップグレード後に Phaser 3 の API を使用している
• フレームごとのアロケーション、無制限のグループ、オブジェクトプーリングの欠如
• タイマーイベントが追跡されていない — 参照を保持せずに time.addEvent() を呼び出すと、シーンの再起動をまたいで蓄積されます
• 物理グループが明示的に破棄されていない — 進化した武器グループやスポーンフェーズのグループは、clear(true,true) + destroy() を行わないとリークします
• base+modifiers なしのステータス変更 — 2 つのシステムが同じフレームで同じステータスに書き込むと、競合状態の値が生じます
• 文字列の等価性による通知の重複排除 — 正当な短時間の繰り返しイベント（例: 200 ms 以内の 2 回のコイン取得）を破棄してしまいます。代わりに時間ウィンドウによる重複排除を使用してください
• モジュールレベルの定数からサイズ設定されたオーバーレイ/パネルの背景 — 起動時のサイズで固定されます。this.cameras.main.width/height + リサイズリスナーを使用してください

よくあるサイレント障害のカテゴリ

コンソールエラーなしでゲームがフリーズしたり誤動作したりする場合は、references/agent-guidance.md の完全なガイドに頼る前に、これらの迅速な診断パスを使用してください。

サイレントフリーズ（エラーなし）:

// Add to main.ts BEFORE new Phaser.Game(config)
window.onerror = (msg, _src, _line, _col, err) => {
  console.error('GLOBAL ERROR:', msg, err?.stack);
};
window.onunhandledrejection = (ev) => {
  console.error('UNHANDLED REJECTION:', ev.reason);
};

その後、ハードリフレッシュします。以前はサイレントだった障害がログに出力されるようになります。完全なチェックリストは references/agent-guidance.md → Silent Freeze を参照してください。

セッション途中でスポーンが停止する（エラーなし）: プールスロットのリーク — エンティティがカメラビューから外れる際にスロットをリサイクルしていません。スポーン呼び出しに console.log('pool free:', pool.getTotalFree()) を追加してください。値がゼロになりそのままなら、スロットが保持されています。references/agent-guidance.md → Pool Slot Leak を参照してください。

強制アニメーションが 1 フレーム再生されて戻ってしまう: エンティティの update() が 1 ティック後に強制アニメーションを上書きしています。cinematicMode フラグで修正してください。skills/phaser-animation/references/state-machine-patterns.md を参照してください。

速度やステータスが断続的に誤った値にジャンプする: 2 つのシステムが同じフレームで同じステータスを変更しています。base+modifiers パターンを使用してください。references/agent-guidance.md → Race Between Two Systems を参照してください。

スタックしたエンティティの検出が誤って発火する（誤検出または検出漏れ）: 壁を押しているとき body.velocity は 0 を返します。代わりに位置差分のサンプリングを使用してください。references/agent-guidance.md → Stuck Detection Fails を参照してください。

完全なガイダンス

完全な診断プレイブックについては、references/agent-guidance.md を読んでください。これは Claude サブエージェントの定義からコピーされたものですが、ポータブルなスキルとして適用する必要があります。model、color、tools などの Claude 専用フィールドは無視してください。