Index · Object → Node → Node3D → CollisionObject3D → PhysicsBody3D → RigidBody3D

RigidBody3D

A 3D physics body that is moved by a physics simulation.

Inherited by (1): VehicleBody3D
Class Description

RigidBody3D implements full 3D physics. It cannot be controlled directly, instead, you must apply forces to it (gravity, impulses, etc.), and the physics simulation will calculate the resulting movement, rotation, react to collisions, and affect other physics bodies in its path.

The body's behavior can be adjusted via lock_rotation, freeze, and freeze_mode. By changing various properties of the object, such as mass, you can control how the physics simulation acts on it.

A rigid body will always maintain its shape and size, even when forces are applied to it. It is useful for objects that can be interacted with in an environment, such as a tree that can be knocked over or a stack of crates that can be pushed around.

If you need to directly affect the body, prefer _integrate_forces() as it allows you to directly access the physics state.

If you need to override the default physics behavior, you can write a custom force integration function. See custom_integrator.

Note: Changing the 3D transform or linear_velocity of a RigidBody3D very often may lead to some unpredictable behaviors. This also happens when a RigidBody3D is the descendant of a constantly moving node, like another RigidBody3D, as that will cause its global transform to be set whenever its ancestor moves.

Properties

var angular_damp: float = 0.0

Damps the body's rotation. By default, the body will use the ProjectSettings.physics/3d/default_angular_damp project setting or any value override set by an Area3D the body is in. Depending on angular_damp_mode, you can set angular_damp to be added to or to replace the body's damping value.

See ProjectSettings.physics/3d/default_angular_damp for more details about damping.

var angular_damp_mode: RigidBody3D.DampMode = 0

Defines how angular_damp is applied.

var angular_velocity: Vector3 = Vector3(0, 0, 0)

The RigidBody3D's rotational velocity in radians per second.

var can_sleep: bool = true

If true, the body can enter sleep mode when there is no movement. See sleeping.

var center_of_mass: Vector3 = Vector3(0, 0, 0)

The body's custom center of mass, relative to the body's origin position, when center_of_mass_mode is set to CENTER_OF_MASS_MODE_CUSTOM. This is the balanced point of the body, where applied forces only cause linear acceleration. Applying forces outside of the center of mass causes angular acceleration.

When center_of_mass_mode is set to CENTER_OF_MASS_MODE_AUTO (default value), the center of mass is automatically determined, but this does not update the value of center_of_mass.

var center_of_mass_mode: RigidBody3D.CenterOfMassMode = 0

Defines the way the body's center of mass is set.

var constant_force: Vector3 = Vector3(0, 0, 0)

The body's total constant positional forces applied during each physics update.

See add_constant_force() and add_constant_central_force().

var constant_torque: Vector3 = Vector3(0, 0, 0)

The body's total constant rotational forces applied during each physics update.

See add_constant_torque().

var contact_monitor: bool = false

If true, the RigidBody3D will emit signals when it collides with another body.

Note: By default the maximum contacts reported is set to 0, meaning nothing will be recorded, see max_contacts_reported.

var continuous_cd: bool = false

If true, continuous collision detection is used.

Continuous collision detection tries to predict where a moving body will collide, instead of moving it and correcting its movement if it collided. Continuous collision detection is more precise, and misses fewer impacts by small, fast-moving objects. Not using continuous collision detection is faster to compute, but can miss small, fast-moving objects.

var custom_integrator: bool = false

If true, the standard force integration (like gravity or damping) will be disabled for this body. Other than collision response, the body will only move as determined by the _integrate_forces() method, if that virtual method is overridden.

Setting this property will call the method PhysicsServer3D.body_set_omit_force_integration() internally.

var freeze: bool = false

If true, the body is frozen. Gravity and forces are not applied anymore.

See freeze_mode to set the body's behavior when frozen.

Note: For a body that is always frozen, use StaticBody3D or AnimatableBody3D instead.

var freeze_mode: RigidBody3D.FreezeMode = 0

The body's freeze mode. Determines the body's behavior when freeze is true.

Note: For a body that is always frozen, use StaticBody3D or AnimatableBody3D instead.

var gravity_scale: float = 1.0

This is multiplied by ProjectSettings.physics/3d/default_gravity to produce this body's gravity. For example, a value of 1.0 will apply normal gravity, 2.0 will apply double the gravity, and 0.5 will apply half the gravity to this body.

var inertia: Vector3 = Vector3(0, 0, 0)

The body's moment of inertia. This is like mass, but for rotation: it determines how much torque it takes to rotate the body on each axis. The moment of inertia is usually computed automatically from the mass and the shapes, but this property allows you to set a custom value.

If set to Vector3.ZERO, inertia is automatically computed (default value).

Note: This value does not change when inertia is automatically computed. Use PhysicsServer3D to get the computed inertia.

@onready var ball = $Ball

func get_ball_inertia():
	return PhysicsServer3D.body_get_direct_state(ball.get_rid()).inverse_inertia.inverse()
var linear_damp: float = 0.0

Damps the body's movement. By default, the body will use the ProjectSettings.physics/3d/default_linear_damp project setting or any value override set by an Area3D the body is in. Depending on linear_damp_mode, you can set linear_damp to be added to or to replace the body's damping value.

See ProjectSettings.physics/3d/default_linear_damp for more details about damping.

var linear_damp_mode: RigidBody3D.DampMode = 0

Defines how linear_damp is applied.

var linear_velocity: Vector3 = Vector3(0, 0, 0)

The body's linear velocity in units per second. Can be used sporadically, but don't set this every frame, because physics may run in another thread and runs at a different granularity. Use _integrate_forces() as your process loop for precise control of the body state.

var lock_rotation: bool = false

If true, the body cannot rotate. Gravity and forces only apply linear movement.

var mass: float = 1.0

The body's mass.

var max_contacts_reported: int = 0

The maximum number of contacts that will be recorded. Requires a value greater than 0 and contact_monitor to be set to true to start to register contacts. Use get_contact_count() to retrieve the count or get_colliding_bodies() to retrieve bodies that have been collided with.

Note: The number of contacts is different from the number of collisions. Collisions between parallel edges will result in two contacts (one at each end), and collisions between parallel faces will result in four contacts (one at each corner).

var physics_material_override: PhysicsMaterial

The physics material override for the body.

If a material is assigned to this property, it will be used instead of any other physics material, such as an inherited one.

var sleeping: bool = false

If true, the body will not move and will not calculate forces until woken up by another body through, for example, a collision, or by using the apply_impulse() or apply_force() methods.

Inherited from PhysicsBody3D (6)
Inherited from CollisionObject3D (6)
Inherited from Node3D (17)
var position: Vector3 = Vector3(0, 0, 0)
var rotation: Vector3 = Vector3(0, 0, 0)
var rotation_order: EulerOrder = 2
var scale: Vector3 = Vector3(1, 1, 1)
var top_level: bool = false
var transform: Transform3D = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)
var visibility_parent: NodePath = NodePath("")
var visible: bool = true
Inherited from Node (14)
var owner: Node

Methods

func _integrate_forces(state: PhysicsDirectBodyState3D) -> void

Called during physics processing, allowing you to read and safely modify the simulation state for the object. By default, it is called before the standard force integration, but the custom_integrator property allows you to disable the standard force integration and do fully custom force integration for a body.

func add_constant_central_force(force: Vector3) -> void

Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with constant_force = Vector3(0, 0, 0).

This is equivalent to using add_constant_force() at the body's center of mass.

func add_constant_force(force: Vector3, position: Vector3 = Vector3(0, 0, 0)) -> void

Adds a constant positioned force to the body that keeps being applied over time until cleared with constant_force = Vector3(0, 0, 0).

position is the offset from the body origin in global coordinates.

func add_constant_torque(torque: Vector3) -> void

Adds a constant rotational force without affecting position that keeps being applied over time until cleared with constant_torque = Vector3(0, 0, 0).

func apply_central_force(force: Vector3) -> void

Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update.

This is equivalent to using apply_force() at the body's center of mass.

func apply_central_impulse(impulse: Vector3) -> void

Applies a directional impulse without affecting rotation.

An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise).

This is equivalent to using apply_impulse() at the body's center of mass.

func apply_force(force: Vector3, position: Vector3 = Vector3(0, 0, 0)) -> void

Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update.

position is the offset from the body origin in global coordinates.

func apply_impulse(impulse: Vector3, position: Vector3 = Vector3(0, 0, 0)) -> void

Applies a positioned impulse to the body.

An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise).

position is the offset from the body origin in global coordinates.

func apply_torque(torque: Vector3) -> void

Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update.

Note: inertia is required for this to work. To have inertia, an active CollisionShape3D must be a child of the node, or you can manually set inertia.

func apply_torque_impulse(impulse: Vector3) -> void

Applies a rotational impulse to the body without affecting the position.

An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise).

Note: inertia is required for this to work. To have inertia, an active CollisionShape3D must be a child of the node, or you can manually set inertia.

func get_colliding_bodies() -> Node3D[]

Returns a list of the bodies colliding with this one. Requires contact_monitor to be set to true and max_contacts_reported to be set high enough to detect all the collisions.

Note: The result of this test is not immediate after moving objects. For performance, list of collisions is updated once per frame and before the physics step. Consider using signals instead.

func get_contact_count() -> int

Returns the number of contacts this body has with other bodies. By default, this returns 0 unless bodies are configured to monitor contacts (see contact_monitor).

Note: To retrieve the colliding bodies, use get_colliding_bodies().

func get_inverse_inertia_tensor() -> Basis

Returns the inverse inertia tensor basis. This is used to calculate the angular acceleration resulting from a torque applied to the RigidBody3D.

func set_axis_velocity(axis_velocity: Vector3) -> void

Sets an axis velocity. The velocity in the given vector axis will be set as the given vector length. This is useful for jumping behavior.

Inherited from PhysicsBody3D (8)
func get_collision_exceptions() -> PhysicsBody3D[]
func move_and_collide(motion: Vector3, test_only: bool = false, safe_margin: float = 0.001, recovery_as_collision: bool = false, max_collisions: int = 1) -> KinematicCollision3D
func set_axis_lock(axis: PhysicsServer3D.BodyAxis, lock: bool) -> void
func test_move(from: Transform3D, motion: Vector3, collision: KinematicCollision3D = null, safe_margin: float = 0.001, recovery_as_collision: bool = false, max_collisions: int = 1) -> bool
Inherited from CollisionObject3D (23)
func _input_event(camera: Camera3D, event: InputEvent, event_position: Vector3, normal: Vector3, shape_idx: int) -> void
func _mouse_enter() -> void
func _mouse_exit() -> void
func create_shape_owner(owner: Object) -> int
func get_collision_layer_value(layer_number: int) -> bool
func get_collision_mask_value(layer_number: int) -> bool
func get_rid() -> RID
func is_shape_owner_disabled(owner_id: int) -> bool
func remove_shape_owner(owner_id: int) -> void
func set_collision_layer_value(layer_number: int, value: bool) -> void
func set_collision_mask_value(layer_number: int, value: bool) -> void
func shape_find_owner(shape_index: int) -> int
func shape_owner_add_shape(owner_id: int, shape: Shape3D) -> void
func shape_owner_clear_shapes(owner_id: int) -> void
func shape_owner_get_owner(owner_id: int) -> Object
func shape_owner_get_shape(owner_id: int, shape_id: int) -> Shape3D
func shape_owner_get_shape_index(owner_id: int, shape_id: int) -> int
func shape_owner_remove_shape(owner_id: int, shape_id: int) -> void
func shape_owner_set_disabled(owner_id: int, disabled: bool) -> void
func shape_owner_set_transform(owner_id: int, transform: Transform3D) -> void
Inherited from Node3D (37)
func add_gizmo(gizmo: Node3DGizmo) -> void
func clear_gizmos() -> void
func force_update_transform() -> void
func get_gizmos() -> Node3DGizmo[]
func global_rotate(axis: Vector3, angle: float) -> void
func global_scale(scale: Vector3) -> void
func global_translate(offset: Vector3) -> void
func hide() -> void
func look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func orthonormalize() -> void
func rotate(axis: Vector3, angle: float) -> void
func rotate_object_local(axis: Vector3, angle: float) -> void
func rotate_x(angle: float) -> void
func rotate_y(angle: float) -> void
func rotate_z(angle: float) -> void
func scale_object_local(scale: Vector3) -> void
func set_disable_scale(disable: bool) -> void
func set_identity() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) -> void
func show() -> void
func to_global(local_point: Vector3) -> Vector3
func to_local(global_point: Vector3) -> Vector3
func translate(offset: Vector3) -> void
func translate_object_local(offset: Vector3) -> void
func update_gizmos() -> void
Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

signal body_entered(body: Node)

Emitted when a collision with another PhysicsBody3D or GridMap occurs. Requires contact_monitor to be set to true and max_contacts_reported to be set high enough to detect all the collisions. GridMaps are detected if the MeshLibrary has Collision Shape3Ds.

body the Node, if it exists in the tree, of the other PhysicsBody3D or GridMap.

signal body_exited(body: Node)

Emitted when the collision with another PhysicsBody3D or GridMap ends. Requires contact_monitor to be set to true and max_contacts_reported to be set high enough to detect all the collisions. GridMaps are detected if the MeshLibrary has Collision Shape3Ds.

body the Node, if it exists in the tree, of the other PhysicsBody3D or GridMap.

signal body_shape_entered(body_rid: RID, body: Node, body_shape_index: int, local_shape_index: int)

Emitted when one of this RigidBody3D's Shape3Ds collides with another PhysicsBody3D or GridMap's Shape3Ds. Requires contact_monitor to be set to true and max_contacts_reported to be set high enough to detect all the collisions. GridMaps are detected if the MeshLibrary has Collision Shape3Ds.

body_rid the RID of the other PhysicsBody3D or MeshLibrary's CollisionObject3D used by the PhysicsServer3D.

body the Node, if it exists in the tree, of the other PhysicsBody3D or GridMap.

body_shape_index the index of the Shape3D of the other PhysicsBody3D or GridMap used by the PhysicsServer3D. Get the CollisionShape3D node with body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)).

local_shape_index the index of the Shape3D of this RigidBody3D used by the PhysicsServer3D. Get the CollisionShape3D node with self.shape_owner_get_owner(self.shape_find_owner(local_shape_index)).

signal body_shape_exited(body_rid: RID, body: Node, body_shape_index: int, local_shape_index: int)

Emitted when the collision between one of this RigidBody3D's Shape3Ds and another PhysicsBody3D or GridMap's Shape3Ds ends. Requires contact_monitor to be set to true and max_contacts_reported to be set high enough to detect all the collisions. GridMaps are detected if the MeshLibrary has Collision Shape3Ds.

body_rid the RID of the other PhysicsBody3D or MeshLibrary's CollisionObject3D used by the PhysicsServer3D. GridMaps are detected if the Meshes have Shape3Ds.

body the Node, if it exists in the tree, of the other PhysicsBody3D or GridMap.

body_shape_index the index of the Shape3D of the other PhysicsBody3D or GridMap used by the PhysicsServer3D. Get the CollisionShape3D node with body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)).

local_shape_index the index of the Shape3D of this RigidBody3D used by the PhysicsServer3D. Get the CollisionShape3D node with self.shape_owner_get_owner(self.shape_find_owner(local_shape_index)).

signal sleeping_state_changed()

Emitted when the physics engine changes the body's sleeping state.

Note: Changing the value sleeping will not trigger this signal. It is only emitted if the sleeping state is changed by the physics engine or emit_signal("sleeping_state_changed") is used.

Inherited from CollisionObject3D (3)
signal input_event(camera: Node, event: InputEvent, event_position: Vector3, normal: Vector3, shape_idx: int)
signal mouse_entered()
signal mouse_exited()
Inherited from Node3D (1)
Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)

Enums & Constants

enum FreezeMode
FREEZE_MODE_STATIC = 0

Static body freeze mode (default). The body is not affected by gravity and forces. It can be only moved by user code and doesn't collide with other bodies along its path.

FREEZE_MODE_KINEMATIC = 1

Kinematic body freeze mode. Similar to FREEZE_MODE_STATIC, but collides with other bodies along its path when moved. Useful for a frozen body that needs to be animated.

enum CenterOfMassMode
CENTER_OF_MASS_MODE_AUTO = 0

In this mode, the body's center of mass is calculated automatically based on its shapes. This assumes that the shapes' origins are also their center of mass.

CENTER_OF_MASS_MODE_CUSTOM = 1

In this mode, the body's center of mass is set through center_of_mass. Defaults to the body's origin position.

enum DampMode
DAMP_MODE_COMBINE = 0

In this mode, the body's damping value is added to any value set in areas or the default value.

DAMP_MODE_REPLACE = 1

In this mode, the body's damping value replaces any value set in areas or the default value.