These functions allow you to create a simulation world. More...

Data Structures
struct	b2RayResult
	Result from b2World_CastRayClosest If there is initial overlap the fraction and normal will be zero while the point is an arbitrary point in the overlap region. More...
struct	b2Capacity
	Optional world capacities that can be used to avoid run-time allocations. More...
struct	b2WorldDef
	World definition used to create a simulation world. More...
struct	b2Profile
	Profiling data. More...
struct	b2Counters
	Counters that give details of the simulation size. More...
struct	b2ExplosionDef
	The explosion definition is used to configure options for explosions. More...

Typedefs
typedef void	b2TaskCallbackFcn(void *taskContext)
	Task interface This is the prototype for a Box2D task.
typedef void *	b2EnqueueTaskCallbackFcn(b2TaskCallbackFcn task, void taskContext, void *userContext)
	These functions can be provided to Box2D to invoke a task system.
typedef void	b2FinishTaskCallbackFcn(void userTask, void userContext)
	Finishes a user task object that wraps a Box2D task.
typedef float	b2FrictionCallbackFcn(float frictionA, uint64_t userMaterialIdA, float frictionB, uint64_t userMaterialIdB)
	Optional friction mixing callback.
typedef float	b2RestitutionCallbackFcn(float restitutionA, uint64_t userMaterialIdA, float restitutionB, uint64_t userMaterialIdB)
	Optional restitution mixing callback.
typedef bool	b2CustomFilterCallbackFcn(b2ShapeId shapeIdA, b2ShapeId shapeIdB, void *context)
	Prototype for a contact filter callback.
typedef void	b2PreSolveCallbackFcn(b2ShapeId shapeIdA, b2ShapeId shapeIdB, b2Manifold manifold, void context)
	Prototype for a pre-solve callback.
typedef bool	b2PreContinuousCallbackFcn(b2ShapeId shapeIdA, b2ShapeId shapeIdB, b2Pos point, b2Vec2 normal, void *context)
	Prototype for a pre-continuous callback.
typedef bool	b2OverlapResultCallbackFcn(b2ShapeId shapeId, void *context)
	Prototype callback for overlap queries.
typedef float	b2CastResultCallbackFcn(b2ShapeId shapeId, b2Pos point, b2Vec2 normal, float fraction, void *context)
	Prototype callback for ray and shape casts.

Functions
b2WorldId	b2CreateWorld (const b2WorldDef *def)
	Create a world for rigid body simulation.
void	b2DestroyWorld (b2WorldId worldId)
	Destroy a world.
bool	b2World_IsValid (b2WorldId id)
	World id validation. Provides validation for up to 64K allocations.
void	b2World_Step (b2WorldId worldId, float timeStep, int subStepCount)
	Simulate a world for one time step.
void	b2World_Draw (b2WorldId worldId, b2DebugDraw *draw)
	Call this to draw shapes and other debug draw data.
b2AABB	b2World_GetBounds (b2WorldId worldId)
	Call this to get the world bounds based on the union of all shape bounds.
b2BodyEvents	b2World_GetBodyEvents (b2WorldId worldId)
	Get the body events for the current time step.
b2SensorEvents	b2World_GetSensorEvents (b2WorldId worldId)
	Get sensor events for the current time step.
b2ContactEvents	b2World_GetContactEvents (b2WorldId worldId)
	Get contact events for the current time step.
b2JointEvents	b2World_GetJointEvents (b2WorldId worldId)
	Get the joint events for the current time step.
b2TreeStats	b2World_OverlapAABB (b2WorldId worldId, b2Pos origin, b2AABB aabb, b2QueryFilter filter, b2OverlapResultCallbackFcn fcn, void context)
	Overlap test for all shapes that potentially overlap the provided AABB.
b2TreeStats	b2World_OverlapShape (b2WorldId worldId, b2Pos origin, const b2ShapeProxy proxy, b2QueryFilter filter, b2OverlapResultCallbackFcn fcn, void *context)
	Overlap test for all shapes that overlap the provided shape proxy.
b2TreeStats	b2World_CastRay (b2WorldId worldId, b2Pos origin, b2Vec2 translation, b2QueryFilter filter, b2CastResultCallbackFcn fcn, void context)
	Cast a ray into the world to collect shapes in the path of the ray.
b2RayResult	b2World_CastRayClosest (b2WorldId worldId, b2Pos origin, b2Vec2 translation, b2QueryFilter filter)
	Cast a ray into the world to collect the closest hit.
b2TreeStats	b2World_CastShape (b2WorldId worldId, b2Pos origin, const b2ShapeProxy proxy, b2Vec2 translation, b2QueryFilter filter, b2CastResultCallbackFcn fcn, void *context)
	Cast a shape through the world.
float	b2World_CastMover (b2WorldId worldId, b2Pos origin, const b2Capsule *mover, b2Vec2 translation, b2QueryFilter filter)
	Cast a capsule mover through the world.
void	b2World_CollideMover (b2WorldId worldId, b2Pos origin, const b2Capsule mover, b2QueryFilter filter, b2PlaneResultCallbackFcn fcn, void *context)
	Collide a capsule mover with the world, gathering collision planes that can be fed to b2SolvePlanes.
void	b2World_EnableSleeping (b2WorldId worldId, bool flag)
	Enable/disable sleep.
bool	b2World_IsSleepingEnabled (b2WorldId worldId)
	Is body sleeping enabled?
void	b2World_EnableContinuous (b2WorldId worldId, bool flag)
	Enable/disable continuous collision between dynamic and static bodies.
bool	b2World_IsContinuousEnabled (b2WorldId worldId)
	Is continuous collision enabled?
void	b2World_SetRestitutionThreshold (b2WorldId worldId, float value)
	Adjust the restitution threshold.
float	b2World_GetRestitutionThreshold (b2WorldId worldId)
	Get the restitution speed threshold. Usually in meters per second.
void	b2World_SetRestitutionIterations (b2WorldId worldId, int iterations)
	Set the number of iterations used by the restitution solver.
int	b2World_GetRestitutionIterations (b2WorldId worldId)
	Get the number of iterations used by the restitution solver.
void	b2World_EnableRestitutionPropagation (b2WorldId worldId, bool flag)
	Enable/disable restitution propagation.
bool	b2World_IsRestitutionPropagationEnabled (b2WorldId worldId)
	Is restitution propagation enabled?
void	b2World_SetHitEventThreshold (b2WorldId worldId, float value)
	Adjust the hit event threshold.
float	b2World_GetHitEventThreshold (b2WorldId worldId)
	Get the hit event speed threshold. Usually in meters per second.
void	b2World_SetCustomFilterCallback (b2WorldId worldId, b2CustomFilterCallbackFcn fcn, void context)
	Register the custom filter callback. This is optional.
void	b2World_SetPreSolveCallback (b2WorldId worldId, b2PreSolveCallbackFcn preSolveFcn, b2PreContinuousCallbackFcn preContinuousFcn, void *context)
	Register the pre-solve and pre-continuous callbacks. This is optional.
void	b2World_SetGravity (b2WorldId worldId, b2Vec2 gravity)
	Set the gravity vector for the entire world.
b2Vec2	b2World_GetGravity (b2WorldId worldId)
	Get the gravity vector.
void	b2World_Explode (b2WorldId worldId, const b2ExplosionDef *explosionDef)
	Apply a radial explosion.
void	b2World_SetContactTuning (b2WorldId worldId, float hertz, float dampingRatio, float pushSpeed)
	Adjust contact tuning parameters.
void	b2World_GetContactTuning (b2WorldId worldId, float hertz, float dampingRatio, float *pushSpeed)
	Get the contact tuning.
void	b2World_SetContactRecycleDistance (b2WorldId worldId, float recycleDistance)
	Set the contact point recycling distance.
float	b2World_GetContactRecycleDistance (b2WorldId worldId)
	Get the contact point recycling distance. Usually in meters.
void	b2World_SetMaxLinearSpeed (b2WorldId worldId, float maximumLinearSpeed)
	Set the maximum linear speed. Usually in m/s.
float	b2World_GetMaxLinearSpeed (b2WorldId worldId)
	Get the maximum linear speed. Usually in m/s.
void	b2World_EnableWarmStarting (b2WorldId worldId, bool flag)
	Enable/disable constraint warm starting.
bool	b2World_IsWarmStartingEnabled (b2WorldId worldId)
	Is constraint warm starting enabled?
void	b2World_EnableSSE2Fallback (b2WorldId worldId, bool flag)
	Force SSE2 to be used even when AVX2 is available. This is for testing.
int	b2World_GetAwakeBodyCount (b2WorldId worldId)
	Get the number of awake bodies.
b2Profile	b2World_GetProfile (b2WorldId worldId)
	Get the current world performance profile.
b2Counters	b2World_GetCounters (b2WorldId worldId)
	Get world counters and sizes.
b2Capacity	b2World_GetMaxCapacity (b2WorldId worldId)
	Get max capacity. This can be used with b2WorldDef to avoid run-time allocations and copies.
void	b2World_SetUserData (b2WorldId worldId, void *userData)
	Set the user data pointer.
void *	b2World_GetUserData (b2WorldId worldId)
	Get the user data pointer.
void	b2World_SetFrictionCallback (b2WorldId worldId, b2FrictionCallbackFcn *callback)
	Set the friction callback. Passing NULL resets to default.
void	b2World_SetRestitutionCallback (b2WorldId worldId, b2RestitutionCallbackFcn *callback)
	Set the restitution callback. Passing NULL resets to default.
void	b2World_SetWorkerCount (b2WorldId worldId, int count)
	Set the worker count. Must be in the range [1, B2_MAX_WORKERS].
int	b2World_GetWorkerCount (b2WorldId worldId)
	Get the worker count.
void	b2World_DumpMemoryStats (b2WorldId worldId)
	Dump memory stats to box2d_memory.txt.
void	b2World_RebuildStaticTree (b2WorldId worldId)
	This is for internal testing.
uint64_t	b2World_GetStateHash (b2WorldId worldId)
	Compute a hash of the simulation state.
b2WorldDef	b2DefaultWorldDef (void)
	Use this to initialize your world definition.
b2ExplosionDef	b2DefaultExplosionDef (void)
	Use this to initialize your explosion definition.

Detailed Description

These functions allow you to create a simulation world.

You can add rigid bodies and joint constraints to the world and run the simulation. You can get contact information to get contact points and normals as well as events. You can query the world, checking for overlaps and casting rays or shapes. There is also debugging information such as debug draw, timing information, and counters. You can find documentation here: https://box2d.org/

Data Structure Documentation

◆ b2RayResult

struct b2RayResult

Result from b2World_CastRayClosest If there is initial overlap the fraction and normal will be zero while the point is an arbitrary point in the overlap region.

Data Fields
float	fraction	The fraction of the input ray.
bool	hit	Did the ray hit? If false, all other data is invalid.
int	leafVisits	The number of BVH leaves visited. Diagnostic.
int	nodeVisits	The number of BVH nodes visited. Diagnostic.
b2Vec2	normal	The unit normal vector at the point of contact.
b2Pos	point	The point of contact, on the surface of the hit shape.
b2ShapeId	shapeId	The shape hit.

◆ b2Capacity

struct b2Capacity

Optional world capacities that can be used to avoid run-time allocations.

See also: b2World_GetMaxCapacity

Data Fields
int	arenaByteCount	Reserve arena allocator space, used for temporary allocations.
int	contactCount	Number of expected contacts.
int	dynamicBodyCount	Number of expected dynamic and kinematic bodies.
int	dynamicShapeCount	Number of expected dynamic and kinematic shapes.
int	staticBodyCount	Number of expected static bodies.
int	staticShapeCount	Number of expected static shapes.

◆ b2WorldDef

struct b2WorldDef

World definition used to create a simulation world.

Must be initialized using b2DefaultWorldDef().

Data Fields
b2Capacity	capacity	Optional initial capacities.
float	contactDampingRatio	Contact bounciness. Non-dimensional. You can speed up overlap recovery by decreasing this with the trade-off that overlap resolution becomes more energetic.
float	contactHertz	Contact stiffness. Cycles per second. Increasing this increases the speed of overlap recovery, but can introduce jitter.
float	contactSpeed	This parameter controls how fast overlap is resolved and usually has units of meters per second. This only puts a cap on the resolution speed. The resolution speed is increased by increasing the hertz and/or decreasing the damping ratio.
bool	enableContinuous	Enable continuous collision.
bool	enableRestitutionPropagation	Enable full contact propagation in the restitution solver. Expensive. (Experimental).
bool	enableSleep	Can bodies go to sleep to improve performance.
b2EnqueueTaskCallbackFcn *	enqueueTask	Function to spawn tasks.
b2FinishTaskCallbackFcn *	finishTask	Function to finish a task.
b2FrictionCallbackFcn *	frictionCallback	Optional mixing callback for friction. The default uses sqrt(frictionA * frictionB).
b2Vec2	gravity	Gravity vector. Box2D has no up-vector defined.
float	hitEventThreshold	Threshold speed for hit events. Usually meters per second.
int	internalValue	Used internally to detect a valid definition. DO NOT SET.
float	maximumLinearSpeed	Maximum linear speed. Usually meters per second.
b2RestitutionCallbackFcn *	restitutionCallback	Optional mixing callback for restitution. The default uses max(restitutionA, restitutionB).
int	restitutionIterations	Number of iterations of the restitution solver. More iterations can lead to less box spinning. See also B2_MAX_RESTITUTION_ITERATIONS
float	restitutionThreshold	Restitution speed threshold, usually in m/s. Collisions above this speed have restitution applied (will bounce).
void *	userData	User data.
void *	userTaskContext	User context that is provided to enqueueTask and finishTask.
int	workerCount	Number of workers for multithreading. Box2D performs best when using performance cores and accessing a single L3 cache (uniform memory). Efficiency cores and SMT provide little benefit and may even harm performance. This is clamped to the range [1, B2_MAX_WORKERS]. If task callbacks are provided then Box2D will use the user provided task system. If no task callbacks are installed then Box2D will run single-threaded with a worker count of 1, or use the internal scheduler with a worker count greater than 1.

◆ b2Profile

struct b2Profile

Profiling data.

Times are in milliseconds.

Data Fields
float	bullets
float	collide
float	constraints
float	hitEvents
float	integratePositions
float	integrateVelocities
float	jointEvents
float	pairs
float	prepareConstraints
float	refit
float	relaxImpulses
float	restitution
float	sensorHits
float	sensors
float	sleepIslands
float	solve
float	solveImpulses
float	solverSetup
float	splitIslands
float	step
float	storeImpulses
float	transforms
float	warmStart

◆ b2Counters

struct b2Counters

Counters that give details of the simulation size.

Data Fields
int	awakeContactCount	Number of contacts touched by the collide pass (graph contacts + awake-set non-touching).
int	bodyCount
size_t	byteCount
int	colorCounts[24]
int	contactCount
int	islandCount
int	jointCount
int	recycledContactCount	Number of contacts recycled in the most recent step.
int	shapeCount
int	stackUsed
int	staticTreeHeight
int	taskCount
int	treeHeight

◆ b2ExplosionDef

struct b2ExplosionDef

The explosion definition is used to configure options for explosions.

Explosions consider shape geometry when computing the impulse.

Data Fields
float	falloff	The falloff distance beyond the radius. Impulse is reduced to zero at this distance.
float	impulsePerLength	Impulse per unit length. This applies an impulse according to the shape perimeter that is facing the explosion. Explosions only apply to circles, capsules, and polygons. This may be negative for implosions.
uint64_t	maskBits	Mask bits to filter shapes.
b2Pos	position	The center of the explosion in world space.
float	radius	The radius of the explosion.

Typedef Documentation

◆ b2CastResultCallbackFcn

typedef float b2CastResultCallbackFcn(b2ShapeId shapeId, b2Pos point, b2Vec2 normal, float fraction, void *context)

Prototype callback for ray and shape casts.

Called for each shape found in the query. You control how the ray cast proceeds by returning a float:

return -1: ignore this shape and continue
return 0: terminate the ray cast
return fraction: clip the ray to this point

return 1: don't clip the ray and continue A cast with initial overlap will return a zero fraction and a zero normal.

Parameters

shapeId	the shape hit by the ray
point	the point of initial intersection
normal	the normal vector at the point of intersection, zero for a shape cast with initial overlap
fraction	the fraction along the ray at the point of intersection, zero for a shape cast with initial overlap
context	the user context

Returns: -1 to filter, 0 to terminate, fraction to clip the ray for closest hit, 1 to continue

See also: b2World_CastRay

◆ b2CustomFilterCallbackFcn

typedef bool b2CustomFilterCallbackFcn(b2ShapeId shapeIdA, b2ShapeId shapeIdB, void *context)

Prototype for a contact filter callback.

This is called when a contact pair is considered for collision. This allows you to perform custom logic to prevent collision between shapes. This is only called if one of the two shapes has custom filtering enabled. Notes:

this function must be thread-safe
this is only called if one of the two shapes has enabled custom filtering
this may be called for awake dynamic bodies and sensors Return false if you want to disable the collision
See also
b2ShapeDef

Warning
Do not attempt to modify the world inside this callback

◆ b2EnqueueTaskCallbackFcn

typedef void * b2EnqueueTaskCallbackFcn(b2TaskCallbackFcn *task, void *taskContext, void *userContext)

These functions can be provided to Box2D to invoke a task system.

Returns a pointer to the user's task object. May be nullptr. A nullptr indicates to Box2D that the work was executed serially within the callback and there is no need to call b2FinishTaskCallbackFcn.

◆ b2FrictionCallbackFcn

typedef float b2FrictionCallbackFcn(float frictionA, uint64_t userMaterialIdA, float frictionB, uint64_t userMaterialIdB)

Optional friction mixing callback.

This intentionally provides no context objects because this is called from a worker thread.

Warning: This function should not attempt to modify Box2D state or user application state.

◆ b2OverlapResultCallbackFcn

typedef bool b2OverlapResultCallbackFcn(b2ShapeId shapeId, void *context)

Prototype callback for overlap queries.

Called for each shape found in the query.

See also: b2World_OverlapAABB

Returns: false to terminate the query.

◆ b2PreContinuousCallbackFcn

typedef bool b2PreContinuousCallbackFcn(b2ShapeId shapeIdA, b2ShapeId shapeIdB, b2Pos point, b2Vec2 normal, void *context)

Prototype for a pre-continuous callback.

This is called when a time of impact event is computed in continuous collision. This function can be used to skip the event. Unlike the pre-solve callback, this only supplies the point and normal. At this stage of the solver the manifold may not exist or may be stale. Notes:

this function must be thread-safe
this is only called if the shape has enabled pre-solve events
this is called only for awake dynamic bodies
this is not called for sensors Return false if you want to disable the time of impact event.
Warning
Do not attempt to modify the world inside this callback

◆ b2PreSolveCallbackFcn

typedef void b2PreSolveCallbackFcn(b2ShapeId shapeIdA, b2ShapeId shapeIdB, b2Manifold *manifold, void *context)

Prototype for a pre-solve callback.

This is called after a contact manifold is updated. This allows you to inspect a manifold before it goes to the solver. If you are careful, you can modify the manifold (e.g. modify the normal). You can set the manifold point count to zero to disable collision. Notes:

this function must be thread-safe
this is only called if the shape has enabled pre-solve events
this is called only for awake dynamic bodies
this is not called for sensors
the supplied manifold impulses are not reliable
Warning
Do not attempt to modify the world inside this callback

◆ b2RestitutionCallbackFcn

typedef float b2RestitutionCallbackFcn(float restitutionA, uint64_t userMaterialIdA, float restitutionB, uint64_t userMaterialIdB)

Optional restitution mixing callback.

This intentionally provides no context objects because this is called from a worker thread.

Warning: This function should not attempt to modify Box2D state or user application state.

◆ b2TaskCallbackFcn

typedef void b2TaskCallbackFcn(void *taskContext)

Task interface This is the prototype for a Box2D task.

Your task system is expected to run this callback on a worker thread, exactly once per enqueue, passing back the same taskContext pointer supplied to b2EnqueueTaskCallbackFcn.

Function Documentation

◆ b2CreateWorld()

b2WorldId b2CreateWorld ( const b2WorldDef * def )

Create a world for rigid body simulation.

A world contains bodies, shapes, and constraints. You may create up to B2_MAX_WORLDS worlds. Each world is completely independent and may be simulated in parallel.

Returns: the world id.

◆ b2World_CastMover()

float b2World_CastMover	(	b2WorldId	worldId,
		b2Pos	origin,
		const b2Capsule *	mover,
		b2Vec2	translation,
		b2QueryFilter	filter )

Cast a capsule mover through the world.

This is a special shape cast that handles sliding along other shapes while reducing clipping. The mover capsule is relative to the origin. Near the origin pass b2Pos_zero and a world capsule. Returns the translation fraction at the first hit.

◆ b2World_CastRay()

b2TreeStats b2World_CastRay	(	b2WorldId	worldId,
		b2Pos	origin,
		b2Vec2	translation,
		b2QueryFilter	filter,
		b2CastResultCallbackFcn *	fcn,
		void *	context )

Cast a ray into the world to collect shapes in the path of the ray.

Your callback function controls whether you get the closest point, any point, or n-points.

Note: The callback function may receive shapes in any order

Parameters

worldId	The world to cast the ray against
origin	The start point of the ray
translation	The translation of the ray from the start point to the end point
filter	Contains bit flags to filter unwanted shapes from the results
fcn	A user implemented callback function
context	A user context that is passed along to the callback function

Returns: traversal performance counters

◆ b2World_CastRayClosest()

b2RayResult b2World_CastRayClosest	(	b2WorldId	worldId,
		b2Pos	origin,
		b2Vec2	translation,
		b2QueryFilter	filter )

Cast a ray into the world to collect the closest hit.

This is a convenience function. Ignores initial overlap. This is less general than b2World_CastRay() and does not allow for custom filtering.

◆ b2World_CastShape()

b2TreeStats b2World_CastShape	(	b2WorldId	worldId,
		b2Pos	origin,
		const b2ShapeProxy *	proxy,
		b2Vec2	translation,
		b2QueryFilter	filter,
		b2CastResultCallbackFcn *	fcn,
		void *	context )

Cast a shape through the world.

Similar to a ray cast except that a shape is cast instead of a point. The proxy points are relative to the origin. Callback points are world positions.

See also: b2World_CastRay

◆ b2World_CollideMover()

void b2World_CollideMover	(	b2WorldId	worldId,
		b2Pos	origin,
		const b2Capsule *	mover,
		b2QueryFilter	filter,
		b2PlaneResultCallbackFcn *	fcn,
		void *	context )

Collide a capsule mover with the world, gathering collision planes that can be fed to b2SolvePlanes.

Useful for kinematic character movement. The mover capsule and the resulting planes are relative to the origin.

◆ b2World_EnableContinuous()

void b2World_EnableContinuous	(	b2WorldId	worldId,
		bool	flag )

Enable/disable continuous collision between dynamic and static bodies.

Generally you should keep continuous collision enabled to prevent fast moving objects from going through static objects. The performance gain from disabling continuous collision is minor.

See also: b2WorldDef

◆ b2World_EnableRestitutionPropagation()

void b2World_EnableRestitutionPropagation	(	b2WorldId	worldId,
		bool	flag )

Enable/disable restitution propagation.

See also: b2WorldDef::enableRestitutionPropagation

◆ b2World_EnableSleeping()

void b2World_EnableSleeping	(	b2WorldId	worldId,
		bool	flag )

Enable/disable sleep.

If your application does not need sleeping, you can gain some performance by disabling sleep completely at the world level.

See also: b2WorldDef

◆ b2World_EnableWarmStarting()

void b2World_EnableWarmStarting	(	b2WorldId	worldId,
		bool	flag )

Enable/disable constraint warm starting.

Advanced feature for testing. Disabling warm starting greatly reduces stability and provides no performance gain.

◆ b2World_Explode()

void b2World_Explode	(	b2WorldId	worldId,
		const b2ExplosionDef *	explosionDef )

Apply a radial explosion.

Parameters

worldId	The world id
explosionDef	The explosion definition

◆ b2World_GetBodyEvents()

b2BodyEvents b2World_GetBodyEvents ( b2WorldId worldId )

Get the body events for the current time step.

The event data is transient. Do not store a reference to this data.

◆ b2World_GetContactEvents()

b2ContactEvents b2World_GetContactEvents ( b2WorldId worldId )

Get contact events for the current time step.

The event data is transient. Do not store a reference to this data.

◆ b2World_GetJointEvents()

b2JointEvents b2World_GetJointEvents ( b2WorldId worldId )

Get the joint events for the current time step.

The event data is transient. Do not store a reference to this data.

◆ b2World_GetSensorEvents()

b2SensorEvents b2World_GetSensorEvents ( b2WorldId worldId )

Get sensor events for the current time step.

The event data is transient. Do not store a reference to this data.

◆ b2World_GetStateHash()

uint64_t b2World_GetStateHash ( b2WorldId worldId )

Compute a hash of the simulation state.

Use this to detect desyncs, for example in rollback resimulation.

◆ b2World_OverlapAABB()

b2TreeStats b2World_OverlapAABB	(	b2WorldId	worldId,
		b2Pos	origin,
		b2AABB	aabb,
		b2QueryFilter	filter,
		b2OverlapResultCallbackFcn *	fcn,
		void *	context )

Overlap test for all shapes that potentially overlap the provided AABB.

The AABB is relative to the origin, which keeps the test precise far from the world origin in large world mode. Near the origin pass b2Pos_zero and a world AABB.

◆ b2World_OverlapShape()

b2TreeStats b2World_OverlapShape	(	b2WorldId	worldId,
		b2Pos	origin,
		const b2ShapeProxy *	proxy,
		b2QueryFilter	filter,
		b2OverlapResultCallbackFcn *	fcn,
		void *	context )

Overlap test for all shapes that overlap the provided shape proxy.

The proxy points are relative to the origin. Near the origin pass b2Pos_zero and world points.

◆ b2World_SetContactRecycleDistance()

void b2World_SetContactRecycleDistance	(	b2WorldId	worldId,
		float	recycleDistance )

Set the contact point recycling distance.

Setting this to zero disables contact point recycling. Usually in meters.

◆ b2World_SetContactTuning()

void b2World_SetContactTuning	(	b2WorldId	worldId,
		float	hertz,
		float	dampingRatio,
		float	pushSpeed )

Adjust contact tuning parameters.

Parameters

worldId	The world id
hertz	The contact stiffness (cycles per second)
dampingRatio	The contact bounciness with 1 being critical damping (non-dimensional)
pushSpeed	The maximum contact constraint push out speed (meters per second)

Note: Advanced feature

◆ b2World_SetGravity()

void b2World_SetGravity	(	b2WorldId	worldId,
		b2Vec2	gravity )

Set the gravity vector for the entire world.

Box2D has no concept of an up direction and this is left as a decision for the application. Usually in m/s^2.

See also: b2WorldDef

◆ b2World_SetHitEventThreshold()

void b2World_SetHitEventThreshold	(	b2WorldId	worldId,
		float	value )

Adjust the hit event threshold.

This controls the collision speed needed to generate a b2ContactHitEvent. Usually in meters per second.

See also: b2WorldDef::hitEventThreshold

◆ b2World_SetRestitutionIterations()

void b2World_SetRestitutionIterations	(	b2WorldId	worldId,
		int	iterations )

Set the number of iterations used by the restitution solver.

See also: B2_MAX_RESTITUTION_ITERATIONS

◆ b2World_SetRestitutionThreshold()

void b2World_SetRestitutionThreshold	(	b2WorldId	worldId,
		float	value )

Adjust the restitution threshold.

It is recommended not to make this value very small because it will prevent bodies from sleeping. Usually in meters per second.

See also: b2WorldDef

◆ b2World_Step()

void b2World_Step	(	b2WorldId	worldId,
		float	timeStep,
		int	subStepCount )

Simulate a world for one time step.

This performs collision detection, integration, and constraint solution.

Parameters

worldId	The world to simulate
timeStep	The amount of time to simulate, this should be a fixed number. Usually 1/60.
subStepCount	The number of sub-steps, increasing the sub-step count can increase accuracy. Usually 4.

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ b2RayResult

◆ b2Capacity

◆ b2WorldDef

◆ b2Profile

◆ b2Counters

◆ b2ExplosionDef

Typedef Documentation

◆ b2CastResultCallbackFcn

◆ b2CustomFilterCallbackFcn

◆ b2EnqueueTaskCallbackFcn

◆ b2FrictionCallbackFcn

◆ b2OverlapResultCallbackFcn

◆ b2PreContinuousCallbackFcn

◆ b2PreSolveCallbackFcn

◆ b2RestitutionCallbackFcn

◆ b2TaskCallbackFcn

Function Documentation

◆ b2CreateWorld()

◆ b2World_CastMover()

◆ b2World_CastRay()

◆ b2World_CastRayClosest()

◆ b2World_CastShape()

◆ b2World_CollideMover()

◆ b2World_EnableContinuous()

◆ b2World_EnableRestitutionPropagation()

◆ b2World_EnableSleeping()

◆ b2World_EnableWarmStarting()

◆ b2World_Explode()

◆ b2World_GetBodyEvents()

◆ b2World_GetContactEvents()

◆ b2World_GetJointEvents()

◆ b2World_GetSensorEvents()

◆ b2World_GetStateHash()

◆ b2World_OverlapAABB()

◆ b2World_OverlapShape()

◆ b2World_SetContactRecycleDistance()

◆ b2World_SetContactTuning()

◆ b2World_SetGravity()

◆ b2World_SetHitEventThreshold()

◆ b2World_SetRestitutionIterations()

◆ b2World_SetRestitutionThreshold()

◆ b2World_Step()