boxdd - Rust bindings for Box2D v3 (C API)

Crates

• boxdd-sys: low-level FFI for the official Box2D v3 C API (vendored)
• boxdd: safe layer (world, bodies, shapes, joints, queries, events, debug draw)

Highlights

• Safe, ergonomic Rust wrapper over the official Box2D v3 C API.
• Mint interop by default: any Into<Vec2> accepts mint::Vector2<f32>, mint::Point2<f32>, arrays/tuples.

Quickstart

use boxdd::{World, WorldDef, BodyBuilder, ShapeDef, shapes, Vec2};

let def = WorldDef::builder().gravity(Vec2::new(0.0, -9.8)).build();
let mut world = World::new(def).unwrap();
let mut body = world.create_body(BodyBuilder::new().position([0.0, 2.0]).build());
let poly = shapes::box_polygon(0.5, 0.5);
let _shape = body.create_polygon_shape(&ShapeDef::default(), &poly);
world.step(1.0/60.0, 4);

Features (optional)

• serde: serialization for Vec2, Rot (radians), Transform ({ pos, angle }) and config types.
• serialize: snapshot helpers (save/apply world config; take/rebuild minimal full-scene snapshot).
• cgmath, nalgebra, glam: conversions with their 2D types (e.g. Vector2/Point2, UnitComplex/Isometry2, glam::Vec2).

Snapshots

• Enable serialize and see example examples/scene_serialize.rs for a minimal scene round-trip.
• Note: chain shapes are captured when created via ID-style API (World::create_chain_for_id).

Build Modes

• From source: builds vendored Box2D C sources via cc and uses pregenerated bindings by default.
  • Example: cargo build -p boxdd.
• System library (optional): link an existing box2d installed on the system.
  • Via env: set BOX2D_LIB_DIR=/path/to/lib and optionally BOXDD_SYS_LINK_KIND=static|dylib.
  • Via feature: enable pkg-config and provide box2d through your system's package manager.
  • Note: crate features that affect C build (e.g. simd-avx2, disable-simd, validate) are ignored in system mode. Set BOXDD_SYS_STRICT_FEATURES=1 to fail the build if such features are enabled.

Getting Started

git submodule update --init --recursive

cargo build


# run some examples

cargo r --example world_basics

cargo r --example joints

cargo r --example queries

cargo r --example sensors

cargo r --example testbed_imgui_glow --features imgui-glow-testbed

Examples

• The examples/ folder covers worlds/bodies/shapes, joints, queries/casts, events/sensors, CCD, and debug draw.

Events

• Three access styles:
  • By value: world.contact_events()/sensor_events()/body_events()/joint_events() return owned data for storage or cross-frame use.
  • Zero‑copy views: with_*_events_view(...) iterate without exposing FFI types and without allocations (recommended for per‑frame processing).
  • Raw slices: with_*_events(...) expose FFI slices for power users; valid only within the callback.
• Example (zero‑copy views):

use boxdd::prelude::*;
let mut world = World::new(WorldDef::default()).unwrap();
world.with_contact_events_view(|begin, end, hit| {
    let _ = (begin.count(), end.count(), hit.count());
});
world.with_sensor_events_view(|beg, end| {
    let _ = (beg.count(), end.count());
});
world.with_body_events_view(|moves| {
    for m in moves { let _ = (m.body_id(), m.fell_asleep()); }
});
world.with_joint_events_view(|j| { let _ = j.count(); });

Notes

• Vendored C sources + pregenerated bindings by default (no LLVM needed on CI). To force bindgen: set BOXDD_SYS_FORCE_BINDGEN=1 and ensure libclang is available. On Windows/MSVC, set LIBCLANG_PATH if needed.
• On docs.rs, the native C build is skipped.

Documentation

• Local: cargo doc --open
• Online: https://docs.rs/boxdd

Acknowledgments

• Thanks to the Rust Box2D bindings project for prior art and inspiration: https://github.com/Bastacyclop/rust_box2d
• Huge thanks to the upstream Box2D project by Erin Catto: https://github.com/erincatto/box2d

Related Projects

If you're working with graphics applications in Rust, you might also be interested in:

• asset-importer - A comprehensive Rust binding for the latest Assimp 3D asset import library, providing robust 3D model loading capabilities for graphics applications
• dear-imgui - Comprehensive Dear ImGui bindings for Rust using C++ bindgen, providing immediate mode GUI capabilities for graphics applications

License

• boxdd: MIT OR Apache-2.0
• boxdd-sys: MIT OR Apache-2.0