Body

This is the body API. More...

Data Structures
struct	b3MotionLocks
	Motion locks to restrict the body movement. More...
struct	b3BodyDef
	A body definition holds all the data needed to construct a rigid body. More...

Enumerations
enum	b3BodyType { b3_staticBody = 0 , b3_kinematicBody = 1 , b3_dynamicBody = 2 , b3_bodyTypeCount }
	The body simulation type. More...

Functions
b3BodyId	b3CreateBody (b3WorldId worldId, const b3BodyDef *def)
	Create a rigid body given a definition.
void	b3DestroyBody (b3BodyId bodyId)
	Destroy a rigid body given an id.
bool	b3Body_IsValid (b3BodyId id)
	Body identifier validation.
b3BodyType	b3Body_GetType (b3BodyId bodyId)
	Get the body type: static, kinematic, or dynamic.
void	b3Body_SetType (b3BodyId bodyId, b3BodyType type)
	Change the body type.
void	b3Body_SetName (b3BodyId bodyId, const char *name)
	Set the body name. Up to B3_BODY_NAME_LENGTH characters including null termination.
const char *	b3Body_GetName (b3BodyId bodyId)
	Get the body name.
void	b3Body_SetUserData (b3BodyId bodyId, void *userData)
	Set the user data for a body.
void *	b3Body_GetUserData (b3BodyId bodyId)
	Get the user data stored in a body.
b3Pos	b3Body_GetPosition (b3BodyId bodyId)
	Get the world position of a body. This is the location of the body origin.
b3Quat	b3Body_GetRotation (b3BodyId bodyId)
	Get the world rotation of a body as a quaternion.
b3WorldTransform	b3Body_GetTransform (b3BodyId bodyId)
	Get the world transform of a body.
void	b3Body_SetTransform (b3BodyId bodyId, b3Pos position, b3Quat rotation)
	Set the world transform of a body.
b3Vec3	b3Body_GetLocalPoint (b3BodyId bodyId, b3Pos worldPoint)
	Get a local point on a body given a world point.
b3Pos	b3Body_GetWorldPoint (b3BodyId bodyId, b3Vec3 localPoint)
	Get a world point on a body given a local point.
b3Vec3	b3Body_GetLocalVector (b3BodyId bodyId, b3Vec3 worldVector)
	Get a local vector on a body given a world vector.
b3Vec3	b3Body_GetWorldVector (b3BodyId bodyId, b3Vec3 localVector)
	Get a world vector on a body given a local vector.
b3Vec3	b3Body_GetLinearVelocity (b3BodyId bodyId)
	Get the linear velocity of a body's center of mass. Usually in meters per second.
b3Vec3	b3Body_GetAngularVelocity (b3BodyId bodyId)
	Get the angular velocity of a body in radians per second.
void	b3Body_SetLinearVelocity (b3BodyId bodyId, b3Vec3 linearVelocity)
	Set the linear velocity of a body. Usually in meters per second.
void	b3Body_SetAngularVelocity (b3BodyId bodyId, b3Vec3 angularVelocity)
	Set the angular velocity of a body in radians per second.
void	b3Body_SetTargetTransform (b3BodyId bodyId, b3WorldTransform target, float timeStep, bool wake)
	Set the velocity to reach the given transform after a given time step.
b3Vec3	b3Body_GetLocalPointVelocity (b3BodyId bodyId, b3Vec3 localPoint)
	Get the linear velocity of a local point attached to a body. Usually in meters per second.
b3Vec3	b3Body_GetWorldPointVelocity (b3BodyId bodyId, b3Pos worldPoint)
	Get the linear velocity of a world point attached to a body. Usually in meters per second.
void	b3Body_ApplyForce (b3BodyId bodyId, b3Vec3 force, b3Pos point, bool wake)
	Apply a force at a world point.
void	b3Body_ApplyForceToCenter (b3BodyId bodyId, b3Vec3 force, bool wake)
	Apply a force to the center of mass.
void	b3Body_ApplyTorque (b3BodyId bodyId, b3Vec3 torque, bool wake)
	Apply a torque.
void	b3Body_ApplyLinearImpulse (b3BodyId bodyId, b3Vec3 impulse, b3Pos point, bool wake)
	Apply an impulse at a point.
void	b3Body_ApplyLinearImpulseToCenter (b3BodyId bodyId, b3Vec3 impulse, bool wake)
	Apply an impulse to the center of mass.
void	b3Body_ApplyAngularImpulse (b3BodyId bodyId, b3Vec3 impulse, bool wake)
	Apply an angular impulse in world space.
float	b3Body_GetMass (b3BodyId bodyId)
	Get the mass of the body, usually in kilograms.
b3Matrix3	b3Body_GetLocalRotationalInertia (b3BodyId bodyId)
	Get the rotational inertia of the body in local space, usually in kg*m^2.
float	b3Body_GetInverseMass (b3BodyId bodyId)
	Get the inverse mass of the body, usually in 1/kilograms.
b3Matrix3	b3Body_GetWorldInverseRotationalInertia (b3BodyId bodyId)
	Get the inverse rotational inertia of the body in world space, usually in 1/kg*m^2.
b3Vec3	b3Body_GetLocalCenterOfMass (b3BodyId bodyId)
	Get the center of mass position of the body in local space.
b3Pos	b3Body_GetWorldCenterOfMass (b3BodyId bodyId)
	Get the center of mass position of the body in world space.
void	b3Body_SetMassData (b3BodyId bodyId, b3MassData massData)
	Override the body's mass properties.
b3MassData	b3Body_GetMassData (b3BodyId bodyId)
	Get the mass data for a body.
void	b3Body_ApplyMassFromShapes (b3BodyId bodyId)
	This updates the mass properties to the sum of the mass properties of the shapes.
void	b3Body_SetLinearDamping (b3BodyId bodyId, float linearDamping)
	Adjust the linear damping. Normally this is set in b3BodyDef before creation.
float	b3Body_GetLinearDamping (b3BodyId bodyId)
	Get the current linear damping.
void	b3Body_SetAngularDamping (b3BodyId bodyId, float angularDamping)
	Adjust the angular damping. Normally this is set in b3BodyDef before creation.
float	b3Body_GetAngularDamping (b3BodyId bodyId)
	Get the current angular damping.
void	b3Body_SetGravityScale (b3BodyId bodyId, float gravityScale)
	Adjust the gravity scale.
float	b3Body_GetGravityScale (b3BodyId bodyId)
	Get the current gravity scale.
bool	b3Body_IsAwake (b3BodyId bodyId)
void	b3Body_SetAwake (b3BodyId bodyId, bool awake)
	Wake a body from sleep.
void	b3Body_EnableSleep (b3BodyId bodyId, bool enableSleep)
	Enable or disable sleeping for this body. If sleeping is disabled the body will wake.
bool	b3Body_IsSleepEnabled (b3BodyId bodyId)
	Returns true if sleeping is enabled for this body.
void	b3Body_SetSleepThreshold (b3BodyId bodyId, float sleepThreshold)
	Set the sleep threshold, usually in meters per second.
float	b3Body_GetSleepThreshold (b3BodyId bodyId)
	Get the sleep threshold, usually in meters per second.
bool	b3Body_IsEnabled (b3BodyId bodyId)
	Returns true if this body is enabled.
void	b3Body_Disable (b3BodyId bodyId)
	Disable a body by removing it completely from the simulation. This is expensive.
void	b3Body_Enable (b3BodyId bodyId)
	Enable a body by adding it to the simulation. This is expensive.
void	b3Body_SetMotionLocks (b3BodyId bodyId, b3MotionLocks locks)
	Set the motion locks on this body.
b3MotionLocks	b3Body_GetMotionLocks (b3BodyId bodyId)
	Get the motion locks for this body.
void	b3Body_SetBullet (b3BodyId bodyId, bool flag)
	Set this body to be a bullet.
bool	b3Body_IsBullet (b3BodyId bodyId)
	Is this body a bullet?
void	b3Body_EnableContactRecycling (b3BodyId bodyId, bool flag)
	Enable or disable contact recycling for this body.
bool	b3Body_IsContactRecyclingEnabled (b3BodyId bodyId)
	Is contact recycling enabled on this body?
void	b3Body_EnableHitEvents (b3BodyId bodyId, bool enableHitEvents)
	Enable/disable hit events on all shapes.
b3WorldId	b3Body_GetWorld (b3BodyId bodyId)
	Get the world that owns this body.
int	b3Body_GetShapeCount (b3BodyId bodyId)
	Get the number of shapes on this body.
int	b3Body_GetShapes (b3BodyId bodyId, b3ShapeId *shapeArray, int capacity)
	Get the shape ids for all shapes on this body, up to the provided capacity.
int	b3Body_GetJointCount (b3BodyId bodyId)
	Get the number of joints on this body.
int	b3Body_GetJoints (b3BodyId bodyId, b3JointId *jointArray, int capacity)
	Get the joint ids for all joints on this body, up to the provided capacity.
int	b3Body_GetContactCapacity (b3BodyId bodyId)
	Get the maximum capacity required for retrieving all the touching contacts on a body.
int	b3Body_GetContactData (b3BodyId bodyId, b3ContactData *contactData, int capacity)
	Get the touching contact data for a body.
b3AABB	b3Body_ComputeAABB (b3BodyId bodyId)
	Get the current world AABB that contains all the attached shapes.
float	b3Body_GetClosestPoint (b3BodyId bodyId, b3Vec3 *result, b3Vec3 target)
	Get the closest point on a body to a world target.
b3BodyCastResult	b3Body_CastRay (b3BodyId bodyId, b3Pos origin, b3Vec3 translation, b3QueryFilter filter, float maxFraction, b3WorldTransform bodyTransform)
	Cast a ray at a specific body using a specified body transform.
b3BodyCastResult	b3Body_CastShape (b3BodyId bodyId, b3Pos origin, const b3ShapeProxy *proxy, b3Vec3 translation, b3QueryFilter filter, float maxFraction, bool canEncroach, b3WorldTransform bodyTransform)
	Cast a shape at a specific body using a specified body transform.
bool	b3Body_OverlapShape (b3BodyId bodyId, b3Pos origin, const b3ShapeProxy *proxy, b3QueryFilter filter, b3WorldTransform bodyTransform)
	Overlap a shape with a specific body using a specified body transform.
int	b3Body_CollideMover (b3BodyId bodyId, b3BodyPlaneResult *bodyPlanes, int planeCapacity, b3Pos origin, const b3Capsule *mover, b3QueryFilter filter, b3WorldTransform bodyTransform)
	Collide a character mover with a specific body using a specified body transform.
b3BodyDef	b3DefaultBodyDef (void)
	Use this to initialize your body definition.

Detailed Description

This is the body API.

---

Data Structure Documentation

b3MotionLocks

struct b3MotionLocks

Motion locks to restrict the body movement.

Data Fields
bool	angularX	Prevent rotation around the x-axis.
bool	angularY	Prevent rotation around the y-axis.
bool	angularZ	Prevent rotation around the z-axis.
bool	linearX	Prevent translation along the x-axis.
bool	linearY	Prevent translation along the y-axis.
bool	linearZ	Prevent translation along the z-axis.

b3BodyDef

struct b3BodyDef

A body definition holds all the data needed to construct a rigid body.

You can safely re-use body definitions. Shapes are added to a body after construction. Body definitions are temporary objects used to bundle creation parameters. Must be initialized using b3DefaultBodyDef().

Collaboration diagram for b3BodyDef:

Data Fields
bool	allowFastRotation	This allows this body to bypass rotational speed limits. Should only be used for circular objects, like wheels.
float	angularDamping	Angular damping is used to reduce the angular velocity. The damping parameter can be larger than 1.0f but the damping effect becomes sensitive to the time step when the damping parameter is large. Angular damping can be used to slow down rotating bodies.
b3Vec3	angularVelocity	The initial angular velocity of the body. Radians per second.
bool	enableContactRecycling	Enable contact recycling. True by default. Leaving this enabled improves performance but may lead to ghost collision that should be avoided on characters.
bool	enableSleep	Set this flag to false if this body should never fall asleep.
float	gravityScale	Scale the gravity applied to this body. Non-dimensional.
int	internalValue	Used internally to detect a valid definition. DO NOT SET.
bool	isAwake	Is this body initially awake or sleeping?
bool	isBullet	Treat this body as a high speed object that performs continuous collision detection against dynamic and kinematic bodies, but not other bullet bodies. Warning Bullets should be used sparingly. They are not a solution for general dynamic-versus-dynamic continuous collision. They do not guarantee accurate collision if both bodies are fast moving because the bullet does a continuous check after all non-bullet bodies have moved. You could get unlucky and have the bullet body end a time step very close to a non-bullet body and the non-bullet body then moves over the bullet body. In continuous collision, initial overlap is ignored to avoid freezing bodies in place. I do not recommend using them for game projectiles if precise collision timing is needed. Instead consider using a ray or shape cast. You can use a marching ray or shape cast for projectile that moves over time. If you want a fast moving projectile to collide with a fast moving target, you need to consider the relative movement in your ray or shape cast. This is out of the scope of Box3D. So what are good use cases for bullets? Pinball games or games with dynamic containers that hold other objects. It should be a use case where it doesn't break the game if there is a collision missed, but having them captured improves the quality of the game.
bool	isEnabled	Used to disable a body. A disabled body does not move or collide.
float	linearDamping	Linear damping is used to reduce the linear velocity. The damping parameter can be larger than 1 but the damping effect becomes sensitive to the time step when the damping parameter is large. Generally linear damping is undesirable because it makes objects move slowly as if they are floating.
b3Vec3	linearVelocity	The initial linear velocity of the body's origin. Usually in meters per second.
b3MotionLocks	motionLocks	Motions locks to restrict linear and angular movement.
const char *	name	Optional body name for debugging. Up to B3_BODY_NAME_LENGTH characters (including null termination).
b3Pos	position	The initial world position of the body. Bodies should be created with the desired position. Note Creating bodies at the origin and then moving them nearly doubles the cost of body creation, especially if the body is moved after shapes have been added.
b3Quat	rotation	The initial world rotation of the body.
float	sleepThreshold	Sleep speed threshold, default is 0.05 meters per second.
b3BodyType	type	The body type: static, kinematic, or dynamic.
void *	userData	Use this to store application specific body data.

Enumeration Type Documentation

b3BodyType

enum b3BodyType

The body simulation type.

Each body is one of these three types. The type determines how the body behaves in the simulation.

Enumerator
b3_staticBody	zero mass, zero velocity, may be manually moved
b3_kinematicBody	zero mass, velocity set by user, moved by solver
b3_dynamicBody	positive mass, velocity determined by forces, moved by solver
b3_bodyTypeCount	number of body types

Function Documentation

b3Body_ApplyAngularImpulse()

void b3Body_ApplyAngularImpulse	(	b3BodyId	bodyId,
		b3Vec3	impulse,
		bool	wake )

Apply an angular impulse in world space.

The impulse is ignored if the body is not awake. This optionally wakes the body.

Parameters

bodyId	The body id
impulse	the world angular impulse vector, usually in units of kg*m*m/s
wake	also wake up the body

Warning

This should be used for one-shot impulses. If you need a steady torque, use a torque instead, which will work better with the sub-stepping solver.

b3Body_ApplyForce()

void b3Body_ApplyForce	(	b3BodyId	bodyId,
		b3Vec3	force,
		b3Pos	point,
		bool	wake )

Apply a force at a world point.

If the force is not applied at the center of mass, it will generate a torque and affect the angular velocity. This optionally wakes up the body. The force is ignored if the body is not awake.

Parameters

bodyId	The body id
force	The world force vector, usually in newtons (N)
point	The world position of the point of application
wake	Option to wake up the body

b3Body_ApplyForceToCenter()

void b3Body_ApplyForceToCenter	(	b3BodyId	bodyId,
		b3Vec3	force,
		bool	wake )

Apply a force to the center of mass.

This optionally wakes up the body. The force is ignored if the body is not awake.

Parameters

bodyId	The body id
force	the world force vector, usually in newtons (N).
wake	also wake up the body

b3Body_ApplyLinearImpulse()

void b3Body_ApplyLinearImpulse	(	b3BodyId	bodyId,
		b3Vec3	impulse,
		b3Pos	point,
		bool	wake )

Apply an impulse at a point.

This immediately modifies the velocity. It also modifies the angular velocity if the point of application is not at the center of mass. This optionally wakes the body. The impulse is ignored if the body is not awake.

Parameters

bodyId	The body id
impulse	the world impulse vector, usually in N*s or kg*m/s.
point	the world position of the point of application.
wake	also wake up the body

Warning

This should be used for one-shot impulses. If you need a steady force, use a force instead, which will work better with the sub-stepping solver.

b3Body_ApplyLinearImpulseToCenter()

void b3Body_ApplyLinearImpulseToCenter	(	b3BodyId	bodyId,
		b3Vec3	impulse,
		bool	wake )

Apply an impulse to the center of mass.

This immediately modifies the velocity. The impulse is ignored if the body is not awake. This optionally wakes the body.

Parameters

bodyId	The body id
impulse	the world impulse vector, usually in N*s or kg*m/s.
wake	also wake up the body

Warning

This should be used for one-shot impulses. If you need a steady force, use a force instead, which will work better with the sub-stepping solver.

b3Body_ApplyMassFromShapes()

void b3Body_ApplyMassFromShapes

(

b3BodyId

bodyId

)

This updates the mass properties to the sum of the mass properties of the shapes.

This normally does not need to be called unless you called SetMassData to override the mass and you later want to reset the mass. You may also use this when automatic mass computation has been disabled. You should call this regardless of body type.

b3Body_ApplyTorque()

void b3Body_ApplyTorque	(	b3BodyId	bodyId,
		b3Vec3	torque,
		bool	wake )

Apply a torque.

This affects the angular velocity without affecting the linear velocity. This optionally wakes the body. The torque is ignored if the body is not awake.

Parameters

bodyId	The body id
torque	the world torque vector, usually in N*m.
wake	also wake up the body

b3Body_ComputeAABB()

b3AABB b3Body_ComputeAABB

(

b3BodyId

bodyId

)

Get the current world AABB that contains all the attached shapes.

Note that this may not encompass the body origin. If there are no shapes attached then the returned AABB is empty and centered on the body origin.

b3Body_EnableContactRecycling()

void b3Body_EnableContactRecycling	(	b3BodyId	bodyId,
		bool	flag )

Enable or disable contact recycling for this body.

Contact recycling is a performance optimization that reuses contact manifolds when bodies move slightly. Disabling it can avoid ghost collisions on characters at the cost of higher per-step work. Existing contacts retain their prior setting; only contacts created after this call see the new value.

See also

b3BodyDef::enableContactRecycling

b3Body_EnableHitEvents()

void b3Body_EnableHitEvents	(	b3BodyId	bodyId,
		bool	enableHitEvents )

Enable/disable hit events on all shapes.

See also

b3ShapeDef::enableHitEvents

b3Body_GetJoints()

int b3Body_GetJoints	(	b3BodyId	bodyId,
		b3JointId *	jointArray,
		int	capacity )

Get the joint ids for all joints on this body, up to the provided capacity.

Returns

the number of joint ids stored in the user array

b3Body_GetShapes()

int b3Body_GetShapes	(	b3BodyId	bodyId,
		b3ShapeId *	shapeArray,
		int	capacity )

Get the shape ids for all shapes on this body, up to the provided capacity.

Returns

the number of shape ids stored in the user array

b3Body_IsAwake()

bool b3Body_IsAwake

(

b3BodyId

bodyId

)

Returns

true if this body is awake

b3Body_IsValid()

bool b3Body_IsValid

(

b3BodyId

id

)

Body identifier validation.

A valid body exists in a world and is non-null. This can be used to detect orphaned ids. Provides validation for up to 64K allocations.

b3Body_SetAwake()

void b3Body_SetAwake	(	b3BodyId	bodyId,
		bool	awake )

Wake a body from sleep.

This wakes the entire island the body is touching.

Warning

Putting a body to sleep will put the entire island of bodies touching this body to sleep, which can be expensive and possibly unintuitive.

b3Body_SetBullet()

void b3Body_SetBullet	(	b3BodyId	bodyId,
		bool	flag )

Set this body to be a bullet.

A bullet does continuous collision detection against dynamic bodies (but not other bullets).

b3Body_SetGravityScale()

void b3Body_SetGravityScale	(	b3BodyId	bodyId,
		float	gravityScale )

Adjust the gravity scale.

Normally this is set in b3BodyDef before creation.

See also

b3BodyDef::gravityScale

b3Body_SetMassData()

void b3Body_SetMassData	(	b3BodyId	bodyId,
		b3MassData	massData )

Override the body's mass properties.

Normally this is computed automatically using the shape geometry and density. This information is lost if a shape is added or removed or if the body type changes.

b3Body_SetTargetTransform()

void b3Body_SetTargetTransform	(	b3BodyId	bodyId,
		b3WorldTransform	target,
		float	timeStep,
		bool	wake )

Set the velocity to reach the given transform after a given time step.

The result will be close but maybe not exact. This is meant for kinematic bodies. The target is not applied if the velocity would be below the sleep threshold. This will optionally wake the body if asleep, but only if the movement is significant.

b3Body_SetTransform()

void b3Body_SetTransform	(	b3BodyId	bodyId,
		b3Pos	position,
		b3Quat	rotation )

Set the world transform of a body.

This acts as a teleport and is fairly expensive.

Note

Generally you should create a body with the intended transform.

See also

b3BodyDef::position and b3BodyDef::rotation

b3Body_SetType()

void b3Body_SetType	(	b3BodyId	bodyId,
		b3BodyType	type )

Change the body type.

This is an expensive operation. This automatically updates the mass properties regardless of the automatic mass setting.

b3CreateBody()

b3BodyId b3CreateBody	(	b3WorldId	worldId,
		const b3BodyDef *	def )

Create a rigid body given a definition.

No reference to the definition is retained. So you can create the definition on the stack and pass it as a pointer.

b3BodyDef bodyDef = b3DefaultBodyDef();
b3BodyId myBodyId = b3CreateBody(myWorldId, &bodyDef);

Warning

This function is locked during callbacks.

b3DestroyBody()

void b3DestroyBody

(

b3BodyId

bodyId

)

Destroy a rigid body given an id.

This destroys all shapes and joints attached to the body. Do not keep references to the associated shapes and joints.