Use Godot 4.7 physics bodies and detection in 2D and 3D: RigidBody, StaticBody, Area, and CharacterBody; collision layers vs masks; contact/overlap signals; and raycasts (RayCast nodes and direct space-state queries). Use when configuring collision layers/masks, detecting overlaps with Area2D/Area3D

Godot Physics (4.x, 2D + 3D) Pick the right physics body, wire up collision layers/masks, detect overlaps, and cast rays. Concepts apply to both 2D and 3D (swap the 2D / 3D suffix). Targets Godot 4.7 . In 3D, projects created with Godot 4.6 or later run Jolt Physics by default; older projects keep GodotPhysics3D unless someone switched them. 2D always uses Godot's own 2D engine. When to use Use when choosing between body types, setting collision layers/masks so the right things collide, detecting overlaps (triggers, hurtboxes) with Area , applying forces/impulses to a RigidBody , or casting rays for line of sight/ground checks. When not to use: kinematic character controllers ( move and slide ) → godot 2d movement ; tile collision setup → godot tilemap ; tuning the feel of physics (timestep, mass, jitter) → physics tuning . Core workflow 1. For 3D, check which engine runs before debugging behavior: Project Settings Physics 3D Physics Engine ( [physics] 3d/physics engine="Jolt Physics" in project.godot ). Projects created in 4.6+ get Jolt written there by default; with no such line ( DEFAULT ) the engine is GodotPhysics3D. The API is the same, but joints, ray cast face indices, kinematic contacts, and collision margins behave differently (see Pitfalls). 2. Choose the body type: StaticBody — never moves (floors, walls). Collides, no simulation. RigidBody — fully simulated (gravity, forces, bouncing). Don't set its position directly; apply forces/impulses or set linear velocity . CharacterBody — script driven kinematic (see godot 2d movement ). Area — detects overlaps and can apply gravity/damping; no solid collision. Every body needs a CollisionShape (or CollisionPolygon ) child. 3. Configure layers and masks. A body is on its layers and scans for its masks . Two bodies interact only if one's layer is in the other's mask. Name layers in Project Settings Layer Names for clarity. 4. Detect overlaps with Area signals ( body entered , area entered ). 5. Drive RigidBodies with forces/impulses , or override integrate forces for full control. 6. Cast rays with a RayCast2D/3D node (polled each frame) or a one shot space state query from code. Patterns 1. Collision layers vs masks (set from code) 2. Area2D as a trigger / hurtbox 3. Applying force and impulse to a RigidBody3D 4. Raycast two ways Pitfalls Layer vs mask confusion is the 1 bug. Layer = "what I am"; mask = "what I look for". For A to detect B, B's layer must be in A's mask. Detection can be one directional. Moving a RigidBody by position fights the solver and causes tunneling/jitter. Use impulses/forces, set linear velocity , or freeze it. To teleport, set position and zero the velocities inside integrate forces . Area doesn't fire when neither monitoring nor monitorable is set, or layers/masks don't overlap. monitoring must be on for the Area to detect; monitorable lets others detect it. RayCast2D/3D read stale or no data if enabled is false, or if you read it before physics updated — read in physics process , and call force raycast update() after moving it within the same tick. Forgetting a CollisionShape (or leaving it empty) means the body never collides. Fast objects tunnel through thin walls; enable continuous CD on the RigidBody ( continuous cd ) or use a raycast based check. intersect ray excludes its own body? Pass query.exclude = [self.get rid()] (an Array[RID] , not an array of nodes) to skip self hits. Jolt Physics (3D) differences face index is always 1 in intersect ray() / RayCast3D results under Jolt. Turn on Project Settings Physics Jolt Physics 3D Queries Enable Ray Cast Face Index if you need it (it costs roughly 25% more memory for ConcavePolygonShape3D ). A joint with only one body gets inverted limits after switching engines. Jolt treats the lone body as node b with node a as the world; GodotPhysics3D always treats it as node a . Assign the body to the slot Jolt expects, or use Physics Jolt Physics 3D Joints World Node for compatibility with an older project. Joint soft limit properties do nothing under Jolt: bias / damping / impulse clamp on PinJoint3D ; bias / softness / relaxation on HingeJoint3D and ConeTwistJoint3D ; angular and limit softness/restitution/damping on SliderJoint3D ; limit softness/restitution/damping/erp on Generic6DOFJoint3D . Godot warns when they are set to non default values. A frozen kinematic RigidBody3D reports no contacts with static or kinematic bodies, even with max contacts reported 0 . Enable Physics Jolt Physics 3D Simulation Generate All Kinematic Contacts if gameplay depends on those contacts. Shape margin shrinks the shape instead of padding it under Jolt, so sizes stay true but shape queries can return odd normals on small shapes; the effective margin comes from Physics Jolt Physics 3D Collisions Collision Margin Fraction. Area3D now fires body entered for SoftBody3D under Jolt (GodotPhysics3D never did). Filter soft bodies out with layers/masks if the old behavior is expected. A WorldBoundaryShape3D floor sits at the wrong height after upgrading to 4.7 → under Jolt, 4.7 reads plane.d with Godot's sign convention, the opposite of 4.6; flip the sign of d in projects tuned on 4.6. Jolt also caps the plane's effective size (Physics Jolt Physics 3D Limits World Boundary Shape Size), so bodies far from the origin can fall off an "infinite" floor. References For integrate forces , joints, one way collision, PhysicsServer direct access, shape queries ( intersect shape ), and 3D move and collide , read references/bodies and queries.md . Jolt specifics: Godot docs "Using Jolt Physics" ( https://docs.godotengine.org/en/stable/tutorials/physics/using jolt physics.html ). Related skills godot 2d movement — kinematic CharacterBody2D controllers. godot tilemap — tile collision shapes and their layers. physics tuning — engine agnostic feel: timestep, mass, drag, CCD. godot 3d essentials — 3D scene setup these bodies live in.

godot-physics