godot-physics-3d

Original：🇺🇸 English

Translated

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.

1installs

Sourcethedivergentai/gd-agentic-skills

Added on2026-03-04

NPX Install

npx skill4agent add thedivergentai/gd-agentic-skills godot-physics-3d

SKILL.md Content

View Translation Comparison →

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:

Select Skeleton3D.
Click "Create Physical Skeleton" in top menu.
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

gdscript

# simple_ragdoll.gd
extends Skeleton3D

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

Reference

Master Skill: godot-master