Module world 

Simulation world: create bodies, shapes, and joints; step; query and cast.

Start here with World::new and World::step. Body/shape/joint creation lives in crate::body, crate::shape, and crate::joint. Use crate::types::default_world_def (and the other default_*_def helpers) for C-compatible defaults.

use box3d_rust::types::default_world_def;
use box3d_rust::world::World;

let mut world = World::new(&default_world_def());
world.step(1.0 / 60.0, 1);

Port of physics_world.h / physics_world.c (plus b3Profile from types.h).

Porting decisions (mirroring box2d-rust):

• C keeps a global world registry. The Rust World is an owned object; world_id/generation are kept so body/shape/joint ids remain bit-compatible with C.
• The arena allocator (b3Stack) is per-step scratch; the Rust solver allocates scratch as Vecs in the step, so there is no stack field.
• Manifold block allocators become Vec-owned manifolds on contacts for now; a pooled allocator can return later if profiling warrants it.
• Scheduler/task-system fields are deferred with the single-threaded port; worker_count is kept and clamped like C.
• Hull database is a content-keyed Rc store (verstable map in C).
• Pre-solve and custom-filter callbacks keep the C shape as Option<fn> with a u64 context.

SPDX-FileCopyrightText: 2025 Erin Catto SPDX-License-Identifier: MIT

Structs

Profile

Profiling data. Times are in milliseconds. (b3Profile)

TaskContext

Per thread task storage. (b3TaskContext)

World

The world struct manages all physics entities, dynamic simulation, and asynchronous queries. (b3World)

Functions

default_friction_callback

Default friction mixing: sqrt(frictionA * frictionB). (static b3DefaultFrictionCallback — from types.c / physics_world.c)

default_restitution_callback

Default restitution mixing: max(restitutionA, restitutionB).

world_cast_mover

Cast a capsule mover through the world. Returns the earliest hit fraction in [0, 1]. Overlapping shapes (fraction == 0) are ignored. An optional filter callback can reject individual shapes. (b3World_CastMover + static MoverCastCallback)

world_cast_ray

Cast a ray into the world. The callback receives (shape_id, point, normal, fraction, user_material_id, triangle_index, child_index) and controls continuation like C’s b3CastResultFcn: return -1 to ignore, 0 to terminate, a fraction in 0..=1 to clip, or >1 to continue without clipping. (b3World_CastRay + static RayCastCallback)

world_cast_ray_closest

Cast a ray into the world to collect the closest hit. Ignores initial overlap (fraction == 0 returns -1). (b3World_CastRayClosest)

world_cast_shape

Cast a shape through the world. Callback contract matches world_cast_ray. (b3World_CastShape + static ShapeCastCallback)

world_collide_mover

Collide a capsule mover with the world, gathering collision planes via callback. The callback receives (shape_id, planes) and returns false to stop. (b3World_CollideMover + static TreeCollideCallback)

world_draw

(b3World_Draw)

world_dump_awake

Dump awake bodies (and touching statics) as a C++ recreation snippet to box3d_dump.inl. (b3World_DumpAwake)

world_dump_shape_bounds

Dump leaf AABB bounds for one broad-phase tree to box3d_bounds.txt. (b3World_DumpShapeBounds)

world_enable_continuous

Enable/disable continuous collision. (b3World_EnableContinuous)

world_enable_sleeping

Enable/disable sleep. (b3World_EnableSleeping)

world_enable_speculative

Enable/disable speculative contacts. (b3World_EnableSpeculative)

world_enable_warm_starting

Enable/disable constraint warm starting. (b3World_EnableWarmStarting)

world_explode

Apply a radial explosion. (b3World_Explode + static ExplosionCallback)

world_get_awake_body_count

Get the number of awake bodies. (b3World_GetAwakeBodyCount)

world_get_body_events

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

world_get_bounds

Union of broad-phase tree root bounds. (b3World_GetBounds)

world_get_contact_events

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

world_get_contact_recycle_distance

Get the contact recycle distance. (b3World_GetContactRecycleDistance)

world_get_counters

Get world counters and sizes. (b3World_GetCounters)

world_get_gravity

Get the gravity vector. (b3World_GetGravity)

world_get_hit_event_threshold

Get the hit event speed threshold. (b3World_GetHitEventThreshold)

world_get_joint_events

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

world_get_max_capacity

Get the maximum capacity the world has reached. (b3World_GetMaxCapacity)

world_get_maximum_linear_speed

Get the maximum linear speed. (b3World_GetMaximumLinearSpeed)

world_get_profile

Get the current world performance profile. (b3World_GetProfile)

world_get_restitution_threshold

Get the restitution speed threshold. (b3World_GetRestitutionThreshold)

world_get_sensor_events

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

world_get_user_data

Get the user data pointer. (b3World_GetUserData)

world_get_worker_count

Get the stored worker count. (b3World_GetWorkerCount)

world_is_continuous_enabled

Is continuous collision enabled? (b3World_IsContinuousEnabled)

world_is_sleeping_enabled

Is sleeping enabled? (b3World_IsSleepingEnabled)

world_is_speculative_enabled

Is speculative contact enabled?

world_is_valid

World id validity. (b3World_IsValid)

world_is_warm_starting_enabled

Is constraint warm starting enabled? (b3World_IsWarmStartingEnabled)

world_overlap_aabb

Overlap test for all shapes that potentially overlap the provided AABB. The callback receives each overlapping shape id and returns false to terminate the query. (b3World_OverlapAABB + static TreeQueryCallback)

world_overlap_shape

Overlap test for all shapes that overlap the provided shape proxy. (b3World_OverlapShape + static TreeOverlapCallback)

world_rebuild_static_tree

Rebuild the static broad-phase tree. (b3World_RebuildStaticTree)

world_set_contact_recycle_distance

Set the contact recycle distance. (b3World_SetContactRecycleDistance)

world_set_contact_tuning

Adjust contact tuning parameters. (b3World_SetContactTuning)

world_set_custom_filter_callback

Register the custom filter callback. (b3World_SetCustomFilterCallback)

world_set_friction_callback

Register the friction callback. Passing None restores the default. (b3World_SetFrictionCallback)

world_set_gravity

Set the gravity vector. (b3World_SetGravity)

world_set_hit_event_threshold

Adjust the hit event threshold. (b3World_SetHitEventThreshold)

world_set_maximum_linear_speed

Set the maximum linear speed. (b3World_SetMaximumLinearSpeed)

world_set_pre_solve_callback

Register the pre-solve callback. (b3World_SetPreSolveCallback)

world_set_restitution_callback

Register the restitution callback. Passing None restores the default. (b3World_SetRestitutionCallback)

world_set_restitution_threshold

Adjust the restitution threshold. (b3World_SetRestitutionThreshold)

world_set_user_data

Set the user data pointer. (b3World_SetUserData)

world_set_worker_count

Set the stored worker count. Clamped to [1, MAX_WORKERS]. The serial port does not spawn threads but still resizes task contexts like C. (b3World_SetWorkerCount)

world_start_recording

Begin capturing mutations into recording. (b3World_StartRecording)

world_stop_recording

Finalize the active recording. (b3World_StopRecording)

Type Aliases

CustomFilterFcn

Prototype for a contact filter callback. (b3CustomFilterFcn)

PreSolveFcn

Prototype for a pre-solve callback. (b3PreSolveFcn)