.. _stdlib_rigid_body_component:

=========
RigidBody
=========

The RigidBody component adds physical movement to the node, enabling it to respond to collisions, gravity, or custom forces.

.. note::
    For the body to respond to collisions, add a :ref:`Collider <stdlib_physics_core_colliders>` component.
    Without a collider, the body will act as a point mass.

.. note::
    An important choice is to make your body either ``Dynamic`` or ``Kinematic``; see :ref:`MotionType <enum-public_components-MotionType>`.
    To make a body static, simply do not add a RigidBody component — add only a Collider.
    By default, a body is ``Dynamic``.

This component is provided by the ``engine.physics_core`` module, which is included in the ``engine.core`` module.

Example of a simple physical object::

    require engine.core

    let ball = create_node(NodeData(position=float3(0, 10, 0), scale=float3(2.)))
    add_component(ball, new RigidBody())
    add_component(ball, new Collider(shape = sphere_shape()))

With RigidBody you can:

* Set the body mass: :ref:`mass <function-rigid_body_component__dot__rq_mass_rq_clone_RigidBody_float>`
* Get and set velocities, as well as limit them: :ref:`velocity <function-rigid_body_component__dot__rq_velocity_rq_clone_RigidBody_float3>`, :ref:`angularVelocity <function-rigid_body_component__dot__rq_angularVelocity_rq_clone_RigidBody_float3>`, :ref:`maxVelocity <function-rigid_body_component__dot__rq_maxVelocity_rq_clone_RigidBody_float>`, :ref:`maxAngularVelocity <function-rigid_body_component__dot__rq_maxAngularVelocity_rq_clone_RigidBody_float>`
* Set velocity damping: :ref:`linearDamping <function-rigid_body_component__dot__rq_linearDamping_rq_clone_RigidBody_float>`, :ref:`angularDamping <function-rigid_body_component__dot__rq_angularDamping_rq_clone_RigidBody_float>`
* Disable physics interactions entirely: :ref:`enabled <function-rigid_body_component__dot__rq_enabled_rq_clone_RigidBody_bool>`
* Turn gravity on or off: :ref:`useGravity <function-rigid_body_component__dot__rq_useGravity_rq_clone_RigidBody_bool>`
* Make the object either dynamic or kinematic: :ref:`motionType <function-rigid_body_component__dot__rq_motionType_rq_clone_RigidBody_MotionType>`
* Disable collisions between objects by assigning a collision layer: :ref:`collisionLayer <function-collider_component__dot__rq_collisionlayer_rq_clone_Collider_uint8>`
* Enable continuous collision detection (CCD): :ref:`collisionDetection <function-rigid_body_component__dot__rq_collisionDetection_rq_clone_RigidBody_CollisionDetection>`
* Prevent the object from rotating: :ref:`allowedDofs <function-rigid_body_component__dot__rq_allowedDofs_rq_clone_RigidBody_AllowedDofs>`
* Wake up sleeping objects: :ref:`isSleeping <function-rigid_body_component__dot__rq_isSleeping_rq_clone_RigidBody_bool>`
* Prevent jittering of fast-moving objects: :ref:`interpolation <function-rigid_body_component__dot__rq_interpolation_rq_clone_RigidBody_Interpolation>`

.. note::
    Some fields of the RigidBody component (``velocity``, ``angularVelocity``, and ``isSleeping``) are not serialized and will not be saved when the prefab is saved.

+++++++
Classes
+++++++

.. _struct-rigid_body_component-RigidBody:

.. das:attribute:: RigidBody : NativeComponent

Adds physical movement to an object.

Example::

    add_component(node, new RigidBody())



:Properties:

.. _function-rigid_body_component__dot__rq_enabled_RigidBody:

.. das:operator:: RigidBody.enabled() : bool



.. _function-rigid_body_component__dot__rq_enabled_rq_clone_RigidBody_bool:

.. das:operator:: RigidBody.enabled =(value: bool)

Whether the physics engine is enabled for the body. Setting this to ``false`` disables physics for the body completely. Default is ``true``.

:Arguments: * **value** : bool

.. _function-rigid_body_component__dot__rq_mass_RigidBody:

.. das:operator:: RigidBody.mass() : float



.. _function-rigid_body_component__dot__rq_mass_rq_clone_RigidBody_float:

.. das:operator:: RigidBody.mass =(value: float)

The mass of the object. The more mass an object has, the more difficult it is for it to accelerate or change its velocity. This value can only be positive. Default is 1.

:Arguments: * **value** : float

.. _function-rigid_body_component__dot__rq_linearDamping_RigidBody:

.. das:operator:: RigidBody.linearDamping() : float



.. _function-rigid_body_component__dot__rq_linearDamping_rq_clone_RigidBody_float:

.. das:operator:: RigidBody.linearDamping =(value: float)

The rate at which an object's velocity decreases over time due to air resistance or other forms of friction. The formula used to calculate this effect is: ``dv/dt = -linearDamping * v``. See the :ref:`guide <stdlib_physics_core_friction_damping_guide>` on how to setup damping. Default is 0.05.

:Arguments: * **value** : float

.. _function-rigid_body_component__dot__rq_angularDamping_RigidBody:

.. das:operator:: RigidBody.angularDamping() : float



.. _function-rigid_body_component__dot__rq_angularDamping_rq_clone_RigidBody_float:

.. das:operator:: RigidBody.angularDamping =(value: float)

The rate at which an object's angular velocity decreases over time due to air resistance or other forms of friction. The formula used to calculate this effect is: ``dw/dt = -angularDamping * w``. See the :ref:`guide <stdlib_physics_core_friction_damping_guide>` on how to setup damping. Default is 0.05.

:Arguments: * **value** : float

.. _function-rigid_body_component__dot__rq_useGravity_RigidBody:

.. das:operator:: RigidBody.useGravity() : bool



.. _function-rigid_body_component__dot__rq_useGravity_rq_clone_RigidBody_bool:

.. das:operator:: RigidBody.useGravity =(value: bool)

Determines whether or not gravity should be applied to the object. When set to false, gravity will be disabled for this particular body. To disable gravity globally, consider using the ``set_gravity(float3(0))`` function. Default is true.

:Arguments: * **value** : bool

.. _function-rigid_body_component__dot__rq_motionType_RigidBody:

.. das:operator:: RigidBody.motionType() : MotionType



.. _function-rigid_body_component__dot__rq_motionType_rq_clone_RigidBody_MotionType:

.. das:operator:: RigidBody.motionType =(value: MotionType)

Determines how an object moves and interacts with other objects in a physics simulation. See :ref:`MotionType <enum-public_components-MotionType>` for details. Default is Dynamic.

:Arguments: * **value** :  :ref:`MotionType <enum-public_components-MotionType>` 

.. _function-rigid_body_component__dot__rq_collisionDetection_RigidBody:

.. das:operator:: RigidBody.collisionDetection() : CollisionDetection



.. _function-rigid_body_component__dot__rq_collisionDetection_rq_clone_RigidBody_CollisionDetection:

.. das:operator:: RigidBody.collisionDetection =(value: CollisionDetection)

Determines how collisions are detected and resolved in a physics simulation.  See :ref:`CollisionDetection <enum-public_components-CollisionDetection>` for details. Default is Discrete.

:Arguments: * **value** :  :ref:`CollisionDetection <enum-public_components-CollisionDetection>` 

.. _function-rigid_body_component__dot__rq_allowedDofs_RigidBody:

.. das:operator:: RigidBody.allowedDofs() : AllowedDofs



.. _function-rigid_body_component__dot__rq_allowedDofs_rq_clone_RigidBody_AllowedDofs:

.. das:operator:: RigidBody.allowedDofs =(value: AllowedDofs)

A bitmask that determines which degrees of freedom (DoFs) are allowed for the rigid body. The DoFs can be used to restrict the body's movement or rotation in specific directions. For example, to make the body 2D, you can use ``AllowedDofs.AllowedDofs2D``. Default is ``AllowedDofs.AllowedDofsAll``, which allows all 3D DoFs.

:Arguments: * **value** :  :ref:`AllowedDofs <alias-AllowedDofs>` 

.. _function-rigid_body_component__dot__rq_velocity_RigidBody:

.. das:operator:: RigidBody.velocity() : float3



.. _function-rigid_body_component__dot__rq_velocity_rq_clone_RigidBody_float3:

.. das:operator:: RigidBody.velocity =(value: float3)

Current velocity of a body

.. note::
    This field is not serialized and is not saved to the prefab.

:Arguments: * **value** : float3

.. _function-rigid_body_component__dot__rq_angularVelocity_RigidBody:

.. das:operator:: RigidBody.angularVelocity() : float3



.. _function-rigid_body_component__dot__rq_angularVelocity_rq_clone_RigidBody_float3:

.. das:operator:: RigidBody.angularVelocity =(value: float3)

Current angular velocity of a body, expressed as euler angles in radians per second

.. note::
    This field is not serialized and is not saved to the prefab.

:Arguments: * **value** : float3

.. _function-rigid_body_component__dot__rq_isSleeping_RigidBody:

.. das:operator:: RigidBody.isSleeping() : bool



.. _function-rigid_body_component__dot__rq_isSleeping_rq_clone_RigidBody_bool:

.. das:operator:: RigidBody.isSleeping =(value: bool)

When then body is not moving for some time, it goes to sleep, and the physics worlds stop simulating it. It can be awaken by colliding with another body. This is just an optimization, so try not to base your game logic on this value.

.. note::
    This field is not serialized and is not saved to the prefab.

:Arguments: * **value** : bool

.. _function-rigid_body_component__dot__rq_maxVelocity_RigidBody:

.. das:operator:: RigidBody.maxVelocity() : float



.. _function-rigid_body_component__dot__rq_maxVelocity_rq_clone_RigidBody_float:

.. das:operator:: RigidBody.maxVelocity =(value: float)

Maximum velocity allowed for this rigid body

:Arguments: * **value** : float

.. _function-rigid_body_component__dot__rq_maxAngularVelocity_RigidBody:

.. das:operator:: RigidBody.maxAngularVelocity() : float



.. _function-rigid_body_component__dot__rq_maxAngularVelocity_rq_clone_RigidBody_float:

.. das:operator:: RigidBody.maxAngularVelocity =(value: float)

Maximum angular velocity allowed for this rigid body

:Arguments: * **value** : float

.. _function-rigid_body_component__dot__rq_interpolation_RigidBody:

.. das:operator:: RigidBody.interpolation() : Interpolation



.. _function-rigid_body_component__dot__rq_interpolation_rq_clone_RigidBody_Interpolation:

.. das:operator:: RigidBody.interpolation =(value: Interpolation)

Determines how the body's visual position is calculated between physics updates. See :ref:`Interpolation <enum-public_components-Interpolation>` for details. Default is ``None``

:Arguments: * **value** :  :ref:`Interpolation <enum-public_components-Interpolation>`