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.

In the editor

The Rigid Body has a custom inspector for allowedDofs and centerOfMass. Rather than a plain field, the allowed degrees of freedom are shown as a grid of checkboxes — one per translation axis and one per rotation axis — so you can restrict the body’s movement and rotation per axis.

Networking

Replication of RigidBody is opt-in, see Replicated engine components. velocity, angularVelocity, isSleeping, centerOfMass, inertia and inertiaRotation stay local (not replicated).

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. By default, center of mass will be calculated based on shape, but it is overridden if this property is written to (or if “custom” checkmark in editor is set). To explicitly recalculate center of mass, use reset_center_of_mass function.

Arguments:

  • value : float3

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

Moment of inertia along principal axes. By default, inertia will be calculated based on shape, but it is overridden if this property is written to (or if “custom” checkmark in editor is set). Inertia is only applicable to dynamic bodies, so if you read from these properties from a kinematic body, irrelevant junk will be returned. To explicitly recalculate inertia, use reset_inertia function.

Arguments:

  • value : float3

RigidBody.inertiaRotation: quat4
RigidBody.inertiaRotation =(value: quat4)

Rotation of principal axes. See inertia for details.

Arguments:
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.

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: