Documentation

Create a world for rigid body simulation. A world contains bodies, shapes, and constraints. You make create up to 128 worlds. Each world is completely independent and may be simulated in parallel.

Returns: the world id.

Binds b2CreateWorld.

Destroy a world

Binds b2DestroyWorld.

World id validation. Provides validation for up to 64K allocations.

Binds b2World_IsValid.

Simulate a world for one time step. This performs collision detection, integration, and constraint solution.

Binds b2World_Step.

Call this to draw shapes and other debug draw data

Binds b2World_Draw.

Call this to get the world bounds based on the union of all shape bounds.

Binds b2World_GetBounds.

Like getBounds, but the result is written into a caller-supplied buffer.

Get the body events for the current time step. The event data is transient. Do not store a reference to this data.

Binds b2World_GetBodyEvents.

Like getBodyEvents, but the result is written into a caller-supplied buffer.

Get sensor events for the current time step. The event data is transient. Do not store a reference to this data.

Binds b2World_GetSensorEvents.

Like getSensorEvents, but the result is written into a caller-supplied buffer.

Get contact events for this current time step. The event data is transient. Do not store a reference to this data.

Binds b2World_GetContactEvents.

Like getContactEvents, but the result is written into a caller-supplied buffer.

Get the joint events for the current time step. The event data is transient. Do not store a reference to this data.

Binds b2World_GetJointEvents.

Like getJointEvents, but the result is written into a caller-supplied buffer.

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.

Binds b2World_OverlapAABB.

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.

Binds b2World_OverlapShape.

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

Returns: traversal performance counters

Binds b2World_CastRay.

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.

Binds b2World_CastRayClosest.

Cast a shape through the world. Similar to a cast ray 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.

Binds b2World_CastShape.

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.

Binds b2World_CastMover.

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.

Binds b2World_CollideMover.

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.

Binds b2World_EnableSleeping.

Is body sleeping enabled?

Binds b2World_IsSleepingEnabled.

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.

Binds b2World_EnableContinuous.

Is continuous collision enabled?

Binds b2World_IsContinuousEnabled.

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.

Binds b2World_SetRestitutionThreshold.

Get the the restitution speed threshold. Usually in meters per second.

Binds b2World_GetRestitutionThreshold.

Adjust the hit event threshold. This controls the collision speed needed to generate a b2ContactHitEvent. Usually in meters per second. See also b2WorldDef::hitEventThreshold.

Binds b2World_SetHitEventThreshold.

Get the the hit event speed threshold. Usually in meters per second.

Binds b2World_GetHitEventThreshold.

Register the custom filter callback. This is optional.

Binds b2World_SetCustomFilterCallback.

Register the pre-solve callback. This is optional.

Binds b2World_SetPreSolveCallback.

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.

Binds b2World_SetGravity.

Get the gravity vector

Binds b2World_GetGravity.

Like getGravity, but the result is written into a caller-supplied buffer.

Apply a radial explosion

Binds b2World_Explode.

Adjust contact tuning parameters Note: Advanced feature

Binds b2World_SetContactTuning.

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

Binds b2World_SetContactRecycleDistance.

Get the contact point recycling distance. Usually in meters.

Binds b2World_GetContactRecycleDistance.

Set the maximum linear speed. Usually in m/s.

Binds b2World_SetMaximumLinearSpeed.

Get the maximum linear speed. Usually in m/s.

Binds b2World_GetMaximumLinearSpeed.

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

Binds b2World_EnableWarmStarting.

Is constraint warm starting enabled?

Binds b2World_IsWarmStartingEnabled.

Get the number of awake bodies.

Binds b2World_GetAwakeBodyCount.

Get the current world performance profile

Binds b2World_GetProfile.

Get world counters and sizes

Binds b2World_GetCounters.

Get max capacity. This can be used with b2WorldDef to avoid run-time allocations and copies

Binds b2World_GetMaxCapacity.

Like getMaxCapacity, but the result is written into a caller-supplied buffer.

Set the user data pointer.

Binds b2World_SetUserData.

Get the user data pointer.

Binds b2World_GetUserData.

Set the friction callback. Passing NULL resets to default.

Binds b2World_SetFrictionCallback.

Set the restitution callback. Passing NULL resets to default.

Binds b2World_SetRestitutionCallback.

Set the worker count. Must be between in the range \[1, B2_MAX_WORKERS\]

Binds b2World_SetWorkerCount.

Get the worker count.

Binds b2World_GetWorkerCount.

Dump memory stats to box2d_memory.txt

Binds b2World_DumpMemoryStats.

This is for internal testing

Binds b2World_RebuildStaticTree.

This is for internal testing

Binds b2World_EnableSpeculative.

Begin recording the world into @p recording. Serializes a snapshot of the current world as the seed, then logs every mutating call. Call at a step boundary, before or after creating bodies. Start before the first step to capture the whole session. No effect if already recording or if the world is locked.

Binds b2World_StartRecording.

Stop recording. The recording buffer keeps its bytes. Save and destroy it yourself.

Binds b2World_StopRecording.

Write a snapshot of the world's simulation state into a caller-owned buffer. Call once with image == NULL to get the required size, then again with a buffer of at least that size. Must be called at a step boundary.

Returns: The number of bytes the snapshot needs. If it exceeds capacity nothing is written. Returns 0 if the world is mid-step.

Binds b2World_Snapshot.

Restore a world's simulation state from a snapshot image, in place. The world keeps its slot and generation, so this b2WorldId and any ids held from this same world stay valid for objects that existed at the snapshot instant. Host wiring is preserved. Restore into the same world the snapshot came from to keep held ids valid. Must be called at a step boundary.

Returns: true on success. On a rejected image (bad magic, version, or layout) the world is left unchanged. A corrupt payload detected after the rebuild begins returns false and leaves the world unusable, so the caller must destroy it.

Binds b2World_Restore.

Create a new world from a snapshot image. Use this to load a saved world when there is no existing world to restore into. The new world gets a fresh slot and id, so ids held from the origin world will not match it. Host wiring is reset to defaults.

Returns: The new world id, or b2_nullWorldId on failure.

Binds b2CreateWorldFromSnapshot.