godot-ai-navigation

デシジョンツリー（必ず読むスクリプトのトリガー）

1. Node エージェントと NavigationServer RID の選択

シグナル	選択肢	経路探索スクリプト（必ず読む）
2D のトップダウン／横スクロール、エージェント数が約 50 未満、エディターで調整可能	CharacterBody2D 上の NavigationAgent2D	smart_navigation_agent.gd
3D の床／斜面のナビゲーション、エージェント数が約 50 未満、デザイナーが配置したリージョン	CharacterBody3D 上の NavigationAgent3D	同じスクリプト（3D ブランチ）。ボディの衝突には godot-physics-3d を組み合わせます
数百〜数千の単純な移動体（2D または 3D）	NavigationServer 上の RID エージェント	server_navigation_setup.gd + low_level_avoidance.gd
エージェントが動けなくなる／ジッターが発生する	ターゲットを頻繁に変更する前に、スタックからの復帰を行う	agent_stuck_detection.gd

2. ベイクと障害物の選択

シグナル	選択肢	経路探索スクリプト（必ず読む）
歩行可能なジオメトリが変化した（プロシージャル生成、ドアなど）	非同期で解析してベイク	async_dynamic_baking.gd
動くプラットフォーム／移動するリージョン	動的リージョンマネージャー	dynamic_nav_manager.gd
エージェントを押す飛翔体／転がるハザード	RVO 障害物（全体の再ベイクは不要）	moving_obstacle_server.gd
泥／水より道路を優先する	リージョンの進入コスト／移動コスト	terrain_cost_manager.gd

3. レイヤー、リンク、群衆

シグナル	選択肢	経路探索スクリプト（必ず読む）
歩行／飛行／水泳（または陣営）のフィルター	ナビゲーションレイヤーのビットマスク	layer_mask_navigation.gd
ジャンプ／テレポート／エレベーターの接続	NavigationLink の通過	nav_link_traversal.gd
フォーメーション／群衆の密集防止	リーダー基準のオフセット	group_avoidance_formations.gd
ホットパスでのクエリ割り当て	クエリのパラメーター／結果オブジェクトを再利用	memory_optimized_queries.gd

選択した行以外のスクリプトは読み込まないでください（例：デザイナーが調整する単一のエージェントでは RID／サーバースクリプトを省略し、RVO 障害物だけが動く場合は非同期ベイクを省略します）。

4. 追跡／巡回の再ターゲットポリシー（AI レイヤー）

• 追跡：タイマー（約0.2秒）または距離のしきい値に応じて再ターゲットします。物理フレームごとに target_position を設定してはいけません。
• 巡回：is_navigation_finished() かつ is_target_reachable() の場合にのみウェイポイントを進めます。到達不能な場合は、次のウェイポイントを選ぶか、経路を再計算します。
• 状態の所有者：巡回／追跡／捜索の遷移は godot-state-machine-advanced の担当です。このスキルでは、状態から目的地が要求されたときに、どのように再ターゲットするかだけを決定します。

巡回状態からの引き渡し（呼び出し箇所）： 巡回状態の _physics_process でエージェントがウェイポイントに到達したら、retarget_if_needed(next_waypoint) を呼び出します。ステートマシンのルートから target_position を直接設定してはいけません。

# PatrolState.gd — state machine owns transitions; this skill owns retarget policy
func _physics_process(_delta: float) -> void:
	if nav_agent.is_navigation_finished() and nav_agent.is_target_reachable():
		_ai_nav.retarget_if_needed(_waypoints[_index])
		_index = (_index + 1) % _waypoints.size()

# Threshold retarget — AI policy, not per-frame path spam
const RETARGET_DIST := 1.5
var _last_target: Vector3

func retarget_if_needed(desired: Vector3) -> void:
	if desired.distance_to(_last_target) < RETARGET_DIST:
		return
	nav_agent.target_position = desired
	_last_target = desired

AI ナビゲーションで絶対にしてはいけないこと

• 物理フレームを待つ前に target_position を設定してはいけません — 必ず call_deferred() を呼び出してから await get_tree().physics_frame を実行してください。
• 実行時に同期ベイクを使用してはいけません — パスファインディングの async_dynamic_baking.gd を介して bake_from_source_geometry_data_async を使用してください。
• 毎フレーム、追跡対象をポーリングしてはいけません — 経路の再計算が過剰に発生します。
• ここにローカルの重複したナビゲーションスクリプトを作成してはいけません — godot-navigation-pathfinding のみを使って実装してください。
• is_target_reachable() ／スタック復旧を無視してはいけません — 到達不能または停止したエージェントにはポリシーが必要です（agent_stuck_detection.gd）。
• avoidance_enabled が有効なときに回避半径を0のままにしてはいけません — エージェント同士がすり抜けます。
• 毎フレーム get_path() を呼び出してはいけません — 経路クエリーオブジェクトを再利用してください（memory_optimized_queries.gd）。

フォールバック（godot-navigation-pathfinding がインストールされていない場合）

関連スキルを利用できない場合は、以下の最小限のスタック復旧チェックリストを使用してください。ベイク／RID のチュートリアル一式を記憶から貼り付けてはいけません。

1. 最初の target_position は、call_deferred と await get_tree().physics_frame を使って遅延設定します。
2. タイマー（約0.2秒）または距離のしきい値に応じて再ターゲットします。毎フレーム行ってはいけません。
3. 停止した場合：!nav_agent.is_target_reachable() が成立する、または速度がNフレームにわたって約0の場合は、ウェイポイントをスキップするか、get_next_path_position() による復旧を呼び出します。
4. 回避：avoidance_enabled が有効な場合は radius > 0 に設定します。
5. 非同期ベイクまたは RID の群集機能をリリースする前に、godot-navigation-pathfinding を再インストールしてください。

エキスパートの知見（理由 — 本文に残すこと）

• 最初のターゲットを遅延設定する — 理由：NavigationAgent のマップ／リージョンは _ready() 時点では準備できていません。call_deferred と await physics_frame を使うと、最初の経路探索の失敗を防げます。
• 再ターゲットポリシー — 理由：フレームごとに target_position を設定すると経路が再ベイクされ、CPU 使用率が急上昇します。タイマー（約0.2秒）または距離のしきい値のみを使用してください。
• 到達不能なウェイポイント — 理由：is_target_reachable() と、スキップ／経路再計算のポリシーがないと、巡回ループが永久に停止します。
• 回避半径が0 — 理由：回避を有効にしても半径が0の場合、分離が無効になり、エージェントが重なります。

推奨手順

1. 上記の判断ツリーを使って、AI のニーズを分類します。
2. 選択した行に関連する各パスファインディングスクリプトを開くことが必須です。そのスキルの残りのスクリプトは読み込まないでください。
3. 再ターゲット／状態のポリシー（タイマー／しきい値とステートマシン）はここで組み込み、移動には CharacterBody を使用します。
4. 初回のリージョンベイク UI が必要な場合を除き、公式ドキュメントの導入用レシピは読み込まないでください（参考リンクを使用します）。

詳細なレシピ（必要に応じて）

トピック	参考資料／スクリプト
追跡／巡回／群集 AI のレシピ	ai-movement-recipes.md

参考資料

段階的開示：特定の API を調査するときだけ公式ドキュメントのリンクを開き、関連ドメインに移るときは関連スキルを読み込みます。スキル全体を事前に読み込まないでください。

公式ドキュメント

• ナビゲーションの概要 — クラスのページを詳しく見る前に、マップ、リージョン、エージェント、メッシュ、リンク、障害物、パフォーマンスに関するチュートリアルを確認できます。
• ナビゲーション入門（2D） — NavigationRegion2D + NavigationAgent2D の最小構成、歩行可能なポリゴンのベイク、初回フレームの準備完了について説明します。
• ナビゲーション入門（3D） — NavigationRegion3D / NavigationAgent3D を使った同様の 3D 初期設定と、メッシュのベイクに関する注意点を説明します。
• NavigationAgent の使用 — target_position、get_next_path_position、回避半径、velocity_computed による安全な速度の処理について、追跡／巡回 AI の例を交えて説明します。
• NavigationServer の使用 — ノードを使わない群衆や大規模なカスタムサーバー構成向けの RID マップ／リージョン／エージェントについて説明します。
• ナビゲーションメッシュの使用 — ソースジオメトリの解析／ベイク、非同期ベイク、動的な切り抜きのための投影障害物について説明します。
• NavigationRegion の使用 — テレインの通行コスト設定に関する、リージョンの所有権、進入／移動コスト、チャンク単位／実行時のリージョン更新について説明します。
• NavigationObstacle の使用 — フレームごとにメッシュ全体を再生成せずに、RVO による障害物の押し出しとベイク時の切り抜きを行う方法を説明します。
• NavigationLink の使用 — ジャンプ／テレポート／エレベーターの経路と、エージェントによる手動のリンク移動について説明します。
• ナビゲーションレイヤーの使用 — 歩行／飛行／水泳（または陣営）による経路フィルターに使う 32 ビットのレイヤービットマスクについて説明します。
• ナビゲーション経路クエリーオブジェクトの使用 — 群衆でフレームごとの GC を避けるために NavigationPathQueryParameters/Result を再利用する方法を説明します。
• ナビゲーションパフォーマンスの最適化 — 大規模な AI 集団向けのベイクコスト、エージェント／障害物の数、サーバークエリーの予算について説明します。

関連スキル

前提条件

• godot-navigation-pathfinding — 必須の信頼できる NavigationServer スクリプト（非同期ベイク、RID 設定、クエリーの再利用、スタック検出）が含まれています。このスキルにはローカルの scripts/ はありません。
• godot-characterbody-2d — 経路のコーナーは move_and_slide によって CharacterBody の速度になります。エージェントのスクリプトは、親がボディであることを前提としています。
• godot-2d-physics — コリジョンレイヤー／シェイプは引き続きボディを遮ります。ナビゲーションメッシュは、壁やトリガーの物理演算の代わりにはなりません。
• godot-physics-3d — 3D エージェントも同じ役割分担に従います。経路は NavigationServer が扱い、コリジョンや斜面は RigidBody/CharacterBody が扱います。

補完

• godot-raycasting-queries — 視線判定、照準範囲、命中予測は、追跡／ステルス AI の経路探索を補完します。
• godot-state-machine-advanced — 巡回／追跡／捜索の各状態が、NavigationAgent のターゲットをいつ変更するか、いつ停止するかを管理します。
• godot-tilemap-mastery — 2D レベルでは、TileMap／TileSet のジオメトリが NavigationPolygon のベイクに使われることがよくあります。
• godot-3d-world-building — 静的メッシュと GridMap は、ベイク済み領域の NavigationMesh のソースジオメトリとして一般的に使われます。
• godot-procedural-generation — 実行時に生成したレイアウトには、生成後に parse と bake_from_source_geometry_data_async が必要です。
• godot-signal-architecture — AI システムがポーリングではなく型付きシグナルを発行すれば、velocity_computed／navigation_finished の接続をすっきり保てます。

下流／利用側

• godot-genre-rts — ユニットの移動指示と RVO 群衆は、NavigationAgent／Server のパターンを直接利用します。
• godot-genre-tower-defense — レーン／経路上の敵と動的な障害物は、領域、コスト、障害物の更新に依存します。
• godot-genre-stealth — ガードの巡回と調査地点は、検知状態によって制御される NavigationAgent の経路です。
• godot-combat-system — 交戦／引き撃ち／側面攻撃時の移動では、経路に基づく新たなターゲット指定と、行き詰まりからの復帰が必要です。
• godot-monte-carlo-balancer — AI の難易度調整時に、追跡対象へ到達できるか、移動時間の範囲、群衆の圧力をシミュレートします。

マスター

• godot-master — このドメインスキルのライブラリルーター兼ミラー化されたモジュールエントリです。