デバッグの問題

ドメイン固有のデシジョンツリーを使用した体系的なデバッグです。まず症状のカテゴリを識別し、対応するツリーに従います。

カテゴリ検出

ユーザーの症状を適切なツリーにマッピングしてください:

症状のキーワード	カテゴリ
「通り抜ける」「衝突がない」「重なる」「引っかかる」「滑り落ちる」	Physics
「シグナルが発火しない」「接続されていない」「コールバックが呼ばれない」	Signals
「見えない」「表示されない」「背後にある」「ちらつく」「色が違う」	Rendering
「ターゲットに移動しない」「パスが間違っている」「ナビゲーション上で引っかかる」「パスがない」	Navigation
「キーが機能しない」「入力が無視される」「ボタンが違う」「二重入力」	Input

Physics デシジョンツリー

この順序でチェックしてください -- 各ステップはその時点で最も一般的な原因です:

衝突レイヤー/マスクの不一致 (最も一般的):
- 定義されたレイヤー名を確認: physics(action="layers")
- ノードのプロパティを確認:
```
nodes(action="get_property", scene_path="<scene>.tscn", name="<body>", property="collision_layer")
nodes(action="get_property", scene_path="<scene>.tscn", name="<body>", property="collision_mask")
```
- ルール: オブジェクト A がオブジェクト B を検出するのは、A の collision_mask に B の collision_layer と一致するビットがある場合のみです。両方とも正しく設定される必要があります。
CollisionShape2D/3D の欠落:
- シーンツリーを検査: scenes(action="info", scene_path="<scene>.tscn")
- すべてのフィジックスボディと Area に CollisionShape の子があることを確認してください。形状がないボディ = フィジックスに不可視です。
ボディタイプが間違っている:
- StaticBody2D: 動かせない (壁、床)
- CharacterBody2D: move_and_slide() によるプレイヤー/NPC の移動
- RigidBody2D: フィジックス駆動 (発射体、破片)
- よくある間違い: プレイヤーキャラクターに RigidBody2D を使用してから、フィジックスエンジンと戦う
スクリプトの速度の問題:
- スクリプトを読む: scripts(action="read", script_path="res://scripts/<name>.gd")
- move_and_slide() の前に velocity が設定されているか確認
- _physics_process で重力が適用されているか確認 (_process ではなく)
- フレーム独立の移動に delta が使用されているか確認

Signals デシジョンツリー

接続が存在するか?
- すべての接続をリスト表示: signals(action="list", scene_path="<scene>.tscn")
- 接続がない = シグナルは静かに何もしない
シグネチャが一致しているか?
- シグナル定義のパラメータはハンドラー関数のパラメータと一致する必要があります
- signal health_changed(new_hp: int) にはハンドラー func _on_health_changed(new_hp: int) が必要です
- パラメータが余分であるか不足している = Godot がランタイムエラーを出す
シグナルが発火しているか?
- emit_signal() / signal.emit() の前に print("signal emitted") を追加
- 出力されない場合、emit 呼び出しに到達していない (ロジックのバグ)
Callable が有効か?
- コード経由で接続された場合: connect() が実行されるときにターゲットノードが存在する必要があります
- ターゲットが解放された場合、シグナルは無効な callable に発火 = エラー

Rendering デシジョンツリー

可視性:
- visible プロパティ = false? ノードとすべての親を確認 (親が不可視 = 子も不可視)
- modulate.a = 0? (完全に透明)
Z-index:
- Z-index が低いほど Z-index が高いものの背後に描画される
- z_as_relative = true の場合、z_index は親に対する相対値
- Sprite が TileMapLayer の背後? 両方のz_index 値を確認
マテリアル/シェーダー:
- CanvasItemMaterial または ShaderMaterial が外観をオーバーライドしているか?
- シェーダーコンパイルエラーはオブジェクトを不可視にします (Output パネルを確認)
ビューポートの問題:
- SubViewport が更新されていない? render_target_update_mode を確認
- Camera2D がアクティブではない? ビューポートごとに enabled = true の Camera2D は1つだけであるべき

Navigation デシジョンツリー

NavigationRegion のセットアップ:
- NavigationRegion2D/3D がシーンに存在する必要があります
- NavigationPolygon/NavigationMesh リソースが割り当てられている必要があります
ナビゲーションメッシュがベイクされているか?
- メッシュはベイクされている必要があります (エディタで、または bake_navigation_mesh() 経由)
- ベイクされていないメッシュ = 利用可能なパスなし
NavigationAgent の設定:
- path_desired_distance: 次のパスポイントに移動する前にどのくらい近いか
- target_desired_distance: 停止する前にターゲットにどのくらい近いか
- 値が小さすぎる = エージェントが振動します。値が大きすぎる = 不正確
パス計算:
- NavigationAgent.set_target_position() を呼び出してから get_next_path_position() を確認
- 現在位置を返す場合、有効なパスが存在しません (メッシュカバレッジを確認)

Input デシジョンツリー

Input Map:
- アクションをリスト表示: input_map(action="list")
- project.godot の [input] セクションを確認
アクション名が一致しているか:
- Input.is_action_pressed("jump") -- 正確な文字列一致が必要
- アクション名のタイプミス = 静かに false を返す (エラーなし!)
イベント処理:
- _input() vs _unhandled_input() -- 別のノードがイベントを消費する場合、_unhandled_input は発火しません
- set_process_input(false) はそのノード上の _input() を無効にします
競合:
- 同じキーに2つのアクション = 両方発火
- UI 要素 (Button、LineEdit) はゲームノードの前に入力イベントを消費

診断ステップ

すべてのカテゴリについて:

シーンツリーを検査: scenes(action="info", scene_path="<scene>.tscn")
関連するスクリプトを読む: scripts(action="read", script_path="res://scripts/<name>.gd")
プロパティを確認: nodes(action="get_property", scene_path="<scene>.tscn", name="<node_path>", property="<name>")
シーンを実行: project(action="run", scene_path="<scene>.tscn") してエラーをチェック
結果を報告: 根本原因と具体的な修正を提示 (プロパティ変更、ノードの欠落、スクリプト編集)

使用するタイミング

Godot での「動作しない」デバッグシナリオ
原因が明らかでない場合の体系的な排除
フィジックス、シグナル、レンダリング、ナビゲーション、または入力の正しいセットアップを検証する

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

debug-issue

SKILL.md 本文

デバッグの問題

カテゴリ検出

Physics デシジョンツリー

Signals デシジョンツリー

Rendering デシジョンツリー

Navigation デシジョンツリー

Input デシジョンツリー

診断ステップ

使用するタイミング

詳細情報