godot-navigation-pathfinding

ナビゲーションと経路探索で絶対にしてはいけないこと

• 物理フレームを待機する前にtarget_positionを設定しないでください — _ready()ではNavigationServerの準備ができていませんか？　パスはエラーなく失敗します。必ずcall_deferred()を呼び出してからawait get_tree().physics_frameを実行してください。
• 実行時にNavigationRegion2D.bake_navigation_polygon()を使わないでください — 同期ベイキングはゲームを100ミリ秒以上停止させます。カクつきのない更新にはNavigationServer.bake_from_source_geometry_data_async()を使ってください。
• is_navigation_finished()の確認を忘れないでください — 目標に到達した後にget_next_path_position()を呼び出すと、古いパスが返され、AIが以前の位置に向かって歩きます。
• 半径を設定せずにavoidance_enabledを使わないでください — デフォルトの半径は0なので、エージェント同士がすり抜けます。適切な回避のためにnav_agent.radius = collision_shape.radiusを設定してください。
• 追跡AIで毎フレームtarget_positionを確認しないでください — 1秒間に60回目標を設定すると、パスの再計算が頻発します。更新にはタイマー（0.2秒間隔）または距離しきい値を使ってください。
• パスが存在すると決めつけないでください — 目標に到達できない場合（壁に阻まれているなど）、get_next_path_position()は無効な値を返します。is_target_reachable()を確認するか、パスの長さを検証してください。
• 単純なエンティティが数千個ある場合、ノードベースの重いナビゲーションを使わないでください — ノードのオーバーヘッドを回避するには、NavigationServer3D/2DのRIDを直接使ってください。
• 毎フレームget_path()を呼び出さないでください — ヒープの大量割り当てとGC負荷を防ぐため、再利用するNavigationPathQueryResultオブジェクトとquery_path()を使ってください。
• ペナルティの大きいエリアで'enter_cost'を0のままにしないでください — コストを設定して、AIが幾何学的に最短の距離だけでなく、論理的な経路（沼地より道路など）を選ぶようにしてください。
• agent_set_avoidance_callbackを無視しないでください — 同期の問題や動きの「揺れ」を避けるため、安全な速度を計算するコールバックを必ず使ってください。

判断ツリー → スクリプト

選択したパスでは必須です。このスキル本文からエディター導入／公式ドキュメントの初期設定レシピを読み込まないでください（リージョンの初回設定が必要な場合は、Referenceリンクを使ってください）。

必要なもの	スクリプト
実行時／手続き型ベイキングを停止なしで実行	必須 async_dynamic_baking.gd
エージェントの停止／揺れからの復帰	必須 agent_stuck_detection.gd
ノードを使わない高数のRVO	必須 low_level_avoidance.gd
移動プラットフォーム／動的リージョン	dynamic_nav_manager.gd
RIDのみのマップ／リージョン	server_navigation_setup.gd
再利用可能なパスクエリーオブジェクト	memory_optimized_queries.gd
地形の進入／移動コスト	terrain_cost_manager.gd
RVO障害物としての飛翔体	moving_obstacle_server.gd
リンク（ジャンプ／テレポート／エレベーター）	nav_link_traversal.gd
歩行／飛行／水泳レイヤー	layer_mask_navigation.gd
群衆隊形のオフセット	group_avoidance_formations.gd
サーバーRVOの群衆エージェント（ノードなし）	crowd_agent_3d.gd
動的ナビメッシュの切り抜き（衝撃による穴）	nav_mesh_carver_3d.gd
ベイク時間のベンチマーク	navmesh_profiler.gd
スマートエージェントのラッパー	smart_navigation_agent.gd

追跡／再ターゲットのルール（「絶対にしてはいけないこと」と矛盾させないでください）

物理フレームごとにtarget_positionを設定しないでください。タイマー（約0.2秒）で、または追跡対象のボディが距離しきい値を超えて移動したときに、再ターゲットしてください。

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

func _physics_process(_delta: float) -> void:
    var desired := prey.global_position
    if desired.distance_to(_last_target) >= RETARGET_DIST:
        nav_agent.target_position = desired
        _last_target = desired
    if nav_agent.is_navigation_finished():
        return
    var next := nav_agent.get_next_path_position()
    velocity = (next - global_position).normalized() * speed
    move_and_slide()

利用可能なスクリプト

async_dynamic_baking.gd

bake_from_source_geometry_data_async — メインスレッドで解析し、別スレッドでベイクします。

agent_stuck_detection.gd

時間経過に伴う距離に基づいて停滞を検出し、復帰させます。

low_level_avoidance.gd

サーバー側のRVOエージェントと回避コールバック。

dynamic_nav_manager.gd

動くプラットフォームに対応したランタイムでのナビメッシュ更新。

server_navigation_setup.gd

NavigationServer RID を使った、ノードなしのマップ／リージョン。

memory_optimized_queries.gd

パス検索のパラメーター／結果オブジェクトを再利用します。

terrain_cost_manager.gd

優先ルートに対する enter_cost ／ travel_cost。

moving_obstacle_server.gd

全面的な再ベイクなしで動的なRVO障害物を扱います。

nav_link_traversal.gd

NavigationLink によるジャンプ／テレポート／エレベーターの処理。

layer_mask_navigation.gd

複数領域のナビゲーションレイヤー（歩行／飛行／水泳）。

group_avoidance_formations.gd

密集を抑える、リーダー相対のオフセット。

smart_navigation_agent.gd

本番環境向けの NavigationAgent ラッパーのパターン。

エキスパート向けのヒント

• 最初の NavigationRegion のベイク UI については、公式ドキュメントの導入を優先してください。このスキルでは、非同期ベイク、サーバーRVO、コスト、スタック状態からの復帰を扱います。
• シンプルなエージェントが数千体いる場合は、NavigationAgent ノードを1体ずつ用意するのではなく、RID サーバー方式（server_navigation_setup.gd + low_level_avoidance.gd）を使用します。
• 群衆RVO／カービング／ベイクのベンチマークサンプル → crowd_agent_3d.gd、nav_mesh_carver_3d.gd、navmesh_profiler.gd

詳細（必要に応じて）

• 2D／3Dの追跡、パトロール、回避シグナル → agent-movement-patterns.md
• サーバーRVO群衆、投影カービング、ベイクのベンチマーク → expert-nav-architectures.md

参考資料

段階的な開示：特定のAPIを調べる場合にのみ公式ドキュメントへのリンクを開いてください。 関連スキルは、関連分野へ作業を割り当てる場合に読み込んでください。全体をあらかじめ読み込まないでください。

公式ドキュメント

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

関連スキル

前提条件

• 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-performance-optimization — 群衆の処理では、このスキルで取り上げるサーバー RID、クエリの再利用、回避動作の調整が重要になります。

下流／利用側

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

マスター

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