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):

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

See [references/rigidbody-recipes.md](references/rigidbody-recipes.md) for a thrust-and-spin example (GDScript + C#) using applyforce + applycentralimpulse + applytorque.

integrateforces() — Safe Physics Modification

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

Warning: integrateforces() 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](references/rigidbody-recipes.md) for the thrust + torque example using state.applyforce / state.applytorque (GDScript + C#).

Contact Monitoring, PhysicsMaterial, Freeze, look_at

• Contact signals require contactmonitor = true + maxcontactsreported > 0. Then bodyentered/body_exited fire.
• PhysicsMaterial resource controls friction (0 ice → 1 rubber) and bounce (0 → 1).
• Freeze modes: FREEZEMODESTATIC (acts like a StaticBody) or FREEZEMODEKINEMATIC (code-moved, pushes others).
• RigidBody3D orientation: never lookat() a RigidBody — use integrateforces and set state.angularvelocity from a cross-product steering term.

See [references/rigidbody-recipes.md](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 constantlinearvelocity (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](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 bodyentered / bodyexited for body overlaps; use areaentered / areaexited for Area-to-Area (hitbox vs hurtbox — see component-system). Areas can also override gravity (zero-G zones, point gravity / black holes), lineardamp / angulardamp (water, slow-mo), and redirect audio to a specific AudioBus. When multiple areas overlap, priority decides order; pick a spaceoverride mode (COMBINE, REPLACE, COMBINEREPLACE, REPLACE_COMBINE).

See [references/area-recipes.md](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

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 onewaycollision_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](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 setcollisionlayervalue(N, true) / setcollisionmaskvalue(N, true) (1-indexed).

See [references/collision-layers.md](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 iscolliding() and getcollider() / getcollisionpoint() / getcollisionnormal().

See [references/raycasting-recipes.md](references/raycasting-recipes.md) for the GDScript + C# RayCast node example.

Code-Based Raycasting (PhysicsDirectSpaceState)

For on-demand queries, access the space state via getworld2d().directspacestate (or getworld3d()) and call intersectray(query) with PhysicsRayQueryParameters2D/3D.create(from, to). Set query.exclude = [getrid()] to skip self, query.collisionmask to filter layers. Only safe inside physics_process() — the physics space is locked during rendering.

See [references/raycasting-recipes.md](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 intersectray result dictionary contains position, normal, collider, colliderid, rid, shape. PhysicsDirectSpaceState also supports intersectpoint (overlapping shapes at a point), intersectshape (area query), castmotion (shape sweep), collideshape (contact points), getrestinfo (resting collision info). For 3D mouse picking, Camera3D.projectrayorigin(screenpos) + projectraynormal(screenpos) builds the ray.

See [references/raycasting-recipes.md](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](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 physicsprocess() — transforms set outside physics ticks cause jitter
2. Tweens and AnimationPlayer that move physics objects must use physics tick timing
3. Call resetphysicsinterpolation() after teleporting or initial placement to prevent "streaking"

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

Camera Interpolation

Cameras need special handling under physics interpolation. Make the camera independent (or toplevel = true), update it in process() (not physicsprocess()), and read the target's smooth position with getglobaltransform_interpolated().

See [references/interpolation-camera.md](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 physicalbonesstart_simulation(), blend with Influence.

See [references/ragdoll-recipes.md](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 applycentralimpulse() / applycentralforce() for RigidBody3D-style force application — distributes across all simulation points.

See [references/softbody-recipes.md](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. linearstiffness is also applied differently, so re-tweak linearstiffness and dampingcoefficient after upgrading. See the 4.7 migration guide.