Box2D 3.1.0
A 2D physics engine for games
Loading...
Searching...
No Matches
Body

This is the body API. More...

Data Structures

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

Enumerations

enum  b2BodyType { b2_staticBody = 0 , b2_kinematicBody = 1 , b2_dynamicBody = 2 , b2_bodyTypeCount }
 The body simulation type. More...
 

Functions

b2BodyId b2CreateBody (b2WorldId worldId, const b2BodyDef *def)
 Create a rigid body given a definition.
 
void b2DestroyBody (b2BodyId bodyId)
 Destroy a rigid body given an id.
 
bool b2Body_IsValid (b2BodyId id)
 Body identifier validation. Can be used to detect orphaned ids. Provides validation for up to 64K allocations.
 
b2BodyType b2Body_GetType (b2BodyId bodyId)
 Get the body type: static, kinematic, or dynamic.
 
void b2Body_SetType (b2BodyId bodyId, b2BodyType type)
 Change the body type.
 
void b2Body_SetUserData (b2BodyId bodyId, void *userData)
 Set the user data for a body.
 
void * b2Body_GetUserData (b2BodyId bodyId)
 Get the user data stored in a body.
 
b2Vec2 b2Body_GetPosition (b2BodyId bodyId)
 Get the world position of a body. This is the location of the body origin.
 
b2Rot b2Body_GetRotation (b2BodyId bodyId)
 Get the world rotation of a body as a cosine/sine pair (complex number)
 
b2Transform b2Body_GetTransform (b2BodyId bodyId)
 Get the world transform of a body.
 
void b2Body_SetTransform (b2BodyId bodyId, b2Vec2 position, b2Rot rotation)
 Set the world transform of a body.
 
b2Vec2 b2Body_GetLocalPoint (b2BodyId bodyId, b2Vec2 worldPoint)
 Get a local point on a body given a world point.
 
b2Vec2 b2Body_GetWorldPoint (b2BodyId bodyId, b2Vec2 localPoint)
 Get a world point on a body given a local point.
 
b2Vec2 b2Body_GetLocalVector (b2BodyId bodyId, b2Vec2 worldVector)
 Get a local vector on a body given a world vector.
 
b2Vec2 b2Body_GetWorldVector (b2BodyId bodyId, b2Vec2 localVector)
 Get a world vector on a body given a local vector.
 
b2Vec2 b2Body_GetLinearVelocity (b2BodyId bodyId)
 Get the linear velocity of a body's center of mass. Typically in meters per second.
 
float b2Body_GetAngularVelocity (b2BodyId bodyId)
 Get the angular velocity of a body in radians per second.
 
void b2Body_SetLinearVelocity (b2BodyId bodyId, b2Vec2 linearVelocity)
 Set the linear velocity of a body. Typically in meters per second.
 
void b2Body_SetAngularVelocity (b2BodyId bodyId, float angularVelocity)
 Set the angular velocity of a body in radians per second.
 
void b2Body_ApplyForce (b2BodyId bodyId, b2Vec2 force, b2Vec2 point, bool wake)
 Apply a force at a world point.
 
void b2Body_ApplyForceToCenter (b2BodyId bodyId, b2Vec2 force, bool wake)
 Apply a force to the center of mass.
 
void b2Body_ApplyTorque (b2BodyId bodyId, float torque, bool wake)
 Apply a torque.
 
void b2Body_ApplyLinearImpulse (b2BodyId bodyId, b2Vec2 impulse, b2Vec2 point, bool wake)
 Apply an impulse at a point.
 
void b2Body_ApplyLinearImpulseToCenter (b2BodyId bodyId, b2Vec2 impulse, bool wake)
 Apply an impulse to the center of mass.
 
void b2Body_ApplyAngularImpulse (b2BodyId bodyId, float impulse, bool wake)
 Apply an angular impulse.
 
float b2Body_GetMass (b2BodyId bodyId)
 Get the mass of the body, typically in kilograms.
 
float b2Body_GetRotationalInertia (b2BodyId bodyId)
 Get the rotational inertia of the body, typically in kg*m^2.
 
b2Vec2 b2Body_GetLocalCenterOfMass (b2BodyId bodyId)
 Get the center of mass position of the body in local space.
 
b2Vec2 b2Body_GetWorldCenterOfMass (b2BodyId bodyId)
 Get the center of mass position of the body in world space.
 
void b2Body_SetMassData (b2BodyId bodyId, b2MassData massData)
 Override the body's mass properties.
 
b2MassData b2Body_GetMassData (b2BodyId bodyId)
 Get the mass data for a body.
 
void b2Body_ApplyMassFromShapes (b2BodyId bodyId)
 This update the mass properties to the sum of the mass properties of the shapes.
 
void b2Body_SetAutomaticMass (b2BodyId bodyId, bool automaticMass)
 Set the automatic mass setting.
 
bool b2Body_GetAutomaticMass (b2BodyId bodyId)
 Get the automatic mass setting.
 
void b2Body_SetLinearDamping (b2BodyId bodyId, float linearDamping)
 Adjust the linear damping. Normally this is set in b2BodyDef before creation.
 
float b2Body_GetLinearDamping (b2BodyId bodyId)
 Get the current linear damping.
 
void b2Body_SetAngularDamping (b2BodyId bodyId, float angularDamping)
 Adjust the angular damping. Normally this is set in b2BodyDef before creation.
 
float b2Body_GetAngularDamping (b2BodyId bodyId)
 Get the current angular damping.
 
void b2Body_SetGravityScale (b2BodyId bodyId, float gravityScale)
 Adjust the gravity scale.
 
float b2Body_GetGravityScale (b2BodyId bodyId)
 Get the current gravity scale.
 
bool b2Body_IsAwake (b2BodyId bodyId)
 
void b2Body_SetAwake (b2BodyId bodyId, bool awake)
 Wake a body from sleep.
 
void b2Body_EnableSleep (b2BodyId bodyId, bool enableSleep)
 Enable or disable sleeping for this body. If sleeping is disabled the body will wake.
 
bool b2Body_IsSleepEnabled (b2BodyId bodyId)
 Returns true if sleeping is enabled for this body.
 
void b2Body_SetSleepThreshold (b2BodyId bodyId, float sleepThreshold)
 Set the sleep threshold, typically in meters per second.
 
float b2Body_GetSleepThreshold (b2BodyId bodyId)
 Get the sleep threshold, typically in meters per second.
 
bool b2Body_IsEnabled (b2BodyId bodyId)
 Returns true if this body is enabled.
 
void b2Body_Disable (b2BodyId bodyId)
 Disable a body by removing it completely from the simulation. This is expensive.
 
void b2Body_Enable (b2BodyId bodyId)
 Enable a body by adding it to the simulation. This is expensive.
 
void b2Body_SetFixedRotation (b2BodyId bodyId, bool flag)
 Set this body to have fixed rotation. This causes the mass to be reset in all cases.
 
bool b2Body_IsFixedRotation (b2BodyId bodyId)
 Does this body have fixed rotation?
 
void b2Body_SetBullet (b2BodyId bodyId, bool flag)
 Set this body to be a bullet.
 
bool b2Body_IsBullet (b2BodyId bodyId)
 Is this body a bullet?
 
void b2Body_EnableHitEvents (b2BodyId bodyId, bool enableHitEvents)
 Enable/disable hit events on all shapes.
 
int b2Body_GetShapeCount (b2BodyId bodyId)
 Get the number of shapes on this body.
 
int b2Body_GetShapes (b2BodyId bodyId, b2ShapeId *shapeArray, int capacity)
 Get the shape ids for all shapes on this body, up to the provided capacity.
 
int b2Body_GetJointCount (b2BodyId bodyId)
 Get the number of joints on this body.
 
int b2Body_GetJoints (b2BodyId bodyId, b2JointId *jointArray, int capacity)
 Get the joint ids for all joints on this body, up to the provided capacity.
 
int b2Body_GetContactCapacity (b2BodyId bodyId)
 Get the maximum capacity required for retrieving all the touching contacts on a body.
 
int b2Body_GetContactData (b2BodyId bodyId, b2ContactData *contactData, int capacity)
 Get the touching contact data for a body.
 
b2AABB b2Body_ComputeAABB (b2BodyId bodyId)
 Get the current world AABB that contains all the attached shapes.
 
b2BodyDef b2DefaultBodyDef (void)
 Use this to initialize your body definition.
 

Detailed Description

This is the body API.


Data Structure Documentation

◆ b2BodyDef

struct b2BodyDef

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 b2DefaultBodyDef().

Collaboration diagram for b2BodyDef:
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 use 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 use slow down rotating bodies.

float angularVelocity The initial angular velocity of the body. Radians per second.
bool automaticMass Automatically compute mass and related properties on this body from shapes.

Triggers whenever a shape is add/removed/changed. Default is true.

bool enableSleep Set this flag to false if this body should never fall asleep.
bool fixedRotation Should this body be prevented from rotating? Useful for characters.
float gravityScale Scale the gravity applied to this body. Non-dimensional.
int32_t 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 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 may interfere with joint constraints.
bool isEnabled Used to disable a body. A disabled body does not move or collide.
float linearDamping Linear damping is use 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.

b2Vec2 linearVelocity The initial linear velocity of the body's origin. Typically in meters per second.
b2Vec2 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.
b2Rot rotation The initial world rotation of the body. Use b2MakeRot() if you have an angle.
float sleepThreshold Sleep velocity threshold, default is 0.05 meter per second.
b2BodyType type The body type: static, kinematic, or dynamic.
void * userData Use this to store application specific body data.

Enumeration Type Documentation

◆ b2BodyType

enum b2BodyType

The body simulation type.

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

Enumerator
b2_staticBody 

zero mass, zero velocity, may be manually moved

b2_kinematicBody 

zero mass, velocity set by user, moved by solver

b2_dynamicBody 

positive mass, velocity determined by forces, moved by solver

b2_bodyTypeCount 

number of body types

Function Documentation

◆ b2Body_ApplyAngularImpulse()

void b2Body_ApplyAngularImpulse ( b2BodyId bodyId,
float impulse,
bool wake )

Apply an angular impulse.

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

Parameters
bodyIdThe body id
impulsethe angular impulse, typically in units of kg*m*m/s
wakealso 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.

◆ b2Body_ApplyForce()

void b2Body_ApplyForce ( b2BodyId bodyId,
b2Vec2 force,
b2Vec2 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
bodyIdThe body id
forceThe world force vector, typically in newtons (N)
pointThe world position of the point of application
wakeOption to wake up the body

◆ b2Body_ApplyForceToCenter()

void b2Body_ApplyForceToCenter ( b2BodyId bodyId,
b2Vec2 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
bodyIdThe body id
forcethe world force vector, usually in newtons (N).
wakealso wake up the body

◆ b2Body_ApplyLinearImpulse()

void b2Body_ApplyLinearImpulse ( b2BodyId bodyId,
b2Vec2 impulse,
b2Vec2 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
bodyIdThe body id
impulsethe world impulse vector, typically in N*s or kg*m/s.
pointthe world position of the point of application.
wakealso 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.

◆ b2Body_ApplyLinearImpulseToCenter()

void b2Body_ApplyLinearImpulseToCenter ( b2BodyId bodyId,
b2Vec2 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
bodyIdThe body id
impulsethe world impulse vector, typically in N*s or kg*m/s.
wakealso 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.

◆ b2Body_ApplyMassFromShapes()

void b2Body_ApplyMassFromShapes ( b2BodyId bodyId)

This update 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.

◆ b2Body_ApplyTorque()

void b2Body_ApplyTorque ( b2BodyId bodyId,
float 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
bodyIdThe body id
torqueabout the z-axis (out of the screen), typically in N*m.
wakealso wake up the body

◆ b2Body_ComputeAABB()

b2AABB b2Body_ComputeAABB ( b2BodyId 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.

◆ b2Body_EnableHitEvents()

void b2Body_EnableHitEvents ( b2BodyId bodyId,
bool enableHitEvents )

Enable/disable hit events on all shapes.

See also
b2ShapeDef::enableHitEvents

◆ b2Body_GetJoints()

int b2Body_GetJoints ( b2BodyId bodyId,
b2JointId * 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

◆ b2Body_GetShapes()

int b2Body_GetShapes ( b2BodyId bodyId,
b2ShapeId * 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

◆ b2Body_IsAwake()

bool b2Body_IsAwake ( b2BodyId bodyId)
Returns
true if this body is awake

◆ b2Body_SetAutomaticMass()

void b2Body_SetAutomaticMass ( b2BodyId bodyId,
bool automaticMass )

Set the automatic mass setting.

Normally this is set in b2BodyDef before creation.

See also
b2BodyDef::automaticMass

◆ b2Body_SetAwake()

void b2Body_SetAwake ( b2BodyId 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.

◆ b2Body_SetBullet()

void b2Body_SetBullet ( b2BodyId bodyId,
bool flag )

Set this body to be a bullet.

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

◆ b2Body_SetGravityScale()

void b2Body_SetGravityScale ( b2BodyId bodyId,
float gravityScale )

Adjust the gravity scale.

Normally this is set in b2BodyDef before creation.

See also
b2BodyDef::gravityScale

◆ b2Body_SetMassData()

void b2Body_SetMassData ( b2BodyId bodyId,
b2MassData 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.

◆ b2Body_SetTransform()

void b2Body_SetTransform ( b2BodyId bodyId,
b2Vec2 position,
b2Rot 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 then intended transform.
See also
b2BodyDef::position and b2BodyDef::angle

◆ b2Body_SetType()

void b2Body_SetType ( b2BodyId bodyId,
b2BodyType type )

Change the body type.

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

◆ b2CreateBody()

b2BodyId b2CreateBody ( b2WorldId worldId,
const b2BodyDef * 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.

b2BodyId myBodyId = b2CreateBody(myWorldId, &bodyDef);
b2BodyDef b2DefaultBodyDef(void)
Use this to initialize your body definition.
b2BodyId b2CreateBody(b2WorldId worldId, const b2BodyDef *def)
Create a rigid body given a definition.
A body definition holds all the data needed to construct a rigid body.
Definition types.h:146
Body id references a body instance. This should be treated as an opaque handle.
Definition id.h:45
Warning
This function is locked during callbacks.

◆ b2DestroyBody()

void b2DestroyBody ( b2BodyId 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.