A high-performance port and fork of Erwin Coumans' Bullet 3 Physics SDK. Built for games, visual robotics, simulation, and WebAssembly with deterministic sub-stepping.
Running the Bullet3-RS sequential impulse solver and collision response in real-time.
Every core subsystem in the upstream Bullet 3 repository has an idiomatic, memory-safe equivalent in pure Rust.
| Bullet 3 C++ Subsystem | bullet3-rs Module | Key Features & Algorithms |
|---|---|---|
| LinearMath | bullet3::linear_math | Vector3, Matrix3x3 (inverses, transposes), Quaternion (slerp, Euler), Transform, AABB slab test, MotionState. |
| btDbvtBroadphase | bullet3::collision::DbvtBroadphase | Dynamic Bounding Volume Tree with fat bounding boxes, incremental rebalancing, and raycast culling. |
| btCollisionShape | bullet3::collision::Shape | Sphere, Box, Capsule, Cylinder, Cone, StaticPlane, ConvexHull, and Compound shape hierarchies with inertia tensors. |
| Narrowphase Collision | bullet3::collision::narrowphase | Separating Axis Theorem (15 SAT axes for Box-Box), analytic tests, and Gilbert-Johnson-Keerthi (GJK) simplex solver. |
| btRigidBody | bullet3::dynamics::RigidBody | Mass, rotated world inertia tensors, velocity damping, forces, impulses, and sleep/deactivation thresholds. |
| btSequentialImpulseConstraintSolver | bullet3::dynamics::solver | Projected Gauss-Seidel solver, normal restitution, 2-axis Coulomb friction cones, and warm-starting impulse reuse. |
| btTypedConstraint | bullet3::dynamics::constraint | Point2Point (ball-socket), Hinge (revolute), Distance (rod), Slider (prismatic), and ConeTwist (ragdoll) joints. |
| btRaycastVehicle | bullet3::dynamics::RaycastVehicle | Independent wheel suspension raycasting, spring-damper dynamics, engine traction, braking, and steering. |
| btKinematicCharacterController | bullet3::dynamics::KinematicCharacterController | Player movement, ground snapping, step-climbing, jump impulse, and filtered ray testing. |
| btDiscreteDynamicsWorld | bullet3::dynamics::DiscreteDynamicsWorld | Fixed sub-stepping accumulator, gravity integration, broadphase/narrowphase dispatch, and RayResultCallback. |
Simulate a bouncing box dropped onto a static plane in 20 lines of Rust:
use bullet3::prelude::*;
fn main() {
// 1. Create discrete dynamics world with standard gravity (9.81 m/s² down)
let mut world = DiscreteDynamicsWorld::new()
.with_gravity(Vector3::new(0.0, -9.81, 0.0));
// 2. Add static ground plane at y = 0
let ground_shape = Shape::StaticPlane(StaticPlaneShape::new(Vector3::Y, 0.0));
let ground_info = RigidBodyConstructionInfo::new(0.0, ground_shape, Transform::IDENTITY);
world.add_rigid_body(RigidBody::new(ground_info));
// 3. Add dynamic falling box at height y = 10.0
let box_shape = Shape::Box(BoxShape::new(Vector3::splat(0.5)));
let box_tf = Transform::from_translation(Vector3::new(0.0, 10.0, 0.0));
let box_info = RigidBodyConstructionInfo::new(1.0, box_shape, box_tf)
.with_restitution(0.4)
.with_friction(0.6);
let box_id = world.add_rigid_body(RigidBody::new(box_info));
// 4. Step simulation for 60 ticks (1.0s at 60 Hz)
let dt = 1.0 / 60.0;
for _ in 0..60 {
world.step_simulation(dt, 10, dt);
}
let body = world.get_rigid_body(box_id).unwrap();
println!("Settled Box Center Y: {:.3}m", body.transform.origin.y);
}
The `bullet3` crate compiles directly into a standalone benchmarking and verification CLI.
Verifies Gauss-Seidel constraint solver convergence and non-penetration stability for vertical rigid body stacks.
cargo run --release -- stack --boxes 5 --steps 180
Verifies Point-to-Point spherical constraint rod distance conservation under gravity acceleration.
cargo run --release -- pendulum --steps 120
Verifies 100% restitution momentum conservation and velocity transfer in zero-gravity space.
cargo run --release -- billiards --steps 60
Measures raw simulation throughput across multiple dynamic colliding bodies.
cargo run --release -- benchmark --steps 1000 --bodies 20
Benchmarked natively on Apple Silicon with 64-bit precision floating-point vector math.
Per complete 10-body simulation step (forces, broadphase, narrowphase, 10 solver iterations, integration).
Physics steps/second in single-threaded release profile execution mode.
Unit, accuracy, and integration tests verifying linear math, energy conservation, GJK/EPA, SAT, constraints, and kinematics.
Empirically validated via tests/test_accuracy.rs against Newtonian & Hamiltonian baselines.