box3d-rust 0.0.1

Pure Rust port of the Box3D 3D physics engine
Documentation

box3d-rust

A pure Rust port of Box3D, Erin Catto's 3D physics engine for games — exact behavioral match, including cross-platform deterministic math.

crates.io docs.rs License Live Demo

Demo Site

Follow the port live in your browser

box3d-rust demo

The demo site will mirror the upstream samples app via WebAssembly, exactly like our finished box2d-rust port did for Box2D. Until the collision layer lands it is a status page running the current wasm build.

Part of the rust-apps suite — a collection of Rust graphics and geometry libraries by Lars Brubaker.

Status: Port starting

Box3D was released by Erin Catto in June 2026. The pinned reference source lives in the box3d-cpp-reference/ submodule (v0.1.0+, 540ea38), and this port follows the same playbook that took box2d-rust to completion: whole modules in dependency order, each landing with its portion of the upstream C test suite.

Area Ported Tests
Foundation: math_functions (Vec3/Quat/Mat33), core/constants, id, bitset, id_pool, table, container ⬜ ⬜ (test_math/id/bitset/table/container.c)
Collision: aabb, distance (GJK/TOI), hull, dynamic_tree ⬜ ⬜ (test_collision/distance/hull.c)
Shapes: sphere, capsule, box, convex hull, compound, mesh, height field ⬜ ⬜ (test_shape/compound/height_field.c)
Manifolds: convex, mesh contact, triangle ⬜ ⬜
Broad phase: proxy ops, move buffer, pair update → contact creation ⬜ ⬜
Dynamics: body/shape/contact lifecycles, constraint graph, solver sets, islands ⬜ ⬜ (test_body.c)
Joints: distance, motor, prismatic, revolute, spherical, weld, wheel ⬜ ⬜ (test_joint.c)
Solver: contact solver + step pipeline, sensors, sleeping, continuous ⬜ ⬜ (test_world.c)
World API: queries, casts, character movers ⬜ ⬜ (test_body_query/mover.c)
Determinism: hand-rolled trig, bit-exact vs the C build ⬜ ⬜ (test_determinism.c)
Snapshots and recording/replay ⬜ ⬜ (test_recording.c)
Large world mode (double-precision feature = BOX3D_DOUBLE_PRECISION) ⬜ ⬜ (test_large_world.c)

Not ported (by design): the task scheduler/worker threads (the port is serial), SIMD codepaths (the scalar BOX3D_DISABLE_SIMD path is the behavioral reference), and the C arena/block allocators (Rust Vecs).

Porting principles

  • Exact behavioral match — same algorithms, same f32 arithmetic, same edge cases as the C source. Floating-point operations are never reordered or "improved".
  • Determinism preserved — Box3D's hand-rolled b3Atan2 and b3ComputeCosSin (built for cross-platform determinism) are ported bit-for-bit, never replaced with std functions.
  • Tests ported too — every module lands together with its portion of the C test suite.
  • No stubs — no todo!(), no placeholders; modules are ported whole, in dependency order.
  • Large world mode — the double-precision cargo feature mirrors BOX3D_DOUBLE_PRECISION.

The approach follows HOW_WE_PORTED_CLIPPER2.md and the completed box2d-rust port.

Development

# Clone with the C reference submodule
git clone --recurse-submodules https://github.com/larsbrubaker/box3d-rust.git

# Run tests (both precision modes)
cargo test
cargo test --features double-precision

# Full pre-commit gauntlet: file lengths, tests, fmt, clippy, build
./scripts/pre-commit-check.ps1   # or .sh

Demo site

The demo site (demo/) runs the port in the browser via WebAssembly.

The quickest way to see it — builds the wasm and serves the demo at http://localhost:3000, opening your browser:

run_demo.cmd      # Windows (double-click or run from a terminal)
./run_demo.sh     # Linux / macOS

Or drive the steps yourself:

cd demo
bun install
bun run build:wasm   # wasm-pack build (once, and after Rust changes)
bun run dev          # dev server at http://localhost:3000, rebuilds wasm on Rust edits

Deployed automatically to GitHub Pages on push to main.

Acknowledgments