box3d-rust 0.0.1

Pure Rust port of the Box3D 3D physics engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# box3d-rust

A pure Rust port of [Box3D](https://github.com/erincatto/box3d), Erin Catto's 3D physics
engine for games — exact behavioral match, including cross-platform deterministic math.

[![crates.io](https://img.shields.io/crates/v/box3d-rust.svg)](https://crates.io/crates/box3d-rust)
[![docs.rs](https://docs.rs/box3d-rust/badge.svg)](https://docs.rs/box3d-rust)
[![License](https://img.shields.io/badge/License-MIT-lightblue.svg)](LICENSE)
[![Live Demo](https://img.shields.io/badge/Live_Demo-Status_Page-blue)](https://larsbrubaker.github.io/box3d-rust/)

## Demo Site

**[Follow the port live in your browser](https://larsbrubaker.github.io/box3d-rust/)**

[![box3d-rust demo](readme_hero.jpg)](https://larsbrubaker.github.io/box3d-rust/)

The demo site will mirror the upstream `samples` app via WebAssembly, exactly like our
finished [box2d-rust](https://github.com/larsbrubaker/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](https://github.com/larsbrubaker/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](https://github.com/larsbrubaker/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 `Vec`s).

## 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](https://github.com/larsbrubaker/clipper2-rust/blob/main/HOW_WE_PORTED_CLIPPER2.md)
and the completed [box2d-rust](https://github.com/larsbrubaker/box2d-rust) port.

## Development

```bash
# 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:

```bash
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

- [Erin Catto](https://github.com/erincatto) — Box3D author
- [MatterHackers](https://www.matterhackers.com/) — sponsoring the port
- Ported with [Claude Code](https://claude.com/claude-code)