Crate box3d_rust 

Pure Rust port of Box3D, Erin Catto’s 3D physics engine for games.

The port targets exact behavioral match with the C source pinned in the box3d-cpp-reference/ submodule: same algorithms, same f32 arithmetic, same edge cases, including Box3D’s hand-rolled cross-platform-deterministic trigonometry.

API style

For 0.1 the public API is a direct C-mirror (same shapes, defs, and call patterns as Box3D / box2d-rust), not a Rust-ergonomic wrapper. A thin ergonomic layer may be considered after 0.1 if downstream users ask for one.

Quick start

Add the crate, create a world::World, attach bodies and shapes, then step:

use box3d_rust::body::create_body;
use box3d_rust::geometry::Sphere;
use box3d_rust::hull::make_box_hull;
use box3d_rust::shape::{create_hull_shape, create_sphere_shape};
use box3d_rust::types::{default_body_def, default_shape_def, default_world_def, BodyType};
use box3d_rust::world::World;
use box3d_rust::{Pos, VEC3_ZERO};

let mut world = World::new(&default_world_def());

let mut ground_def = default_body_def();
ground_def.type_ = BodyType::Static;
let ground = create_body(&mut world, &ground_def);

let mut ball_def = default_body_def();
ball_def.type_ = BodyType::Dynamic;
ball_def.position = Pos {
    x: 0.0 as _,
    y: 0.5 as _,
    z: 0.0 as _,
};
let ball = create_body(&mut world, &ball_def);

let shape_def = default_shape_def();
let ground_hull = make_box_hull(5.0, 0.5, 5.0);
create_hull_shape(&mut world, ground, &shape_def, &ground_hull.base);

let mut ball_shape = default_shape_def();
ball_shape.density = 1.0;
create_sphere_shape(
    &mut world,
    ball,
    &ball_shape,
    &Sphere {
        center: VEC3_ZERO,
        radius: 0.5,
    },
);

// 60 Hz, 1 sub-step
world.step(1.0 / 60.0, 1);

Features

Enable double-precision to mirror upstream BOX3D_DOUBLE_PRECISION (large-world mode). World positions use a wider scalar while collision math stays f32; both configurations are tested against the C reference.

Determinism

Box3D is designed for cross-platform determinism. This port keeps the hand-rolled approximations (for example atan2 / cos/sin) bit-for-bit with the C scalar path — do not replace them with std trig. The determinism module and the falling-ragdoll scene gate bit-exact match with the pinned reference build.

Key modules

Module	Role
world	Own a simulation, step it, run queries and casts
body	Create and configure rigid bodies
shape	Attach collision geometry to bodies
joint	Constraints between bodies
types	Public defs/defaults (WorldDef, BodyDef, ShapeDef, …)
math_functions	Vec3, Quat, Transform, and deterministic math

See the repository README for port status and the live wasm demo.

Re-exports

pub use debug_draw::make_debug_color;

pub use debug_draw::CreateDebugShapeCallback;

pub use debug_draw::DebugDraw;

pub use debug_draw::DebugMaterial;

pub use debug_draw::DebugShape;

pub use debug_draw::DestroyDebugShapeCallback;

pub use debug_draw::HexColor;

pub use id::BodyId;

pub use id::ContactId;

pub use id::JointId;

pub use id::ShapeId;

pub use id::WorldId;

pub use math_functions::Aabb;

pub use math_functions::CosSin;

pub use math_functions::Matrix3;

pub use math_functions::Plane;

pub use math_functions::Pos;

pub use math_functions::Quat;

pub use math_functions::SegmentDistanceResult;

pub use math_functions::Transform;

pub use math_functions::Triangle;

pub use math_functions::Vec2;

pub use math_functions::Vec3;

pub use math_functions::WorldTransform;

pub use math_functions::MAT3_IDENTITY;

pub use math_functions::MAT3_ZERO;

pub use math_functions::PI;

pub use math_functions::POS_ZERO;

pub use math_functions::QUAT_IDENTITY;

pub use math_functions::TRANSFORM_IDENTITY;

pub use math_functions::VEC3_AXIS_X;

pub use math_functions::VEC3_AXIS_Y;

pub use math_functions::VEC3_AXIS_Z;

pub use math_functions::VEC3_ONE;

pub use math_functions::VEC3_ZERO;

pub use math_functions::WORLD_TRANSFORM_IDENTITY;

pub use types::default_body_def;

pub use types::default_distance_joint_def;

pub use types::default_explosion_def;

pub use types::default_filter;

pub use types::default_filter_joint_def;

pub use types::default_motor_joint_def;

pub use types::default_parallel_joint_def;

pub use types::default_prismatic_joint_def;

pub use types::default_query_filter;

pub use types::default_revolute_joint_def;

pub use types::default_shape_def;

pub use types::default_spherical_joint_def;

pub use types::default_weld_joint_def;

pub use types::default_wheel_joint_def;

pub use types::default_world_def;

pub use types::BodyDef;

pub use types::BodyType;

pub use types::Capacity;

pub use types::Counters;

pub use types::DistanceJointDef;

pub use types::ExplosionDef;

pub use types::Filter;

pub use types::FilterJointDef;

pub use types::JointDef;

pub use types::MotionLocks;

pub use types::MotorJointDef;

pub use types::ParallelJointDef;

pub use types::PrismaticJointDef;

pub use types::QueryFilter;

pub use types::RayResult;

pub use types::RevoluteJointDef;

pub use types::ShapeDef;

pub use types::SphericalJointDef;

pub use types::WeldJointDef;

pub use types::WheelJointDef;

pub use types::WorldCastOutput;

pub use types::WorldDef;

pub use types::BODY_TYPE_COUNT;

Modules

aabb

bitset

body

Rigid bodies: create, destroy, and configure simulation state.

broad_phase

compound

Baked compound collision shape.

constants

constraint_graph

contact

contact_solver

Contact constraint kernels from contact_solver.c.

core

debug_draw

Debug draw interface (b3DebugDraw), color palette (b3HexColor), and debug-material packing from types.h / types.c.

determinism

Falling-ragdoll determinism scene helpers from shared/determinism.c.

distance

dynamic_tree

events

geometry

Shape geometry queries: sphere, capsule, and hull mass/AABB/overlap/cast.

height_field

Height field collision shape.

hull

Convex hull construction and query module.

human

Human ragdoll builder from shared/human.c / shared/human.h.

id

Port of box3d-cpp-reference/include/box3d/id.h

id_pool

island

joint

Joints (constraints) between bodies.

manifold

Contact manifold generation for convex primitive pairs and mesh narrow phase.

math_functions

Vectors, quaternions, transforms, and deterministic scalar math.

mesh

Triangle mesh collision shape.

mover

Character mover plane solver from box3d-cpp-reference/src/mover.c.

name_cache

recording

Recording, replay, and world snapshots.

sensor

Port of box3d-cpp-reference/src/sensor.c + sensor.h.

shape

Collision shapes attached to bodies (sphere, capsule, hull, mesh, …).

solver

Softness / make_soft and the step context from solver.h. Integration and the serial solve driver live in submodules.

solver_set

table

types

Public definition types and C-compatible defaults.

world

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

Constants

VERSION

Crate version, exposed so demos and downstream tools can report the exact port build.