Physics System in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

> Related skills: player-controller for CharacterBody2D/3D movement patterns, component-system for hitbox/hurtbox composition, godot-optimization for physics performance tuning, camera-system for camera follow and interpolation, multiplayer-sync for networked physics, 2d-essentials for tile collision setup and 2D canvas layers.

1. Physics Body Types

Four collision-object types (the last three extend PhysicsBody2D/3D):

| Type | Moved by | Use for | |------|----------|---------| | Area2D/3D | Code | Overlap detection, gravity zones, audio zones | | StaticBody2D/3D | Not moved (or constant_linear_velocity) | Walls, floors, conveyor belts | | RigidBody2D/3D | Physics engine | Crates, projectiles, debris, ragdolls | | CharacterBody2D/3D | Code | Players, enemies, NPCs (see player-controller) |

Every collision object needs at least one CollisionShape2D/3D (or CollisionPolygon2D/3D) child. Jolt Physics is the default 3D engine since 4.4 (non-experimental from 4.6) — see Section 8. 2D always uses GodotPhysics.

> Critical rule: NEVER scale collision shapes or physics bodies via scale. Use the shape's own size parameters (radius, extents, height) — scaling breaks collision accuracy.

2. RigidBody2D/3D

Forces vs Impulses

| Method | Effect | When to use | |---|---|---| | apply_force(force, position) | Continuous accel at point | Thrusters, wind, magnets | | apply_central_force(force) | Continuous accel at center | Gravity, constant push | | apply_impulse(impulse, position) | Instant velocity change at point | Bullet hit, explosion | | apply_central_impulse(impulse) | Instant velocity change at center | Jump, knockback | | apply_torque(torque) | Continuous angular accel | Steering, spinning | | apply_torque_impulse(impulse) | Instant angular velocity change | Impact spin |

> See references/rigidbody-recipes.md for a thrust-and-spin example (GDScript + C#) using apply_force + apply_central_impulse + apply_torque.

_integrate_forces() — Safe Physics Modification

Use _integrate_forces(state) instead of _physics_process() to read/modify a RigidBody's transform, velocity, or angular velocity. Setting position or linear_velocity directly in _physics_process() fights the physics engine.

> Warning: _integrate_forces() is NOT called while the body is sleeping. Set can_sleep = false if you need continuous callbacks; otherwise let bodies sleep for performance.

> See references/rigidbody-recipes.md for the thrust + torque example using state.apply_force / state.apply_torque (GDScript + C#).

Contact Monitoring, PhysicsMaterial, Freeze, look_at

• Contact signals require contact_monitor = true + max_contacts_reported > 0. Then body_entered/body_exited fire.
• PhysicsMaterial resource controls friction (0 ice → 1 rubber) and bounce (0 → 1).
• Freeze modes: FREEZE_MODE_STATIC (acts like a StaticBody) or FREEZE_MODE_KINEMATIC (code-moved, pushes others).
• RigidBody3D orientation: never look_at() a RigidBody — use _integrate_forces and set state.angular_velocity from a cross-product steering term.

> See references/rigidbody-recipes.md for full GDScript + C# recipes (contact handler with take_damage, PhysicsMaterial property table, freeze toggle, RigidBody3D homing-via-angular-velocity).

3. StaticBody2D/3D

StaticBody is not moved by the physics engine but can push other bodies via constant_linear_velocity (e.g. conveyor belts). For platforms that move via code AND push CharacterBodies, use AnimatableBody2D/3D — a code-moved StaticBody won't push CharacterBodies reliably.

> See references/staticbody-recipes.md for the conveyor belt and moving-platform recipes (GDScript + C#, with Tween-driven AnimatableBody2D loop).

4. Area2D/3D

Areas detect overlaps and override physics properties within their bounds. They do NOT produce collision responses — bodies pass through them. Connect body_entered / body_exited for body overlaps; use area_entered / area_exited for Area-to-Area (hitbox vs hurtbox — see component-system). Areas can also override gravity (zero-G zones, point gravity / black holes), linear_damp / angular_damp (water, slow-mo), and redirect audio to a specific AudioBus. When multiple areas overlap, priority decides order; pick a space_override mode (COMBINE, REPLACE, COMBINE_REPLACE, REPLACE_COMBINE).

> See references/area-recipes.md for the GDScript + C# overlap-detection canonical example, the space-override mode reference table, and zero-G + point-gravity recipes.

> ⚠️ Changed in Godot 4.7: With Jolt Physics, Area3D now reports overlaps with SoftBody3D from its signals and methods. Configure collision layers/masks so any unwanted Area3D ↔ SoftBody3D interactions are ignored. See the 4.7 migration guide.

5. Collision Shapes

| Shape (2D / 3D) | Use case | |---|---| | Rectangle / Box | Crates, platforms, rooms | | Circle / Sphere | Balls, projectiles, simple characters, trigger zones | | Capsule (2D & 3D) | Characters — rounded, slides over edges | | Segment2D / — | Thin walls, laser beams | | SeparationRay2D / — | Character ground snapping | | WorldBoundary2D / — | Infinite floor/wall/ceiling | | — / Cylinder3D | Pillars, barrels (Jolt only — unstable on GodotPhysics) |

Prefer primitives for dynamic bodies. ConvexPolygonShape is fast but cannot express holes or inward curves; ConcavePolygonShape is accurate for level geometry but is StaticBody-only and the slowest. Never translate, rotate, or scale a CollisionShape node — an untransformed shape unlocks a broad-phase optimization. Godot 4.7+ adds one_way_collision_direction for sideways one-way platforms.

Convex/concave cost table, shape-generation menus, the full performance rules, and the 4.7+ one-way direction API (GDScript + C#): references/collision-shapes.md

6. Collision Layers and Masks

Godot provides 32 physics layers per dimension (2D and 3D separately).

• collision_layer — which layers this object exists on (others scan for it here)
• collision_mask — which layers this object scans (what it detects)

> Mental model: Layer = "I am", Mask = "I scan for". A collision happens when object A's mask includes object B's layer, OR vice versa.

Name layers in Project Settings → Layer Names → 2D Physics (or 3D Physics); set them in code with set_collision_layer_value(N, true) / set_collision_mask_value(N, true) (1-indexed).

> See references/collision-layers.md for layer naming conventions, bitmask shorthand, Inspector export flags, and the GDScript + C# examples.

7. Raycasting and Physics Queries

RayCast2D/3D Nodes (Simple Per-Frame Rays)

Add a RayCast2D / RayCast3D as a child node — it casts every physics frame automatically. Read with is_colliding() and get_collider() / get_collision_point() / get_collision_normal().

> See references/raycasting-recipes.md for the GDScript + C# RayCast node example.

Code-Based Raycasting (PhysicsDirectSpaceState)

For on-demand queries, access the space state via get_world_2d().direct_space_state (or get_world_3d()) and call intersect_ray(query) with PhysicsRayQueryParameters2D/3D.create(from, to). Set query.exclude = [get_rid()] to skip self, query.collision_mask to filter layers. Only safe inside _physics_process() — the physics space is locked during rendering.

> See references/raycasting-recipes.md for the full GDScript + C# code-based raycast example with self-exclusion and mask filtering, plus the 3D mouse-picking recipe.

Ray Result, Other Queries, 3D Mouse Picking

The intersect_ray result dictionary contains position, normal, collider, collider_id, rid, shape. PhysicsDirectSpaceState also supports intersect_point (overlapping shapes at a point), intersect_shape (area query), cast_motion (shape sweep), collide_shape (contact points), get_rest_info (resting collision info). For 3D mouse picking, Camera3D.project_ray_origin(screen_pos) + project_ray_normal(screen_pos) builds the ray.

> See references/raycasting-recipes.md for the full mouse-picking recipe (GDScript + C#).

8. Jolt Physics

Jolt is a built-in alternative physics engine, the default for new 3D projects since Godot 4.4. (Godot 4.6+) Jolt is no longer marked experimental and is the confirmed stable default for all new 3D projects.

Enabling Jolt

Project Settings → Physics → 3D → Physics Engine → Jolt Physics → Save → Restart editor. (3D only; 2D always uses GodotPhysics.)

Why & Differences

Wins: better stacking stability, reliable CylinderShape3D, better SoftBody3D, optional thread-safe mode, active-edge detection (fixes ghost collisions).

> See references/jolt-differences.md for the behavioral differences from GodotPhysics (stabilization, collision margins, single-body joints, face_index, unsupported joint properties).

> ⚠️ Changed in Godot 4.7: With Jolt Physics, WorldBoundaryShape3D.plane.d now follows the same sign convention as Godot Physics — the plane distance is interpreted with the opposite sign compared to Godot 4.6. Flip the sign yourself to keep the 4.6 behavior. See the 4.7 migration guide.

9. Physics Interpolation

Smooths visual motion between physics ticks, eliminating "staircase" jitter when tick rate ≠ frame rate. Enable in Project Settings → Physics → Common → Physics Interpolation. Godot 4.5+ restructured the 3D interpolation pipeline (RenderingServer → SceneTree) for more accurate results in nested transforms — no API change, automatic improvement on upgrade.

Core Rules

1. Move all game logic to _physics_process() — transforms set outside physics ticks cause jitter
2. Tweens and AnimationPlayer that move physics objects must use physics tick timing
3. Call reset_physics_interpolation() after teleporting or initial placement to prevent "streaking"

> See references/interpolation-tuning.md for the teleport-reset example (GDScript + C#), per-node physics_interpolation_mode control, and tick-rate guidance.

Camera Interpolation

Cameras need special handling under physics interpolation. Make the camera independent (or top_level = true), update it in _process() (not _physics_process()), and read the target's smooth position with get_global_transform_interpolated().

> See references/interpolation-camera.md for the full smooth-follow Camera3D recipe (GDScript + C#).

10. Ragdoll System

Ragdolls replace animation with physics for procedural death, explosions, or limp characters. Generate via Skeleton3D → Skeleton menu → Create Physical Skeleton. Use ConeJoint for shoulders/hips/neck, HingeJoint for elbows/knees — PinJoint (default) tends to crumple. Drive via physical_bones_start_simulation(), blend with Influence.

> See references/ragdoll-recipes.md for setup, joint guidance, full GDScript + C# control, animation blending, and collision exceptions.

11. SoftBody3D

SoftBody3D simulates deformable objects (cloth, capes, jelly). Mesh subdivision drives the simulation; no CollisionShape child needed. Jolt Physics recommended. Set Simulation Precision ≥ 5 to prevent collapse. Pressure > 0.0 only on closed meshes.

Godot 4.5+ adds apply_central_impulse() / apply_central_force() for RigidBody3D-style force application — distributes across all simulation points.

> See references/softbody-recipes.md for the cloth/cape walk-through (PlaneMesh, BoneAttachment3D pinning, Parent Collision Ignore) and the 4.5+ force/impulse API with GDScript and C# (explosion knockback, continuous wind).

> ⚠️ Changed in Godot 4.7: With Jolt Physics, SoftBody3D mass no longer defaults to 0 (which auto-calculated 1 kg per point, giving a very high total mass) — it now defaults to 1 kg for the entire body, matching Godot Physics. linear_stiffness is also applied differently, so re-tweak linear_stiffness and damping_coefficient after upgrading. See the 4.7 migration guide.

13. Troubleshooting Physics Issues

Symptom → causes & fixes quick table covering tunneling, wobbly stacks, scaled shapes, tile collision bumps, unstable cylinders, the physics spiral of death, and float-precision issues far from origin.

> See references/troubleshooting.md for the full table.

14. Implementation Checklist

• ] Dynamic bodies use primitive collision shapes; concave shapes only on StaticBodies
• ] Collision layers named in Project Settings; layer/mask set correctly per body
• ] No scale on collision shapes or bodies — use shape size parameters directly
• ] RigidBodies modify state via _integrate_forces(), not _physics_process()
• ] RigidBodies needing contact signals set contact_monitor = true + max_contacts_reported > 0
• ] Moving platforms use AnimatableBody2D/3D (not manually moved StaticBody)
• ] Code raycasts use PhysicsDirectSpaceState inside _physics_process() only
• ] Physics interpolation enabled; reset_physics_interpolation() called after teleport / initial placement
• ] Ragdoll bones on a separate collision layer from the character capsule
• ] 3D projects use Jolt (non-experimental default in Godot 4.6+)