## Box3D physics plugin (physics v2)
This adds `Box3DPlugin`, an `IPhysicsEngin…ePluginV2` implementation on top of [Box3D](https://github.com/erincatto/box3d), Erin Catto's new MIT licensed 3D rigid body engine (the 3D successor of Box2D v3: soft step solver, continuous collision, deterministic, SIMD).
It is a drop in alternative to the Havok plugin and follows the same shape: the engine ships as a separate WebAssembly package, [`babylon-box3d`](https://github.com/Pryme8/babylon-box3d) (a C shim over box3d with a flat handle based API, ESM + UMD + node builds, typings), and core only contains the plugin.
```ts
import Box3D from "babylon-box3d";
const box3d = await Box3D();
scene.enablePhysics(new Vector3(0, -9.81, 0), new Box3DPlugin(true, box3d));
```
Opened as a draft to discuss whether a Box3D plugin is welcome in core before polishing further. Ammo, Cannon and Oimo set the precedent for third party engine plugins, and Box3D's licensing and determinism make it an attractive open alternative to Havok.
### What is covered
- Bodies: static, animated (kinematic), dynamic, thin instances, prestep teleport and action modes, mass overrides, damping, gravity factor, velocities, forces and impulses.
- Shapes: sphere, capsule, cylinder, box, convex hull, mesh, height field, container. Hull data is copied into box3d's world database, mesh and height field data are shared and reference counted. Box3D shapes live on bodies, so a Babylon `PhysicsShape` is a description that gets instantiated on every body it is set on.
- Constraints: ball and socket (cone and twist limits), hinge, prismatic and slider, lock, distance, with limits, velocity and position motors on the constraint's primary axis. Enable / disable is emulated by re-creating the joint. `SIX_DOF` is not supported yet (falls back to a spherical joint with a warning).
- Events: contact begin / end (started / finished), contact hit events (continued, with point, normal and approach speed), sensor events (trigger entered / exited), per body observables.
- Ray casts with membership / collide masks, ignore body and trigger filtering.
- Box3D specific extras: `explode`, `createWheelJoint` (suspension, steering, spin motor), `createParallelJoint`, collision groups, rolling resistance, fast rotation.
- Only bodies reported by box3d's move events are synced, so large sleeping scenes cost nothing on the JS side.
### Not covered yet
- `Physics6DoFConstraint` / `SpringConstraint`.
- `PhysicsCharacterController` is hard wired to `HavokPlugin` internals (shape casts). Box3D has the query API for it, but the controller needs to be generalized first.
- Only one configurable axis per constraint type (what box3d exposes).
- Single threaded build. Box3D's task scheduler can run on wasm threads later, which needs cross origin isolation.
### Testing
- `packages/dev/core/test/unit/Physics/box3dPlugin.test.ts`: mocked module tests (bodies, shapes, mass overrides, stepping and event sync, contact event mapping, constraint frames and enable / disable, raycast ordering), same style as the Havok tests.
- Dev host showcase at `?exp=box3d&demo=pyramid|ragdolls|car|destruction|stack|joints|terrain|compound`: Box3D's Large Pyramid benchmark with thin instances and explosions, Erin's human ragdoll ported from `shared/human.c`, the Driving sample with wheel joints, a brick tower with a wrecking ball, plus smaller feature tests (every constraint type, height field + mesh + triggers, container shapes). The dev host serves the wasm from `node_modules/babylon-box3d` or from a checkout next to the repository until the package is on npm.
- `npm run build:source`, lint and the tree shaking manifest hooks pass.
### Follow ups if the team wants this
- Publish `babylon-box3d` (or adopt it as `@babylonjs/box3d`) and host the UMD build on the CDN so the playground runner can auto inject it like Havok.
- Documentation page under the physics deep dive.
🤖 Generated with [Claude Code](https://claude.com/claude-code)