Godot Physics 3D

3D Physics (Jolt/Native)

High-performance 3D simulation: body choice, CCD, stairs, vehicles, ragdolls, SoftBody — routed through scripts.

NEVER Do

• NEVER move PhysicsBody3D nodes in _process() — Use _physics_process(). Moving bodies outside the physics step causes visual jitter and unreliable collision detection [12, 13].
• NEVER scale collision shapes directly — Scaling physics shapes causes instability, inaccurate normals, and jitter. Use the shape properties (height, radius, size) instead.
• NEVER modify RigidBody3D transforms directly — This ignores the physics solver. Use apply_impulse(), apply_torque(), or the _integrate_forces() callback for safe manipulation [17].
• NEVER use RigidBody3D for platformer player controllers — RigidBody is for objects driven by physics. For refined movement, use CharacterBody3D with move_and_slide() [move_and_slide].
• NEVER leave Continuous CD (CCD) enabled for static meshes — It adds heavy CPU cost. Reserve it for high-speed small objects (bullets) to prevent them from passing through walls.
• NEVER use PhysicsServer3D RIDs without manual cleanup — RIDs are not garbage collected. If you create bodies via the server, you MUST call free_rid() when done to avoid memory leaks.
• NEVER use RayCast3D for precise ground detection on stairs — A single ray is too thin. Use ShapeCast3D with a cylinder or sphere shape to detect walkable steps reliably [Stair Logic].
• NEVER rely on VehicleBody3D for non-racing arcade vehicles — It's a complex sim. For arcade hovercraft or simple cars, a custom CharacterBody3D with Raycasts is often easier to tune.
• NEVER forget to set collision_layer and collision_mask properly — If everything is on layer 1, performance will tank from redundant checks. Categorize your world.
• NEVER use Area3D for high-frequency blocking — Areas are for detection. For walls/barriers, use StaticBody3D to ensure immediate, robust containment.

---

Body / Symptom Decision Tree

MANDATORY — load the script for the chosen row before writing movement or sim code.

Do NOT Load every physics script for one controller.

3D Layer Pitfalls (not a 2D primer)

• Layer = what the object is; mask = what it hits. Name bits in physics_layers_3d_config.gd.
• Do not dump a same-as-2D layers tutorial here; Official Docs cover the shared mental model.

Available Scripts

kinematic_3d_stairs_logic.gd

Procedural stair-step + snap for CharacterBody3D.

shapecast_3d_ground_check.gd

Volume ground/stair detection (rays tunnel).

ragdoll_manager.gd

Animation → PhysicalBone simulation transition, impulses, cleanup.

vehicle_simulation_tuning.gd

VehicleBody3D / VehicleWheel3D arcade vs sim knobs.

soft_body_3d_interaction.gd

SoftBody3D flags, pinning, and Jolt mass/stiffness tuning.

physics_ccd_3d_projectile.gd

CCD / sub-step anti-tunneling for small fast bodies.

physics_server_3d_bullets.gd

RID bullets at scale with mandatory free_rid().

physics_layers_3d_config.gd

Named 3D collision matrix architecture.

custom_gravity_well_3d.gd

Planet / zero-G Area3D gravity priority.

joint_3d_breakage_logic.gd

Joint stress monitoring and procedural snaps.

ray_query_3d_vision.gd

Low-level LOS / AI vision queries.

raycast_visualizer.gd

In-game ray hit/normal debug draw.

Expert Pointers (Jolt)

• Prefer Generic6DOFJoint3D over stacking specialized joints unless you need a specific node UX.
• Ragdoll/vehicle/soft samples live in scripts above — do not expand Create Physical Skeleton editor tutorials in this body.
• Version-specific Jolt/soft-body upgrade steps: migration-notes.md.

Deep dives (on demand)

• Hover ray constraints, Jolt suspension tuning, ragdoll influence blend → expert-3d-constraints.md
• Scripts: hover_constraint_3d.gd, ragdoll_blender.gd

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing work to a peer domain — do not preload the whole lattice.