godot-2d-physics

2D 物理

Godot 2D の衝突検出、トリガー、レイキャストに関する専門的なガイダンスです。

絶対にしないこと

• CollisionShape2D ノードを絶対に拡大縮小しないでください — エディターでシェイプハンドルを使い、Node2D のスケールプロパティは使わないでください。拡大縮小すると、予測不能な物理挙動や不正な衝突法線が発生します [12]。
• collision_layer と collision_mask を絶対に混同しないでください — Layer は「自分は何か」、Mask は「何を検出するか」です。通常、両方に同じ値を設定するのは誤りです [13]。
• move_and_slide() を使うとき、速度に delta を絶対に掛けないでください — move_and_slide() は時間刻みを自動的に考慮します。delta を掛けるのは重力や加速度だけです [14]。
• フレーム途中でレイキャストを手動実行するとき、force_raycast_update() を絶対に忘れないでください — レイキャストは物理フレームごとに1回更新されます。target_position を変更した場合は、必ず更新を強制してください [15]。
• 毎フレーム get_overlapping_bodies() を絶対に使わないでください — 負荷が高いため、代わりに body_entered／body_exited シグナルで結果をキャッシュしてください [16]。
• _process で RigidBody2D の状態を絶対に直接変更しないでください — PhysicsDirectBodyState2D に安全かつ同期的にアクセスするには、_integrate_forces() を使ってください [17, 411]。
• _process() で PhysicsBody2D ノードを絶対に動かさないでください — _physics_process() を使ってください。物理ステップの外でボディを動かすと、動きがカクつき、衝突検出の信頼性が低下します。
• 1000個以上の単純なエンティティに RigidBody2D を絶対に使わないでください — PhysicsServer2D を使えば、ノードのオーバーヘッドを回避して大幅にパフォーマンスを向上できます（群れ／弾丸）[18, 397]。
• 高頻度のブロッキング処理（弾丸）に Area2D を絶対に使わないでください — Area のシグナルは遅延することがあります。フレーム単位で正確な結果を得るには、move_and_collide() または ShapeCast2D を使ってください [19]。
• リフレッシュレートの高いモニターで「物理ジッター」を絶対に無視しないでください — 物理補間を有効にして、動きの微細なカクつきを防いでください [21, 400]。
• 実行時に衝突シェイプを直接拡大縮小しないでください — 深刻な不安定化を引き起こします。代わりに、シェイプリソースのサイズや半径を変更してください。
• 物理トランスフォームを即時に処理するロジックに set_deferred を絶対に使わないでください — フレームの最後に実行されます。代わりに force_raycast_update() または PhysicsServer2D を使ってください。
• 低速のオブジェクトで連続衝突検出（CCD）を絶対に有効にしたままにしないでください — CPU 負荷が大幅に増加します。トンネリングを防ぐため、高速の飛翔体に限定して使用してください。
• すべてのタイル／エンティティに単一の衝突レイヤーを絶対に使わないでください — Ground、Walls、Enemies などにレイヤーを分け、マスクによる選択的なフィルタリングを可能にしてください。
• PhysicsServer2D の RID を手動で解放するのを絶対に忘れないでください — RID はガベージコレクションされないため、メモリリークが恒久的に発生します。

---

利用可能なスクリプト

必須：コーディングを始める前に、作業する分岐に対応するスクリプトを読んでください。Query／Area のクックブックサンプルはこの本文ではなく、スクリプト内にあります。

ワークフロールーター（必須／読み込まない）

分岐	読み込む	読み込まない
レイヤー／マスクのマトリクス設定	collision_bitmask_helper.gd または collision_setup.gd；マトリクスのポリシー → collision_layer_matrix_manager.gd	群れ／CCD スクリプト
LOS／視野コーン	raycast_vision_stack.gd（ノードレスのレイには physics_direct_query.gd も使用）	shapecast_aoe*.gd、physics_server_swarm.gd
AOE／近接攻撃ボリューム	優先 shapecast_aoe.gd（陣営マスク）；地面／ボリュームの検知 → shapecast_aoe_detection.gd	Area2D の大量使用＋溶岩 DoT のチュートリアル；同じ機能に両方の shapecast スクリプトを読み込まない
ヒットスキャン／ポイント選択／単発シェイプ	physics_queries.gd（標準）。専用スクリプト：physics_direct_space_query.gd（LOS の bool 値）、raycast_hit_prediction.gd	3 つすべてのクエリーヘルパーを一度に読み込まない
弾幕／1000 体以上のボディ	必須 physics_server_swarm.gd（RID シェイプには physics_server_direct_body.gd も使用）	弾ごとの Area2D／RigidBody2D ノード
高速移動時のすり抜け	continuous_collision_detection.gd ＋ substepping_logic.gd	低速の小道具に CCD を適用
RigidBody の安全な変更	safe_rigidbody_state.gd（_integrate_forces）	_process でトランスフォームを直接書き換える
カスタム CharacterBody 力	custom_physics_2d.gd	custom_physics.gd（このファイルは RigidBody の _integrate_forces 用）
重力ゾーン	custom_gravity_area.gd（Area のオーバーライド）または custom_gravity_override.gd（キャラクターの重量／ゾーン）	Area とキャラクターの両方の経路が必要な場合を除き、両方を読み込まない
オーバーラップシグナルの大量発生	collision_debouncer.gd	毎フレーム get_overlapping_bodies をポーリングする
複合マルチシェイプ RID	compound_body_sync.gd	1 つの論理ボディに複数のノードを使用
接触法線のデバッグ	collision_visual_debugger.gd	表示される衝突メニューだけでは不十分
高リフレッシュレート時のジッター	優先 jitter_interpolation_fix.gd	physics_interpolation_smoothing.gd（レガシー／手動；組み込みの補間が利用できない場合のみ）
高精度のバウンス／スライド	move_and_collide_precision.gd	—
静的オブジェクトの一括移動	performance_batch_mover.gd	—
クエリー結果のキャッシュ	physics_query_cache.gd	同じフレーム内でスペースクエリーを重複実行

標準と重複（重複排除ガイド）

• ShapeCast AOE：戦闘の AOE には shapecast_aoe.gd を読み込みます。shapecast_aoe_detection.gd は接地／ボリュームのチェックに限って使用します。同じ機能に両方を使用しないでください。
• スペースクエリー：まず physics_queries.gd を使用します。該当する専用スクリプトがある場合に限り、physics_direct_query.gd／physics_direct_space_query.gd を追加します。
• カスタム物理演算：CharacterBody → custom_physics_2d.gd；RigidBody の積分処理 → custom_physics.gd。
• 補間：physics_interpolation_smoothing.gd より jitter_interpolation_fix.gd を優先します。

スクリプト一覧

• collision_setup.gd / collision_bitmask_helper.gd / collision_layer_matrix_manager.gd
• physics_queries.gd / physics_direct_query.gd / physics_direct_space_query.gd / physics_query_cache.gd
• raycast_vision_stack.gd / raycast_hit_prediction.gd
• shapecast_aoe.gd / shapecast_aoe_detection.gd
• physics_server_swarm.gd / physics_server_direct_body.gd
• continuous_collision_detection.gd / substepping_logic.gd
• safe_rigidbody_state.gd / custom_physics.gd / custom_physics_2d.gd
• custom_gravity_area.gd / custom_gravity_override.gd
• collision_debouncer.gd / jitter_interpolation_fix.gd
• compound_body_sync.gd / collision_visual_debugger.gd
• move_and_collide_precision.gd / performance_batch_mover.gd
• physics_interpolation_smoothing.gd — レガシー版です。jitter fix script を推奨します。

---

衝突検出方法の判断ツリー

用途	方法	理由／スクリプト
継続的なトリガーゾーン	Area2D + シグナル	対象の記憶を保持します。collision_debouncer.gd でデバウンスします
1回限りのアイテム取得	Area2D + 入場時に queue_free	簡単にクリーンアップできます
視線判定	RayCast2D / 直接レイ	raycast_vision_stack.gd または physics_direct_query.gd
クリックして選択	PhysicsPointQueryParameters2D	physics_queries.gd
範囲攻撃の呪文／近接攻撃の範囲	ShapeCast2D / シェイプクエリ	shapecast_aoe.gd（Area のシグナル遅延を回避）
即時ヒット武器	PhysicsRayQueryParameters2D	physics_queries.gd / raycast_hit_prediction.gd
プラットフォーマーの接地／足場の縁	下方向へのレイまたは ShapeCast	CharacterBody スキル + shapecast_aoe_detection.gd
1000個以上の飛翔体	PhysicsServer2D RIDs	必須 physics_server_swarm.gd

---

メンタルモデル（簡潔に）

• Layer = 自分が何者か、Mask = 何を検出するか。ビットマスクの実例集 → collision-layers-masks.md。
• 複数のシェイプを持つ Area2D は、シェイプごとに 1回ずつ body_entered を発行します。Set／dict または collision_debouncer.gd で重複を除去してください。
• フレーム途中でレイ／シェイプを変更した場合は、force_raycast_update() / force_shapecast_update() が必要です。
• _ready での物理クエリは、物理フレームの後まで false になります（await get_tree().physics_frame）。
• CharacterBody2D は collision_layer = 0 で提供されるため、レイヤーを設定するまで Area から認識されません。
• PhysicsServer の RID は自分で解放してください。GC の対象にはなりません。

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

トピック	リファレンス／スクリプト
Layer／Mask のパターン	collision-layers-masks.md
Area2D、レイキャスト、シェイプクエリ	area2d-and-queries.md
複合 RID ボディ	compound_body_sync.gd
接触法線のデバッグ描画	collision_visual_debugger.gd

リファレンス

段階的な情報開示：特定の API を調べる場合にのみ公式ドキュメントのリンクを開いてください。 作業を関連分野の担当に引き継ぐ際は、関連スキルを読み込んでください。関連スキル全体を事前に読み込まないでください。

公式ドキュメント

• 物理演算の概要 — 衝突レイヤーとマスク、ボディタイプ、あらゆる 2D 設定の基盤となる基本的な考え方。
• 衝突形状（2D） — 形状を正しく設定する方法と、CollisionShape2D ノードを拡大縮小すると法線と接触判定が崩れる理由。
• CharacterBody2D の使用 — move_and_slide / move_and_collide、床の検出、キネマティック移動の仕様。
• Area2D の使用 — トリガーの監視、重なり合いのシグナル、ゾーンの空間／重力オーバーライド。
• レイキャスティング — RayCast2D と PhysicsDirectSpaceState2D のレイの違い、除外設定、フレーム途中での force_raycast_update。
• RigidBody — _process でソルバーと競合するのではなく、_integrate_forces / PhysicsDirectBodyState2D を使ってリジッドボディを安全に制御する方法。
• 物理演算の問題のトラブルシューティング — すり抜け、ジッター、片方向プラットフォーム、レイヤー／マスクのよくある設定ミス。
• 物理補間の概要 — 高リフレッシュレートのディスプレイで固定物理ティックがカクつく理由と、補間で解消できる場合。
• PhysicsServer2D — SceneTree のオーバーヘッドなしで、大量の 2D 物理演算を実現する RID ベースのボディ／形状 API。
• PhysicsDirectSpaceState2D — 常設のクエリノードを使わずに、視線判定、範囲攻撃、クリック選択を行うための点・レイ・形状クエリ。
• ShapeCast2D — Area2D のシグナル遅延が許容できない場合に、フレーム単位で正確な近接攻撃／範囲攻撃の検出を行うボリュームキャスト。

関連スキル

前提条件

• godot-project-foundations — レイヤー／マスクの対応表を適切に保つには、プロジェクト設定のレイヤー名、物理ティック、デフォルト重力を設定しておく必要があります。
• godot-gdscript-mastery — ビットマスク列挙型、重なり合いの集合を扱う型付き辞書、_physics_process の適切な運用が、ここで紹介するすべてのパターンの基盤となります。
• godot-signal-architecture — body_entered / body_exited の接続とデバウンスのパターンでは、シグナルの所有権を明確にして、過剰な通知を防ぐ必要があります。

補完

• godot-characterbody-2d — コヨーテタイム、ジャンプバッファ、片方向プラットフォームは、このスキルで定義される衝突の契約に基づいて動作します。
• godot-raycasting-queries — ビジョン／ヒットスキャンシステムが基本を超えて拡張されたときに役立つ、クエリパラメーターの詳細な設定例（除外、マスク、シェイプキャスト）を紹介します。
• godot-tilemap-mastery — タイルの物理レイヤーと片方向タイルの衝突には、ボディやエリアに使われるものと同じレイヤーマトリックスが必要です。
• godot-input-handling — 物理ステップでの入力サンプリングと VSync／レイテンシーの選択は、move_and_slide の操作感に密接に関係します。
• godot-physics-3d — 移植時や次元をまたいでレイヤーポリシーを共有する際に役立つ、3D ボディ／クエリの並行概念を紹介します。
• godot-performance-optimization — PhysicsServer2D の大量処理やクエリキャッシュがボトルネックになったときに役立つ、プロファイリングとバッチ処理の指針を紹介します。
• godot-debugging-profiling — ジッターやヒット漏れの原因を調べる際に役立つ、衝突シェイプの可視化、接触法線、フレーム時間の注意点を紹介します。

下流／利用側

• godot-combat-system — ヒットボックス／ハートボックスは Area2D とレイヤー／マスクの組み合わせで構成されます。ダメージのタイミングは、オーバーラップと CCD の選択を引き継ぎます。
• godot-genre-platformer — プラットフォーマーの操作感（床、足場の端、片方向プラットフォーム）は、この領域の CharacterBody2D と衝突設定を利用します。
• godot-navigation-pathfinding — エージェントにも、障害物と LOS のための物理レイヤーが必要です。ナビメッシュと衝突ワールドの整合性を保ってください。
• godot-monte-carlo-balancer — ジャンプ可能時間、弾速／CCD、重力、ヒットボックスのサイズは、勝率と難易度曲線を直接変化させます。推測ではなく、これらの物理パラメーターをシミュレーションしてください。

マスター

• godot-master — 2D 物理と関連領域を見つけるための、ライブラリルーター兼ミラーエントリーポイントです。