Chipmunk rigid bodies: cpBody

Type Definitions and Memory Management Functions

typedef void (*cpBodyVelocityFunc)(struct cpBody *body, cpVect gravity, cpFloat damping, cpFloat dt);
typedef void (*cpBodyPositionFunc)(struct cpBody *body, cpFloat dt);

Integration function types. See below for more information.

typedef struct cpBody{
	// *** Integration Functions.

	// Function that is called to integrate the body's velocity. (Defaults to cpBodyUpdateVelocity)
	cpBodyVelocityFunc velocity_func;
	
	// Function that is called to integrate the body's position. (Defaults to cpBodyUpdatePosition)
	cpBodyPositionFunc position_func;
	
	// *** Mass Properties
	
	// Mass and it's inverse.
	// Always use cpBodySetMass() whenever changing the mass as these values must agree.
	cpFloat m, m_inv;
	
	// Moment of inertia and it's inverse.
	// Always use cpBodySetMoment() whenever changing the moment as these values must agree.
	cpFloat i, i_inv;
	
	// *** Positional Properties
	
	// Linear components of motion (position, velocity, and force)
	cpVect p, v, f;
	
	// Angular components of motion (angle in radians, angular velocity, and torque)
	// Always use cpBodySetAngle() to set the angle of the body as a and rot must agree.
	cpFloat a, w, t;
	
	// Cached unit length vector representing the angle of the body.
	// Used for fast vector rotation using cpvrotate().
	cpVect rot;
	
	// *** User Definable Fields
	
	// User defined data pointer.
	void *data;
} cpBody;

This is the cpBody structure definition. The comments should be pretty self explanatory. Make a note of the linked fields as Chipmunk does some caching in the cpBody.

cpBody *cpBodyAlloc(void);
cpBody *cpBodyInit(cpBody *body, cpFloat m, cpFloat i);
cpBody *cpBodyNew(cpFloat m, cpFloat i);

void cpBodyDestroy(cpBody *body);
void cpBodyFree(cpBody *body);

Standard set of Chipmunk memory management functions. m and i are the mass and moment of inertia for the body.

Setters for Linked Values

Because several rigid body values are linked, (m/m_inv, i/i_inv, a/rot) don't set them explicitly. Use the following setter functions instead.

void cpBodySetMass(cpBody *body, cpFloat m);
void cpBodySetMoment(cpBody *body, cpFloat i);
void cpBodySetAngle(cpBody *body, cpFloat a);

Getters and Setters

While you MUST use the setters in the previous section. You are encouraged to use setters/getters for all properties.

Getters and setters will all be of the form:

cpFloat cpBodyGetMass(cpBody *body)
void cpBodySetMass(cpBody *body, cpFloat mass)

Integration Functions

void cpBodySlew(cpBody *body, cpVect pos, cpFloat dt)

Modify the velocity of the body so that it will move to the specified absolute coordinates in the next timestep. Intended for objects that are moved manually with a custom velocity integration function.

void cpBodyUpdateVelocity(cpBody *body, cpVect gravity, cpFloat damping, cpFloat dt)

Default rigid body velocity integration function. Updates the velocity of the body using Euler integration.

void cpBodyUpdatePosition(cpBody *body, cpFloat dt)

Default rigid body position integration function. Updates the position of the body using Euler integration. Unlike the velocity function, it's unlikely you'll want to override this function. If you do, make sure you understand it's source code as it's an important part of the collision/joint correction process.

Coordinate Conversion Functions

cpVect cpBodyLocal2World(cpBody *body, cpVect v)

Convert from body local coordinates to world space coordinates.

cpVect cpBodyWorld2Local(cpBody *body, cpVect v)

Convert from world space coordinates to body local coordinates.

Applying Forces and Torques

void cpBodyApplyImpulse(cpBody *body, cpVect j, cpVect r)

Apply the impulse j to body at a relative offset (important!) r from the center of gravity. Both r and j are in world coordinates.

void cpBodyResetForces(cpBody *body)

Zero both the forces and torques accumulated on body.

void cpBodyApplyForce(cpBody *body, cpVect f, cpVect r)

Apply (accumulate) the force f on body at a relative offset (important!) r from the center of gravity. Both r and f are in world coordinates.

void cpApplyDampedSpring(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat rlen, cpFloat k, cpFloat dmp, cpFloat dt)

Apply a spring force between bodies a and b at anchors anchr1 and anchr2 respectively. k is the spring constant (Young's modulus), rlen is the rest length of the spring, dmp is the damping constant (force/velocity), and dt is the time step to apply the force over. Note: not solving the damping forces in the impulse solver causes problems with large damping values. There is a new constraint type cpDampedSpring that should be used instead.

Notes

• Use forces to modify the rigid bodies if possible. This is likely to be the most stable.
• Modifying a body's velocity shouldn't necessarily be avoided, but applying large changes can cause strange results in the simulation. Experiment freely, but be warned.
• Don't modify a body's position every step unless you really know what you are doing. Otherwise you're likely to get the position/velocity badly out of sync.