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 Collider 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 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:

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

RigidBody : NativeComponent

Adds physical movement to an object.

Example:

add_component(node, new RigidBody())
Properties:

RigidBody.enabled: bool
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

RigidBody.mass: float
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

RigidBody.centerOfMass: float3
RigidBody.centerOfMass =(value: float3)

Position of the center of mass of the object, in local coordinates. Upon a body creation, an automatically calculated position is written to this property. You can mutate it to change the position.

Since center of mass influences inertia, changing this property will trigger inertia recalculation. So if you’ve set custom inertia, don’t forget to reapply it.

Usage example:

nodeId?.RigidBody.centerOfMass -= float3(0, .3, 0) // make center of mass a bit lower

Note

When you change shape of Collider in runtime, center of mass will be automatically recalculated. Make sure to reapply your changes in this case.

To explicitly recalculate center of mass, use reset_center_of_mass function.

Arguments:

  • value : float3

RigidBody.inertia: float3

Moment of inertia along principal axes. Upon a body creation, an automatically calculated inertia is written to this property. Inertia is only applicable to dynamic bodies, so if you read from these properties from a kinematic body, irrelevant junk will be returned.

This property is read-only, use set_inertia to mutate.

Note

When you change shape of Collider or center of mass in runtime, inertia and its rotation will be automatically recalculated. Make sure to reapply your changes in this case. To explicitly reset inertia, use reset_inertia function.

RigidBody.inertiaRotation: quat4

Rotation of principal axes. See inertia for details.

RigidBody.linearDamping: float
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 guide on how to setup damping. Default is 0.05.

Arguments:

  • value : float

RigidBody.angularDamping: float
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 guide on how to setup damping. Default is 0.05.

Arguments:

  • value : float

RigidBody.useGravity: bool
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

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

Determines how an object moves and interacts with other objects in a physics simulation. See MotionType for details. Default is Dynamic.

Arguments:
RigidBody.collisionDetection: CollisionDetection
RigidBody.collisionDetection =(value: CollisionDetection)

Determines how collisions are detected and resolved in a physics simulation. See CollisionDetection for details. Default is Discrete.

Arguments:
RigidBody.allowedDofs: AllowedDofs
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:
RigidBody.velocity: float3
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

RigidBody.angularVelocity: float3
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

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

When then body is not moving for some time, it goes to sleep, and then 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

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

Maximum velocity allowed for this rigid body

Arguments:

  • value : float

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

Maximum angular velocity allowed for this rigid body

Arguments:

  • value : float

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

Determines how the body’s visual position is calculated between physics updates. See Interpolation for details. Default is None

Arguments:

Functions

reset_center_of_mass(rb: RigidBody?)

Recalculate the center of mass of the body as if the body was just created. Note that, because center of mass influences inertia, this function will reset it as well.

Usage example:

nodeId?.RigidBody.reset_center_of_mass()
Arguments:
reset_inertia(rb: RigidBody?)

Recalculate the inertia of the body as if the body was just created.

Usage example:

nodeId?.RigidBody.reset_inertia()
Arguments:
set_inertia(rb: RigidBody?; inertia: float3; inertia_rotation: quat4 = quat4())

Set the inertia along principal axes and their rotation. Rotation can be omitted. This function exists because inertia and inertiaRotation must be written to simultaneously.

Inertia is only applicable to dynamic bodies, so nothing will happen if this function is called on a kinematic body.

Note

Because of how moment of inertia is stored internally, the values that will be written back to read properties might differ from values passed to this function.

Usage example:

nodeId.get_component($(rg : RigidBody?) {
    // flat disk that is tilted by 30 degrees
    rg.set_inertia(float3(1, 10, 1), quat4(30, 0, 0))
})
Arguments: