godot-docs/classes/class_physicsdirectbodystate.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/3.6/doc/classes/PhysicsDirectBodyState.xml.

.. _class_PhysicsDirectBodyState:

PhysicsDirectBodyState
======================

**Inherits:** :ref:`Object<class_Object>`

Direct access object to a physics body in the :ref:`PhysicsServer<class_PhysicsServer>`.

.. rst-class:: classref-introduction-group

Description
-----------

Provides direct access to a physics body in the :ref:`PhysicsServer<class_PhysicsServer>`, allowing safe changes to physics properties. This object is passed via the direct state callback of rigid/character bodies, and is intended for changing the direct state of that body. See :ref:`RigidBody._integrate_forces<class_RigidBody_method__integrate_forces>`.

.. rst-class:: classref-introduction-group

Tutorials
---------

- :doc:`Physics introduction <../tutorials/physics/physics_introduction>`

- :doc:`Ray-casting <../tutorials/physics/ray-casting>`

.. rst-class:: classref-reftable-group

Properties
----------

.. table::
   :widths: auto

   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`     | :ref:`angular_velocity<class_PhysicsDirectBodyState_property_angular_velocity>`             |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`     | :ref:`center_of_mass<class_PhysicsDirectBodyState_property_center_of_mass>`                 |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`     | :ref:`inverse_inertia<class_PhysicsDirectBodyState_property_inverse_inertia>`               |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`         | :ref:`inverse_mass<class_PhysicsDirectBodyState_property_inverse_mass>`                     |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`     | :ref:`linear_velocity<class_PhysicsDirectBodyState_property_linear_velocity>`               |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`Basis<class_Basis>`         | :ref:`principal_inertia_axes<class_PhysicsDirectBodyState_property_principal_inertia_axes>` |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`           | :ref:`sleeping<class_PhysicsDirectBodyState_property_sleeping>`                             |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`         | :ref:`step<class_PhysicsDirectBodyState_property_step>`                                     |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`         | :ref:`total_angular_damp<class_PhysicsDirectBodyState_property_total_angular_damp>`         |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`     | :ref:`total_gravity<class_PhysicsDirectBodyState_property_total_gravity>`                   |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`         | :ref:`total_linear_damp<class_PhysicsDirectBodyState_property_total_linear_damp>`           |
   +-----------------------------------+---------------------------------------------------------------------------------------------+
   | :ref:`Transform<class_Transform>` | :ref:`transform<class_PhysicsDirectBodyState_property_transform>`                           |
   +-----------------------------------+---------------------------------------------------------------------------------------------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                                          | :ref:`add_central_force<class_PhysicsDirectBodyState_method_add_central_force>` **(** :ref:`Vector3<class_Vector3>` force **)**                                                       |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                                          | :ref:`add_force<class_PhysicsDirectBodyState_method_add_force>` **(** :ref:`Vector3<class_Vector3>` force, :ref:`Vector3<class_Vector3>` position **)**                               |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                                          | :ref:`add_torque<class_PhysicsDirectBodyState_method_add_torque>` **(** :ref:`Vector3<class_Vector3>` torque **)**                                                                    |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                                          | :ref:`apply_central_impulse<class_PhysicsDirectBodyState_method_apply_central_impulse>` **(** :ref:`Vector3<class_Vector3>` j **)**                                                   |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                                          | :ref:`apply_impulse<class_PhysicsDirectBodyState_method_apply_impulse>` **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` j **)**                           |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                                          | :ref:`apply_torque_impulse<class_PhysicsDirectBodyState_method_apply_torque_impulse>` **(** :ref:`Vector3<class_Vector3>` j **)**                                                     |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`RID<class_RID>`                                         | :ref:`get_contact_collider<class_PhysicsDirectBodyState_method_get_contact_collider>` **(** :ref:`int<class_int>` contact_idx **)** |const|                                           |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                                         | :ref:`get_contact_collider_id<class_PhysicsDirectBodyState_method_get_contact_collider_id>` **(** :ref:`int<class_int>` contact_idx **)** |const|                                     |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Object<class_Object>`                                   | :ref:`get_contact_collider_object<class_PhysicsDirectBodyState_method_get_contact_collider_object>` **(** :ref:`int<class_int>` contact_idx **)** |const|                             |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`                                 | :ref:`get_contact_collider_position<class_PhysicsDirectBodyState_method_get_contact_collider_position>` **(** :ref:`int<class_int>` contact_idx **)** |const|                         |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                                         | :ref:`get_contact_collider_shape<class_PhysicsDirectBodyState_method_get_contact_collider_shape>` **(** :ref:`int<class_int>` contact_idx **)** |const|                               |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`                                 | :ref:`get_contact_collider_velocity_at_position<class_PhysicsDirectBodyState_method_get_contact_collider_velocity_at_position>` **(** :ref:`int<class_int>` contact_idx **)** |const| |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                                         | :ref:`get_contact_count<class_PhysicsDirectBodyState_method_get_contact_count>` **(** **)** |const|                                                                                   |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`                                     | :ref:`get_contact_impulse<class_PhysicsDirectBodyState_method_get_contact_impulse>` **(** :ref:`int<class_int>` contact_idx **)** |const|                                             |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`                                 | :ref:`get_contact_local_normal<class_PhysicsDirectBodyState_method_get_contact_local_normal>` **(** :ref:`int<class_int>` contact_idx **)** |const|                                   |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`                                 | :ref:`get_contact_local_position<class_PhysicsDirectBodyState_method_get_contact_local_position>` **(** :ref:`int<class_int>` contact_idx **)** |const|                               |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                                         | :ref:`get_contact_local_shape<class_PhysicsDirectBodyState_method_get_contact_local_shape>` **(** :ref:`int<class_int>` contact_idx **)** |const|                                     |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`PhysicsDirectSpaceState<class_PhysicsDirectSpaceState>` | :ref:`get_space_state<class_PhysicsDirectBodyState_method_get_space_state>` **(** **)**                                                                                               |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Vector3<class_Vector3>`                                 | :ref:`get_velocity_at_local_position<class_PhysicsDirectBodyState_method_get_velocity_at_local_position>` **(** :ref:`Vector3<class_Vector3>` local_position **)** |const|            |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                                          | :ref:`integrate_forces<class_PhysicsDirectBodyState_method_integrate_forces>` **(** **)**                                                                                             |
   +---------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Property Descriptions
---------------------

.. _class_PhysicsDirectBodyState_property_angular_velocity:

.. rst-class:: classref-property

:ref:`Vector3<class_Vector3>` **angular_velocity**

.. rst-class:: classref-property-setget

- void **set_angular_velocity** **(** :ref:`Vector3<class_Vector3>` value **)**
- :ref:`Vector3<class_Vector3>` **get_angular_velocity** **(** **)**

The body's rotational velocity in axis-angle format. The magnitude of the vector is the rotation rate in *radians* per second.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_center_of_mass:

.. rst-class:: classref-property

:ref:`Vector3<class_Vector3>` **center_of_mass**

.. rst-class:: classref-property-setget

- :ref:`Vector3<class_Vector3>` **get_center_of_mass** **(** **)**

.. container:: contribute

	There is currently no description for this property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_inverse_inertia:

.. rst-class:: classref-property

:ref:`Vector3<class_Vector3>` **inverse_inertia**

.. rst-class:: classref-property-setget

- :ref:`Vector3<class_Vector3>` **get_inverse_inertia** **(** **)**

The inverse of the inertia of the body.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_inverse_mass:

.. rst-class:: classref-property

:ref:`float<class_float>` **inverse_mass**

.. rst-class:: classref-property-setget

- :ref:`float<class_float>` **get_inverse_mass** **(** **)**

The inverse of the mass of the body.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_linear_velocity:

.. rst-class:: classref-property

:ref:`Vector3<class_Vector3>` **linear_velocity**

.. rst-class:: classref-property-setget

- void **set_linear_velocity** **(** :ref:`Vector3<class_Vector3>` value **)**
- :ref:`Vector3<class_Vector3>` **get_linear_velocity** **(** **)**

The body's linear velocity in units per second.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_principal_inertia_axes:

.. rst-class:: classref-property

:ref:`Basis<class_Basis>` **principal_inertia_axes**

.. rst-class:: classref-property-setget

- :ref:`Basis<class_Basis>` **get_principal_inertia_axes** **(** **)**

.. container:: contribute

	There is currently no description for this property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_sleeping:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **sleeping**

.. rst-class:: classref-property-setget

- void **set_sleep_state** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **is_sleeping** **(** **)**

If ``true``, this body is currently sleeping (not active).

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_step:

.. rst-class:: classref-property

:ref:`float<class_float>` **step**

.. rst-class:: classref-property-setget

- :ref:`float<class_float>` **get_step** **(** **)**

The timestep (delta) used for the simulation.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_total_angular_damp:

.. rst-class:: classref-property

:ref:`float<class_float>` **total_angular_damp**

.. rst-class:: classref-property-setget

- :ref:`float<class_float>` **get_total_angular_damp** **(** **)**

The rate at which the body stops rotating, if there are not any other forces moving it.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_total_gravity:

.. rst-class:: classref-property

:ref:`Vector3<class_Vector3>` **total_gravity**

.. rst-class:: classref-property-setget

- :ref:`Vector3<class_Vector3>` **get_total_gravity** **(** **)**

The total gravity vector being currently applied to this body.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_total_linear_damp:

.. rst-class:: classref-property

:ref:`float<class_float>` **total_linear_damp**

.. rst-class:: classref-property-setget

- :ref:`float<class_float>` **get_total_linear_damp** **(** **)**

The rate at which the body stops moving, if there are not any other forces moving it.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_property_transform:

.. rst-class:: classref-property

:ref:`Transform<class_Transform>` **transform**

.. rst-class:: classref-property-setget

- void **set_transform** **(** :ref:`Transform<class_Transform>` value **)**
- :ref:`Transform<class_Transform>` **get_transform** **(** **)**

The body's transformation matrix.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Method Descriptions
-------------------

.. _class_PhysicsDirectBodyState_method_add_central_force:

.. rst-class:: classref-method

void **add_central_force** **(** :ref:`Vector3<class_Vector3>` force **)**

Adds a constant directional force without affecting rotation.

This is equivalent to ``add_force(force, Vector3(0,0,0))``.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_add_force:

.. rst-class:: classref-method

void **add_force** **(** :ref:`Vector3<class_Vector3>` force, :ref:`Vector3<class_Vector3>` position **)**

Adds a positioned force to the body. Both the force and the offset from the body origin are in global coordinates.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_add_torque:

.. rst-class:: classref-method

void **add_torque** **(** :ref:`Vector3<class_Vector3>` torque **)**

Adds a constant rotational force without affecting position.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_apply_central_impulse:

.. rst-class:: classref-method

void **apply_central_impulse** **(** :ref:`Vector3<class_Vector3>` j **)**

Applies a single directional impulse without affecting rotation.

This is equivalent to ``apply_impulse(Vector3(0, 0, 0), impulse)``.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_apply_impulse:

.. rst-class:: classref-method

void **apply_impulse** **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` j **)**

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. The position uses the rotation of the global coordinate system, but is centered at the object's origin.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_apply_torque_impulse:

.. rst-class:: classref-method

void **apply_torque_impulse** **(** :ref:`Vector3<class_Vector3>` j **)**

Apply a torque impulse (which will be affected by the body mass and shape). This will rotate the body around the vector ``j`` passed as parameter.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_collider:

.. rst-class:: classref-method

:ref:`RID<class_RID>` **get_contact_collider** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the collider's :ref:`RID<class_RID>`.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_collider_id:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_contact_collider_id** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the collider's object id.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_collider_object:

.. rst-class:: classref-method

:ref:`Object<class_Object>` **get_contact_collider_object** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the collider object.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_collider_position:

.. rst-class:: classref-method

:ref:`Vector3<class_Vector3>` **get_contact_collider_position** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the contact position in the collider.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_collider_shape:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_contact_collider_shape** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the collider's shape index.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_collider_velocity_at_position:

.. rst-class:: classref-method

:ref:`Vector3<class_Vector3>` **get_contact_collider_velocity_at_position** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the linear velocity vector at the collider's contact point.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_count:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_contact_count** **(** **)** |const|

Returns the number of contacts this body has with other bodies.

\ **Note:** By default, this returns 0 unless bodies are configured to monitor contacts. See :ref:`RigidBody.contact_monitor<class_RigidBody_property_contact_monitor>`.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_impulse:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_contact_impulse** **(** :ref:`int<class_int>` contact_idx **)** |const|

Impulse created by the contact. Only implemented for Bullet physics.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_local_normal:

.. rst-class:: classref-method

:ref:`Vector3<class_Vector3>` **get_contact_local_normal** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the local normal at the contact point.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_local_position:

.. rst-class:: classref-method

:ref:`Vector3<class_Vector3>` **get_contact_local_position** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the local position of the contact point.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_contact_local_shape:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_contact_local_shape** **(** :ref:`int<class_int>` contact_idx **)** |const|

Returns the local shape index of the collision.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_space_state:

.. rst-class:: classref-method

:ref:`PhysicsDirectSpaceState<class_PhysicsDirectSpaceState>` **get_space_state** **(** **)**

Returns the current state of the space, useful for queries.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_get_velocity_at_local_position:

.. rst-class:: classref-method

:ref:`Vector3<class_Vector3>` **get_velocity_at_local_position** **(** :ref:`Vector3<class_Vector3>` local_position **)** |const|

Returns the body's velocity at the given relative position, including both translation and rotation.

.. rst-class:: classref-item-separator

----

.. _class_PhysicsDirectBodyState_method_integrate_forces:

.. rst-class:: classref-method

void **integrate_forces** **(** **)**

Calls the built-in force integration code.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`