godot-physics-3d

3D 物理演算（Jolt／ネイティブ）

高性能な3Dシミュレーション：ボディの選択、CCD、階段、乗り物、ラグドール、SoftBody — スクリプト経由で制御します。

絶対にしてはいけないこと

• PhysicsBody3D ノードを _process() で絶対に動かさないでください — _physics_process() を使用してください。物理ステップ外でボディを動かすと、見た目がガタつき、衝突検出の信頼性が低下します [12, 13]。
• コリジョンシェイプを直接スケーリングしないでください — 物理シェイプをスケーリングすると、不安定さ、不正確な法線、ガタつきが発生します。代わりに shape プロパティ（高さ、半径、サイズ）を使用してください。
• RigidBody3D のトランスフォームを直接変更しないでください — 物理ソルバーを無視することになります。安全に操作するには、apply_impulse()、apply_torque()、または _integrate_forces() コールバックを使用してください [17]。
• プラットフォーマーのプレイヤーコントローラーに RigidBody3D を使用しないでください — RigidBody は物理演算で動かすオブジェクト向けです。動きを細かく調整するには、move_and_slide() を使う CharacterBody3D を使用してください [move_and_slide]。
• 静的メッシュで Continuous CD（CCD）を有効にしたままにしないでください — CPU 負荷が大幅に増加します。壁をすり抜けないようにするため、高速で小さなオブジェクト（弾丸）に限定して使用してください。
• 手動で解放せずに PhysicsServer3D の RID を使用しないでください — RID はガベージコレクションされません。サーバー経由でボディを作成した場合、メモリリークを防ぐため、使用後に必ず free_rid() を呼び出してください。
• 階段での正確な地面判定に RayCast3D を使用しないでください — 単一のレイでは細すぎます。歩行可能な段差を確実に検出するには、円柱または球形状の ShapeCast3D を使用してください [階段のロジック]。
• レース用途以外のアーケード系の乗り物に VehicleBody3D を使用しないでください — 複雑なシミュレーション向けです。アーケード系ホバークラフトやシンプルな車には、Raycast を使った独自の CharacterBody3D のほうが調整しやすいことがよくあります。
• collision_layer と collision_mask を適切に設定し忘れないでください — すべてをレイヤー 1 にすると、重複したチェックによってパフォーマンスが大きく低下します。ワールドを分類してください。
• 高頻度のブロック処理に Area3D を使用しないでください — Area は検出用です。壁や障壁には、即時かつ堅牢に封じ込められる StaticBody3D を使用してください。

---

ボディ／症状の選択ツリー

必須 — 移動またはシミュレーションのコードを書く前に、選択した行のスクリプトを読み込んでください。

禁止：1つのコントローラーのために、すべての物理スクリプトを読み込まないでください。

必要な機能／症状	ボディ／API	スクリプト
プレイヤーの移動、階段、斜面	CharacterBody3D	必須 kinematic_3d_stairs_logic.gd + shapecast_3d_ground_check.gd
破片、小道具、インパルスで動くオブジェクト	RigidBody3D	禁止 + インパルスを使用。レイヤーは physics_layers_3d_config.gd を参照
レース／車輪付きのシミュレーション	VehicleBody3D	必須 vehicle_simulation_tuning.gd
アーケード系ホバー／シンプルな車	独自の CharacterBody3D + レイ	階段／レイのスクリプトを優先してください。VehicleBody 全体の使用は避けてください
死亡／物理ポーズへのブレンド	PhysicalBone3D / Skeleton	必須 ragdoll_manager.gd
マント、柔らかい布、柔らかい葉	SoftBody3D	必須 soft_body_3d_interaction.gd
すり抜ける弾丸	CCD / サーバー弾丸	必須 physics_ccd_3d_projectile.gd または physics_server_3d_bullets.gd
ジョイントの破断／破壊可能オブジェクト	Joint3D の応力	joint_3d_breakage_logic.gd
重力井戸／無重力	Area の優先度	custom_gravity_well_3d.gd
視線判定（LOS）／AI の視覚	直接スペースステート	ray_query_3d_vision.gd
デバッグ用のヒット法線	ビジュアライザー	raycast_visualizer.gd

3D レイヤーの落とし穴（2D の入門ではありません）

• レイヤー = オブジェクトが 何であるか、マスク = オブジェクトが 何に当たるか です。ビットの名前は physics_layers_3d_config.gd で定義します。
• ここで 2D と同じ内容のレイヤーのチュートリアルを長々と説明しないでください。共通の考え方については公式ドキュメントで説明されています。

利用可能なスクリプト

kinematic_3d_stairs_logic.gd

CharacterBody3D 用の、手続き型の階段昇降とスナップ処理です。

shapecast_3d_ground_check.gd

ボリュームによる地面／階段の検出です（レイはすり抜けます）。

ragdoll_manager.gd

アニメーションから PhysicalBone シミュレーションへの切り替え、インパルス、クリーンアップを行います。

vehicle_simulation_tuning.gd

VehicleBody3D / VehicleWheel3D のアーケード向け／シミュレーション向け設定項目です。

soft_body_3d_interaction.gd

SoftBody3D のフラグ、ピン留め、Jolt の質量／剛性の調整を扱います。

physics_ccd_3d_projectile.gd

小型で高速なボディがすり抜けるのを防ぐ CCD ／サブステップ処理です。

physics_server_3d_bullets.gd

多数の RID 弾を扱います。free_rid() の呼び出しが必須です。

physics_layers_3d_config.gd

名前付き 3D 衝突マトリックスの設計です。

custom_gravity_well_3d.gd

惑星／ゼロ G 環境での Area3D の重力優先度を扱います。

joint_3d_breakage_logic.gd

ジョイントの応力監視と手続き型の破断処理です。

ray_query_3d_vision.gd

低レベルの視線判定／AI の視覚クエリです。

raycast_visualizer.gd

ゲーム内でレイのヒット位置／法線をデバッグ描画します。

エキスパート向けのヒント（Jolt）

• 特定のノード操作性が必要な場合を除き、専用ジョイントを重ねるより Generic6DOFJoint3D を優先してください。
• ラグドール／乗り物／ソフトボディのサンプルは上記のスクリプトにあります。この本文では「物理スケルトンを作成」するエディターチュートリアルを追加しないでください。
• Jolt／ソフトボディのバージョン固有のアップグレード手順については、migration-notes.md を参照してください。

詳細情報（必要に応じて）

• ホバーレイの拘束、Jolt のサスペンション調整、ラグドールの影響度ブレンド → expert-3d-constraints.md
• スクリプト：hover_constraint_3d.gd、ragdoll_blender.gd

リファレンス

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

公式ドキュメント

• 物理演算の概要 — レイヤーとマスクの違い、ボディの種類、あらゆる3D設定の基礎となる2D／3D共通の衝突モデルについて説明します。
• 衝突形状（3D） — プリミティブ形状と凸形状／凹形状の違い、CollisionShape3D をスケーリングすると法線や接触が崩れる理由について説明します。
• Jolt Physics の使用 — エンジンの切り替え、Godot Physics とのジョイントプロパティの違い、安定した3Dシミュレーションのためのプロジェクト設定上の注意点について説明します。
• RigidBody の使用 — フレームごとのトランスフォーム変更でソルバーに干渉せず、力、衝撃、_integrate_forces を使って安全に制御する方法について説明します。
• ラグドールシステム — 死亡時のシミュレーションやアニメーションと物理演算の切り替えに向けた、PhysicalBoneSimulator3D ／ PhysicalBone3D の設定について説明します。
• SoftBody3D の使用 — 布や旗の変形、ピン留め、ソフトボディの堅牢性に Jolt が推奨される理由について説明します。
• レイキャスト — RayCast3D と PhysicsDirectSpaceState3D クエリの違い、除外設定、物理演算のティック中の空間アクセスについて説明します。
• 物理演算の問題のトラブルシューティング — トンネリング、ジッター、CCD の誤用、レイヤー／マスクのよくある設定ミスについて説明します。
• 物理演算補間の概要 — 高リフレッシュレートのディスプレイで固定物理演算ティックがカクつく理由と、補間で3Dの動きが滑らかになる状況について説明します。
• PhysicsServer3D — 群れ規模の大量の飛翔体向け RID ベースのボディ／形状 API と、必須の free_rid によるクリーンアップについて説明します。
• PhysicsDirectSpaceState3D — 常設のクエリノードを使わずに、視線判定、ホバー制約、独自サスペンションを実現するレイ／形状／点クエリについて説明します。
• ShapeCast3D — 細い RayCast3D では段差や凹凸のある床を検出できない場合の、階段／地面検出用のボリュームキャストについて説明します。

関連スキル

前提条件

• godot-project-foundations — 行列の設定や Jolt の調整を適切に行うには、事前に3D物理エンジンの選択、ティックレート、重力、名前付きレイヤービットを設定する必要があります。
• godot-gdscript-mastery — 型付き RID、ビットマスク列挙型、_physics_process の適切な扱いは、ここで紹介するサーバー側のパターンや CharacterBody3D のパターンの基礎となります。
• godot-signal-architecture — body_entered ／接触モニターの接続は、Area3D の重力井戸や CCD による衝突でシグナルが過剰に発行されないよう、所有権を明確にする必要があります。

補完

• godot-2d-physics — 複数の次元にまたがってポリシーを共有するときや、メカニクスを移植するときに、レイヤー／マスクとボディタイプの契約を並行して参照します。
• godot-raycasting-queries — ビジョン／ヒットスキャンシステムが基本を超えて複雑になったときに役立つ、クエリパラメーターの詳しいレシピ（マスク、除外、シェイプキャスト）です。
• godot-3d-world-building — GridMap／CSG／メッシュから生成される静的コリジョンは、キャラクターや飛翔体に適用されるものと同じ3Dレイヤーマトリックスに合わせる必要があります。
• godot-animation-tree-mastery — AnimationTreeのポーズとステートマシンは、ラグドールの開始／停止やPhysicalBoneSimulator3Dでの影響ブレンディングに関わります。
• godot-performance-optimization — PhysicsServer3Dの群れ、ソフトボディ、CCDの数がボトルネックになったときに役立つ、プロファイリングとプーリングの指針です。
• godot-debugging-profiling — ジッター、トンネリング、階段の判定漏れを調査するときに役立つ、コリジョンシェイプの可視化、接触法線、プロファイラーの落とし穴について説明します。

下流／利用側

• godot-combat-system — 3Dヒットボックス／ハートボックスと飛翔体のCCDは、この領域のレイヤー／マスクと空間クエリの選択を引き継ぎます。
• godot-genre-racing — VehicleBody3Dのサスペンション／摩擦の調整とドリフトの感触には、ここでの車両およびJoltの指針が使われます。
• godot-genre-shooter-fps — ヒットスキャンのレイ、CharacterBody3Dの移動、高速飛翔体のCCDは、これらの契約を直接利用します。
• godot-navigation-pathfinding — エージェントには遮蔽物やLOSのための物理レイヤーも必要です。ナビゲーションメッシュとコリジョンワールドの一貫性を保ってください。
• godot-monte-carlo-balancer — 重力、CCD、ジョイントの破断しきい値、ヒットボックスのサイズは勝率を変化させるため、推測ではなく、これらの物理パラメーターをシミュレーションしてください。

マスター

• godot-master — ライブラリーのルーターであり、関連領域とともに3D物理を見つけるためのミラー化されたエントリーポイントです。