The Godot physics system provides a high-performance simulation environment for 2D and 3D spatial interactions. It is architected around a server-client model where low-level simulation logic is decoupled from the scene tree via the PhysicsServer2D and PhysicsServer3D APIs.
Godot's physics architecture separates the simulation state (managed by Servers) from the scene representation (managed by Nodes).
The PhysicsServer2D and PhysicsServer3D are the core singletons responsible for the lifecycle of physics objects. They manage:
When a physics node enters the SceneTree, it creates a corresponding object in the PhysicsServer using an RID (Resource ID). The server performs the simulation, and the node synchronizes its transform with the server's state every physics frame.
Physics System Entity Mapping
Sources: doc/classes/RigidBody3D.xml7-11 doc/classes/CharacterBody3D.xml7 doc/classes/PhysicsDirectBodyState3D.xml4-8 doc/classes/CollisionObject3D.xml60-65 scene/3d/physics/vehicle_body_3d.h35-40
Godot provides specialized body types for different simulation requirements, inheriting from abstract bases PhysicsBody2D and PhysicsBody3D.
RigidBody2D and RigidBody3D implement full Newtonian physics. They cannot be controlled directly; instead, developers apply forces and impulses, and the simulation calculates the resulting motion doc/classes/RigidBody2D.xml7-9 doc/classes/RigidBody3D.xml7-9
_integrate_forces to safely modify the body state (velocity, transform) via PhysicsDirectBodyState doc/classes/RigidBody2D.xml21-27 doc/classes/RigidBody3D.xml21-27contact_monitor is enabled doc/classes/RigidBody2D.xml105-109 doc/classes/RigidBody3D.xml105-109CharacterBody2D and CharacterBody3D are specialized for user-controlled entities. They are not affected by physics forces like gravity automatically but affect other bodies in their path doc/classes/CharacterBody2D.xml7 doc/classes/CharacterBody3D.xml7
move_and_slide() for high-level movement with wall and slope detection doc/classes/CharacterBody2D.xml7 doc/classes/CharacterBody3D.xml7KinematicCollision objects, including normals and travel deltas doc/classes/CharacterBody2D.xml69-73 doc/classes/CharacterBody3D.xml76-82constant_linear_velocity.StaticBody intended for scripted movement. It ensures velocity is correctly synchronized so that other bodies can "ride" on it.Sources: doc/classes/RigidBody2D.xml1-13 doc/classes/CharacterBody3D.xml1-9 doc/classes/PhysicsBody2D.xml33-46 doc/classes/PhysicsBody3D.xml41-56
Area2D and Area3D nodes are used for proximity detection and physics overrides. They define regions of space using CollisionShape child nodes doc/classes/Area2D.xml7 doc/classes/Area3D.xml7
| Feature | Description | 2D Reference | 3D Reference |
|---|---|---|---|
| Overlap Detection | Tracks bodies and areas entering/exiting the region. | doc/classes/Area2D.xml7 | doc/classes/Area3D.xml7 |
| Gravity Override | Modifies gravity intensity and direction within the area. | doc/classes/Area2D.xml78-85 | doc/classes/Area3D.xml81-88 |
| Damping | Overrides linear and angular damping for bodies inside. | doc/classes/Area2D.xml65-71 | doc/classes/Area3D.xml68-74 |
| Audio Routing | Routes audio to custom buses when objects enter. | doc/classes/Area2D.xml72-76 | doc/classes/Area3D.xml75-79 |
Sources: doc/classes/Area2D.xml1-10 doc/classes/Area3D.xml1-11
Godot utilizes a modular backend system. While the public API is stable through the PhysicsServer singletons, the underlying implementation can be swapped.
The built-in engine implementation.
SoftBody3D doc/classes/Area3D.xml30-31 doc/classes/Area3D.xml45-46Godot supports the Jolt physics engine as a high-performance 3D backend alternative. It is often preferred for complex simulations requiring high stability and multithreading efficiency.
Collision Execution Flow
Sources: doc/classes/RigidBody3D.xml21-27 doc/classes/PhysicsDirectBodyState3D.xml7-8 doc/classes/Area3D.xml21-23
Physics bodies require collision shapes to define their geometry.
CollisionObject2D and CollisionObject3D manage shapes through "shape owners", which allow multiple shapes per body without needing a unique node for every single one doc/classes/CollisionObject2D.xml7 doc/classes/CollisionObject3D.xml7Area3D may lead to unexpected results as detection only occurs at the surface doc/classes/Area3D.xml10The VehicleBody3D is a specialized RigidBody3D that uses the PhysicsServer3D to simulate car suspension and wheel traction scene/3d/physics/vehicle_body_3d.h35-40 It works in conjunction with VehicleWheel3D nodes which define the physical properties of each wheel.
Sources: doc/classes/Area3D.xml10 doc/classes/CollisionObject2D.xml7 doc/classes/CollisionObject3D.xml7 scene/3d/physics/vehicle_body_3d.cpp35-50
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.