Mass

Controls the mass and matching inertia of a Dynamic JoltBody.

Mass affects acceleration from forces, collision response, constraints, and gravity force. It is available only for Dynamic bodies with motion properties.

High-Level API#

body.set_mass(value)
body.get_mass()

Validation and behaviour#

• value must be finite and strictly greater than 0.
• set_mass() and get_mass() fail for Static and Kinematic bodies.
• Setting mass rescales the shape's native MassProperties to the requested mass and updates inertia consistently.
• The body's allowed degrees of freedom are preserved.
• Changing mass does not resize or replace the collision shape.

Creation option#

var heavy_box = jolt_box_create_dynamic(0, 0, 4, 1, 1, 1, {mass: 25});
heavy_box.set_mass(40);
show_debug_message(heavy_box.get_mass());

Without an explicit mass option, Jolt derives mass properties from the collision shape. If mass is invalid for the newly created body, high-level creation is atomic: the body is destroyed and the creator returns undefined.

Mass, force, and impulse#

Low-Level / Advanced API#

Inverse mass is read-only. The bridge explicitly rejects attempts to set it; use set_mass instead. Low-level functions expose numeric handles and native error state.

Setters return true on success and false on invalid input, an invalid or stale body, or an unsupported motion type. Getters return the requested value or undefined when the operation fails. Inspect jolt_get_error() for the high-level error.

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.