godot-raycasting-queries

利用可能なスクリプト

一般的なケースでは必須 — 実装前にお読みください（クエリ API を記憶に頼って即興で使わないでください）。

• direct_space_state_raycast.gd — RayCast ノードを使わない、高頻度の intersect_ray。
• query_exclusion_optimization.gd — キャスターが自身に衝突しないようにする RID 除外リスト。
• shapecast_ground_detection.gd — 細いレイがすり抜けたり見落としたりする場合の、足元検出／ボリュームキャスト。

以下のすべてのスクリプトを、1 つのタスクのために読み込まないでください。判断表に一致する項目だけを開いてください。

direct_space_state_raycast.gd

高頻度クエリでノードベースのオーバーヘッドを回避するための、PhysicsDirectSpaceState2D/3D の高度な使い方です。

shapecast_ground_detection.gd

細いレイの代わりにボリュームベースの ShapeCast を使用した、信頼性の高い接地／足元検出です。

multiple_hit_piercing_ray.gd

1 回のライン照射で複数のヒットを検出して返す、貫通弾の実装です。

field_of_view_scanner.gd

扇状のレイキャストを使って FOV コーン内のターゲットを検出する、AI センサーのロジックです。

raycast_reflection_logic.gd

衝突法線の反射を使って、レーザーや弾丸の跳ね返りを計算します。

point_in_shape_query.gd

単一の点で重なっている物理ボディを確認します（爆発の中心点）。

rest_info_3d_stuck_fix.gd

get_rest_info を使ってスタックしたオブジェクトを検出し、重なりをすぐに解消します。

mouse_pick_3d_query.gd

ポイント＆クリック操作のために、2D 画面座標を 3D ワールドのレイに変換します。

water_buoyancy_surface_calc.gd

上から下へのレイキャストを使って、浮力システム用の水面の高さを調べます。

query_exclusion_optimization.gd

特定の RID（リソース ID）を交差判定から除外して、パフォーマンスを最適化します。

物理クエリで絶対にしてはいけないこと

• _physics_process() の外で direct_space_state に絶対にアクセスしないでください — 物理空間はロックされている場合や別スレッドで実行されている場合があるため、_process() でのクエリは安全ではありません [1, 2]。
• 細い RayCast で十分な場合に、絶対に ShapeCast を使わないでください — ボリュームクエリは大幅に高コストです。体積検出が必要な場合を除き、レイを使用してください [3, 4]。
• 結果が CollisionObject ノードを返すと絶対に想定しないでください — CSG シェイプ、GridMap、TileMapLayer は汎用の物理ボディではなく、それ自体を返します [5, 6]。
• RayCast ノードが即座に更新されると絶対に想定しないでください — 更新は物理フレームごとに 1 回です。ノードを移動してすぐにクエリする場合は、必ず force_raycast_update() を呼び出してください [3, 9]。
• 物理クエリに複雑なビジュアルメッシュを絶対に使わないでください — GPU 専用データの解析には、高コストなスレッドロックが必要です。簡略化したプリミティブのコリジョンシェイプを使ってください [10, 11]。
• 最初の有効なヒットを見つけるために結果を走査しないでください — 最大限のパフォーマンスを得るには、サーバー側でクエリをフィルタリングする collision_mask と collision_layer を使ってください。
• キャスターの除外を絶対に忘れないでください — キャラクターの中心から始まるレイは、キャラクター自身にヒットします。query.exclude = [self.get_rid()] を使ってください [20]。
• 小さく高速に移動する検出領域に、絶対にレイを使わないでください — フレームレートが低下すると、レイが薄い壁を「すり抜ける」ことがあります。弾丸には cast_motion または高頻度のステップ処理を使ってください。
• GDScript で 1000 本以上のレイを個別にクエリしないでください — クエリ数が極端に多くなる場合は、クエリをまとめるか、C++ で PhysicsServer を直接使ってください。
• result.rid を絶対に無視しないでください — RID を使えば、ノードパスを検索せずにオブジェクトを特定し、後続のクエリから除外できます [20]。

クエリ種別の判断表

質問に答えられる中で、最もコストの低い API を選びます。レイ／シェイプには必ず RID の除外とマスクを組み合わせてください（query_exclusion_optimization.gd）。

必要なもの	優先する API	コスト	使用する場面	スクリプト
シーン内の永続的なセンサー（段差、エイムアシストのデバッグ）	RayCast2D/RayCast3D ノード	低〜中	キャスト数が少ない場合。物理フレームを 1 回待てる場合（または force_raycast_update() を使用する場合）	シーンノード + NEVER ルール
ヒットスキャン／LOS／フレーム途中の単発レイ	PhysicsDirectSpaceState*.intersect_ray	低	高頻度で使用し、永続的なノードが不要な場合	必須 direct_space_state_raycast.gd
接地、厚い壁、近接攻撃のボリューム	ShapeCast* / intersect_shape	中〜高	細いレイがすり抜ける場合や、ボリュームを捉えられない場合	必須 shapecast_ground_detection.gd
爆発／ある点の占有判定	intersect_point	低〜中	爆心地の重なり一覧を取得する場合	point_in_shape_query.gd
引っかかり／貫通の解消	get_rest_info	中	重なりからの回復	rest_info_3d_stuck_fix.gd
貫通／直線上の複数ヒット	intersect_ray を繰り返し、RID を除外	中	そのまま進み続ける弾丸	multiple_hit_piercing_ray.gd
画面座標 → ワールド座標のクリック	カメラの投影 + intersect_ray	低	ピッキング	mouse_pick_3d_query.gd

---

3D マウスピッキングの例

func screen_point_to_ray():
    var space_state = get_world_3d().direct_space_state
    var mouse_pos = get_viewport().get_mouse_position()
    
    var origin = project_ray_origin(mouse_pos)
    var end = origin + project_ray_normal(mouse_pos) * 2000
    
    var query = PhysicsRayQueryParameters3D.create(origin, end)
    var result = space_state.intersect_ray(query)
    
    if result:
        return result.collider
    return null

---

上級者向け：理由（クエリのタイミングと LOS）

• 物理ステップのみ — _process ではなく、_physics_process 内で direct_space_state を使用します。
• 自身へのヒット — キャラクターの中心からレイを飛ばす場合は、query.exclude = [get_rid()] を設定します。
• NavMesh の LOS — 物理レイと、くり抜かれたナビゲーション用の穴は同じではありません。厳密にメッシュの LOS を判定するには、NavigationServer3D.map_get_path の path.size() == 2 を使用してください（詳しくは「詳細」を参照）。
• サーフェスタイプ — デカールや足音には、クラス／グループのチェックより collider.get_meta(&"surface_type") が適しています。
• GPU レイの計算 — 対象外です。ゲームプレイで使う intersect_ray の代わりにはなりません。

詳細（必要に応じて読み込み）

NavMesh の LOS 検証、サーフェスメタデータ、ピッキングの基本、すり抜けに関する注意事項 — references/query-elite-patterns.md。

リファレンス

段階的開示：特定の API を調査するときにのみ公式ドキュメントへのリンクを開いてください。 作業を別の専門領域の担当者に割り当てるときは関連スキルを読み込み、スキルの全体を事前に読み込まないでください。

公式ドキュメント

• レイキャスト — ノード RayCast* と PhysicsDirectSpaceState* クエリの違い、結果の辞書、自己ヒットを防ぐための exclude。
• 物理の概要 — 物理サーバーでのすべてのレイ、シェイプ、ポイントクエリをフィルタリングするコリジョンレイヤー／マスク。
• コリジョンシェイプ（3D） — 信頼性が高く低コストな交差判定を行うには、ビジュアルメッシュではなくプリミティブ／凸シェイプがクエリに必要な理由。
• PhysicsDirectSpaceState3D — フレーム途中の空間クエリにおける intersect_ray ／ intersect_shape ／ intersect_point ／ get_rest_info ／ cast_motion の仕様。
• PhysicsDirectSpaceState2D — 永続的なキャストノードを使わずに、視線判定、ヒットスキャン、ポイント中心判定を行うための、直接空間クエリの2D版。
• PhysicsRayQueryParameters3D — 再利用可能なレイパラメーターオブジェクトのマスク、除外する RID、hit_from_inside、衝突対象フラグ。
• PhysicsShapeQueryParameters3D — ボリュームキャスト、静止情報、スタックした重なりの解消に使うシェイプ RID とトランスフォームの設定。
• PhysicsPointQueryParameters3D — 爆発の中心位置や占有状態の確認に使う、シェイプ内のポイント重なりリスト。
• RayCast3D — シーンツリーのキャストノード、衝突例外、移動後に force_raycast_update() が必要となる場合。
• ShapeCast3D — 細いレイでは検出できない足場／近接攻撃の検出に使うボリュームキャストと force_shapecast_update()。
• Camera3D — アクティブなカメラから画面上の位置をワールドに変換するピッキングレイに使う project_ray_origin ／ project_ray_normal。
• マウスと入力座標 — ピッキングレイを作成する前に確認する、ビューポートのマウス位置とキャンバス／ワールド空間の違い。

関連スキル

前提条件

• godot-project-foundations — クエリマスクと水／地面のレイヤービットの整合性を保つには、名前付きの物理レイヤーとティック設定があらかじめ必要です。
• godot-gdscript-mastery — 型付きクエリパラメーター、RID 配列、_physics_process 内でのみ空間にアクセスすることは、このスキルが前提とする言語レベルの仕様です。
• godot-2d-physics — 2D のボディ／エリアのレイヤーマトリックスと、センサーに RayCast2D ノードと直接空間状態のどちらを優先するか。

補完

• godot-physics-3d — 3D のボディタイプ、CCD、衝突設定によって、レイやシェイプキャストが実際に何に当たるかが決まります。
• godot-characterbody-2d — 接地、段差、コヨーテタイムの感触は、このドメインの ShapeCast／レイによる足元の判定結果を利用することがよくあります。
• godot-input-handling — 物理ステップごとのクリック／照準のサンプリングは、マウスピック用のレイやヒットスキャンのタイミングと連動します。
• godot-navigation-pathfinding — 物理演算による LOS と NavMesh の経路直線性チェックでは、障害物の切り抜きと衝突ワールドの一貫性を保ちます。
• godot-ai-navigation — 視野角の扇形と視覚センサーは AI の知覚スタックにデータを送りますが、適切なクエリマスク／除外設定が必要です。
• godot-performance-optimization — 数百本のレイの予算管理、クエリパラメーターの再利用、ノードキャストが SceneTree のオーバーヘッドになるタイミングの把握に役立ちます。
• godot-debugging-profiling — キャストの線や形状を可視化し、マスク、除外、更新タイミングの誤りによるヒット漏れを診断します。

下流／利用側

• godot-combat-system — ヒットスキャン、貫通レイ、近接攻撃の判定領域は、ここで得られるクエリ結果を基にダメージを解決します。
• godot-genre-shooter — ヒットスキャン武器、弾丸の貫通、エイムアシストは、除外／マスクの設定パターンと複数ヒットの貫通ループを利用します。
• godot-monte-carlo-balancer — 視距離、視野角のレイ数、貫通時の最大ヒット数、クエリの更新頻度は、公平性と難易度を変えます。推測するのではなく、それらのパラメーターをシミュレーションしましょう。

マスター

• godot-master — ライブラリのルーターであり、関連ドメインと併せてレイキャスト／クエリのパターンを見つけるためのミラー化されたエントリーポイントです。