godot-physics-3d

name	godot-physics-3d
description	Expert patterns for Godot 3D physics (Jolt/PhysX), including Ragdolls, PhysicalBones, Joint3D constraints, RayCasting optimizations, and collision layers. Use for rigid body simulations, character physics, or complex interactions. Trigger keywords: RigidBody3D, PhysicalBone3D, Jolt, Ragdoll, Skeleton3D, Joint3D, PinJoint3D, HingeJoint3D, Generic6DOFJoint3D, RayCast3D, PhysicsDirectSpaceState3D.

3D Physics (Jolt/Native)

Expert guidance for high-performance 3D physics and ragdolls.

NEVER Do

• NEVER scale RigidBody3D — Scale collision shapes, NEVER the body itself. Non-uniform scaling breaks physics engines logic.
• NEVER use move_and_slide inside _process — Always use _physics_process. Frame-rate dependency kills simulation stability.
• NEVER simulate ragdolls 24/7 — Only enable physical bones on death or impact. Animate static meshes otherwise to save CPU.
• NEVER ignore Jolt — Godot Jolt plugin is strictly superior to default Godot Physics in 4.x for stability and performance. Use it if possible.
• NEVER use ConcaveCollisionShape3D for dynamic bodies — Concave shapes (Trimesh) are for static ground only. Moving bodies MUST be Convex or Primitive (Box/Capsule).

---

Available Scripts

ragdoll_manager.gd

Expert manager for transitioning Skeleton3D from animation to physical simulation (death effect). Handles impulse application and cleanup.

raycast_visualizer.gd

Debug tool to visualize hit points and normals of RayCast3D in game.

Core Architecture

1. Layers & Masks (3D)

Same as 2D:

• Layer: What object IS.
• Mask: What object HITS.

2. Physical Bones (Ragdolls)

Godot uses PhysicalBone3D nodes attached to Skeleton3D bones. To setup:

1. Select Skeleton3D.
2. Click "Create Physical Skeleton" in top menu.
3. This generates PhysicalBone3D nodes.

3. Jolt Joints

Use Generic6DOFJoint3D for almost everything. It covers hinge, slider, and ball-socket needs with simpler configuration than specific nodes.

---

Ragdoll Implementation

# simple_ragdoll.gd
extends Skeleton3D

func start_ragdoll() -> void:
    physical_bones_start_simulation()
    
func stop_ragdoll() -> void:
    physical_bones_stop_simulation()

Related

• Master Skill: godot-master
• reverse-engineering — Physics → vehicle behavior chain tracing: collision layers, raycasts, tire model, forces