Rigid Body¶

struct nvRigidBody¶

Rigid body struct.

A rigid body is a non deformable object with mass in space. It can be affected by various forces and constraints depending on its type.

Few things to consider to keep the simulation accurate and stable:

If you want to move bodies in space, applying forces may be a better solution than changing velocities directly. Changing transforms (positions and angles) basically means teleporting them around so you should avoid it unless you know what you are doing.
In order to not lose floating point precision, it’s best to not variate sizes of dynamic bodies too much. This of course depends on the application, but considering the penetration slop setting, keeping the size range around 0.5 and 10.0 would be sufficient in a game.

struct nvRigidBodyInitializer¶

Rigid body initializer information.

This struct holds basic information for initializing bodies and can be reused for multiple bodies.

Enums¶

enum nvRigidBodyType¶

Rigid body type enumerator.

Values:

enumerator nvRigidBodyType_STATIC¶: Static bodies do not get affected or moved by any force in the simulation. They behave like they have infinite mass. Generally all terrain and ground objects are static bodies in games.

enumerator nvRigidBodyType_DYNAMIC¶: Dynamic bodies interact with all the other objects in the space and are effected by all forces, gravity and collisions in the simulation. Their mass is calculated by their shape, and unless you know what you’re doing, it’s not recommended to change their mass manually. However, if you want a dynamic body that can’t rotate, you can set it’s inertia to 0.

Methods¶

nvRigidBody *nvRigidBody_new(nvRigidBodyInitializer init)¶

Create a new body.

When you add the rigid body to a space, space is responsible for the memory management. When you call nvSpace_free it releases all resources it has. But if you removed the body or never added it in the first place, you have to manage the memory. Same thing applies to shapes, if you didn’t attach a shape to a body you have to free it yourself.

Returns NULL on error. Use nv_get_error to get more information.

Parameters:: init – Initializer info
Returns:: nvRigidBody *

void nvRigidBody_free(nvRigidBody *body)¶

Free body.

It’s safe to pass NULL to this function.

Parameters:: body – Body to free

void nvRigidBody_set_user_data(nvRigidBody *body, void *data)¶

Set user data.

Parameters:

body – Body
data – Void pointer to user data

void *nvRigidBody_get_user_data(const nvRigidBody *body)¶

Get user data.

Parameters:: body – Body
Returns:: void *

struct nvSpace *nvRigidBody_get_space(const nvRigidBody *body)¶

Get the space instance body belongs to.

Parameters:: body – Body
Returns:: nvSpace *

nv_uint32 nvRigidBody_get_id(const nvRigidBody *body)¶

Get unique identity number of the body.

Parameters:: body –
Returns:: nv_uint32

int nvRigidBody_set_type(nvRigidBody *body, nvRigidBodyType type)¶

Set motion type of the body.

Returns non-zero on error. Use nv_get_error to get more information.

Parameters:

body – Body
type – Type

nvRigidBodyType nvRigidBody_get_type(const nvRigidBody *body)¶

Get motion type of the body.

Parameters:: body – Body
Returns:: nvRigidBodyType

void nvRigidBody_set_position(nvRigidBody *body, nvVector2 new_position)¶

Set position (center of mass) of body in space.

Parameters:

body – Body
new_position – New position vector

nvVector2 nvRigidBody_get_position(const nvRigidBody *body)¶

Get position (center of mass) of body in space.

Parameters:: body – Body
Returns:: nvVector2 Position vector

void nvRigidBody_set_angle(nvRigidBody *body, nv_float new_angle)¶

Set angle (rotation) of body in radians.

If you want to rotate dynamic bodies in a physically accurate manner, applying torques should be the preferred approach. See nvRigidBody_apply_torque

Parameters:

body –
new_angle –

nv_float nvRigidBody_get_angle(const nvRigidBody *body)¶

Get angle (rotation) of body in radians.

Parameters:: body –
Returns:: nv_float

void nvRigidBody_set_linear_velocity(nvRigidBody *body, nvVector2 new_velocity)¶

Set linear velocity of body.

Parameters:

body – Body
new_position – New velocity vector

nvVector2 nvRigidBody_get_linear_velocity(const nvRigidBody *body)¶

Get linear velocity of body.

Parameters:: body – Body
Returns:: nvVector2 Velocity vector

void nvRigidBody_set_angular_velocity(nvRigidBody *body, nv_float new_velocity)¶

Set angular velocity of body.

If you want to rotate dynamic bodies in a physically accurate manner, applying torques should be the preferred approach. See nvRigidBody_apply_torque

Parameters:

body – Body
new_velocity – New velocity

nv_float nvRigidBody_get_angular_velocity(const nvRigidBody *body)¶

Get angular velocity of body.

Parameters:: body – Body
Returns:: nv_float

void nvRigidBody_set_linear_damping_scale(nvRigidBody *body, nv_float scale)¶

Set body’s linear velocity damping factor.

The default value 1.0 (100%) means the velocity damping applied to body is not affected.

Parameters:

body – Body
scale – Scaling factor

nv_float nvRigidBody_get_linear_damping_scale(const nvRigidBody *body)¶

Get body’s linear velocity damping factor.

The default value 1.0 (100%) means the velocity damping applied to body is not affected.

Parameters:: body – Body
Returns:: nv_float

void nvRigidBody_set_angular_damping_scale(nvRigidBody *body, nv_float scale)¶

Set body’s angular velocity damping factor.

The default value 1.0 (100%) means the velocity damping applied to body is not affected.

Parameters:

body – Body
scale – Scaling factor

nv_float nvRigidBody_get_angular_damping_scale(const nvRigidBody *body)¶

Get body’s angular velocity damping factor.

The default value 1.0 (100%) means the velocity damping applied to body is not affected.

Parameters:: body – Body
Returns:: nv_float

void nvRigidBody_set_gravity_scale(nvRigidBody *body, nv_float scale)¶

Set gravity scaling factor of body.

The default value 1.0 (100%) means the global gravity applied to body is not affected.

Parameters:

body – Body
scale – Scaling factor

nv_float nvRigidBody_get_gravity_scale(const nvRigidBody *body)¶

get gravity scaling factor of body.

The default value 1.0 (100%) means the global gravity applied to body is not affected.

Parameters:: body – Body
Returns:: nv_float

void nvRigidBody_set_material(nvRigidBody *body, nvMaterial material)¶

Set material of body.

Parameters:

body – Body
material – Material

nvMaterial nvRigidBody_get_material(const nvRigidBody *body)¶

Get material of body.

Parameters:: body – Body
Returns:: nvMaterial

int nvRigidBody_set_mass(nvRigidBody *body, nv_float mass)¶

Set mass of the body.

Ideally you wouldn’t need to set mass manually because it is calculated as you add shapes to the body.

Returns non-zero on error. Use nv_get_error to get more information.

Note

Currently this doesn’t change inertia with the new mass, so use at your own risk.

Parameters:

body – Body
mass – Mass

Returns:

int Status

nv_float nvRigidBody_get_mass(const nvRigidBody *body)¶

Get mass of the body.

Parameters:: body – Body
Returns:: nv_float

void nvRigidBody_set_inertia(nvRigidBody *body, nv_float inertia)¶

Set inertia of the body.

If you want to disable rotation you can set inertia to 0.

Parameters:

body – Body
inertia – Moment of inertia

nv_float nvRigidBody_get_inertia(const nvRigidBody *body)¶

Get inertia of the body.

Parameters:: body – Body
Returns:: nv_float

void nvRigidBody_set_collision_group(nvRigidBody *body, nv_uint32 group)¶

Set collision group of body.

Bodies that share the same non-zero group do not collide.

Parameters:

body –
group –

nv_uint32 nvRigidBody_get_collision_group(const nvRigidBody *body)¶

Get collision group of body.

Bodies that share the same non-zero group do not collide.

Parameters:: body – Body
Returns:: nv_uint32

void nvRigidBody_set_collision_category(nvRigidBody *body, nv_uint32 category)¶

Set collision category of body.

This is a bitmask defining this body’s collision category.

Parameters:

body – Body
category – Category bitmask

nv_uint32 nvRigidBody_get_collision_category(const nvRigidBody *body)¶

Get collision category of body.

This is a bitmask defining this body’s collision category.

Parameters:: body – Body
Returns:: nv_uint32

void nvRigidBody_set_collision_mask(nvRigidBody *body, nv_uint32 mask)¶

Set collision mask of body.

This is a bitmask defining this body’s collision mask.

Parameters:

body – Body
category – Mask

nv_uint32 nvRigidBody_get_collision_mask(const nvRigidBody *body)¶

Get collision mask of body.

This is a bitmask defining this body’s collision mask.

Parameters:: body – Body
Returns:: nv_uint32

int nvRigidBody_add_shape(nvRigidBody *body, nvShape *shape)¶

Add a shape to the body.

Returns non-zero on error. Use nv_get_error to get more information.

Parameters:

body – Body
shape – Shape

Returns:

int Status

int nvRigidBody_remove_shape(nvRigidBody *body, nvShape *shape)¶

Remove a shape from the body.

Returns non-zero on error. Use nv_get_error to get more information.

Parameters:

body – Body
shape – Shape

Returns:

int Status

nv_bool nvRigidBody_iter_shapes(nvRigidBody *body, nvShape **shape, size_t *index)¶

Iterate over this rigid body’s shapes.

Make sure to reset the index if you alter the shapes in any way while iterating.

Parameters:

body – Body
cons – Pointer to shape
index – Pointer to iteration index

Returns:

nv_bool

void nvRigidBody_apply_force(nvRigidBody *body, nvVector2 force)¶

Apply force to body at its center of mass.

Parameters:

body – Body to apply force on
force – Force

void nvRigidBody_apply_force_at(nvRigidBody *body, nvVector2 force, nvVector2 position)¶

Apply force to body at some local point.

Parameters:

body – Body to apply force on
force – Force
position – Local point to apply force at

void nvRigidBody_apply_torque(nvRigidBody *body, nv_float torque)¶

Apply torque to body.

Parameters:

body – Body to apply torque on
torque – Torque

void nvRigidBody_apply_impulse(nvRigidBody *body, nvVector2 impulse, nvVector2 position)¶

Apply impulse to body at some local point.

An impulse is a sudden change of velocity. Reason of this function existing is mainly for internal use.

Parameters:

body – Body to apply impulse on
impulse – Impulse
position – Local point to apply impulse at

void nvRigidBody_enable_collisions(nvRigidBody *body)¶

Enable collisions for this body.

If this is disabled, the body doesn’t collide with anything at all.

Parameters:: body – Body

void nvRigidBody_disable_collisions(nvRigidBody *body)¶

Disable collisions for this body.

If this is disabled, the body doesn’t collide with anything at all.

Parameters:: body – Body

void nvRigidBody_reset_velocities(nvRigidBody *body)¶

Set all velocities and forces of the body to 0.

Parameters:: body – Body

nvAABB nvRigidBody_get_aabb(nvRigidBody *body)¶

Get AABB (Axis-Aligned Bounding Box) of the body.

Parameters:: body – Body
Returns:: nvAABB

nv_float nvRigidBody_get_kinetic_energy(const nvRigidBody *body)¶

Get kinetic energy of the body in joules.

Parameters:: body – Body
Returns:: nv_float

nv_float nvRigidBody_get_rotational_energy(const nvRigidBody *body)¶

Get rotational kinetic energy of the body in joules.

Parameters:: body – Body
Returns:: nv_float