box2d3-wasm
v6.0.0
Published
Let's try and use box2d v3 on the web.
Readme
box2d3-wasm
Box2D v3 ported to the web via wasm!
Online Demos
- box2d v3 samples
- pyramid drop demo You can change the size of the pyramid by editing the "pyramidHeight" URL parameter. Set it to 101 for a pyramid with 5,050 boxes!
Usage
Web Usage
See the pyramid drop demo code for an example of how to use box2d3-wasm in a Web browser. You'll need to serve the assets correctly in order to access performance features such as threading. See the Serving Requirements section below.
NodeJS Usage
See the integration test code for an example of how to use box2d3-wasm via NodeJS. There'll be no graphics; you probably only want the NodeJS approach if you're building server-side physics or you intend to build your own native GUI.
Available on npm
Install as an npm package:
npm i --save box2d3-wasmChoosing a build
The default import uses deluxe (SIMD and threads) when SIMD is available and the page is cross-origin isolated (or under Node.js). Otherwise it uses compat. To choose explicitly:
import Box2DFactory from 'box2d3-wasm/compat'; // no SIMD, threads or cross-origin isolation required
// or: import Box2DFactory from 'box2d3-wasm/deluxe';Importing compat directly keeps the threaded build and its worker out of your bundle. Both imports expose the same single precision API, including the b2Pos aliases.
Memory ownership
Constructors and functions returning class values, such as b2Body_GetPosition and b2Joint_GetLocalFrameA/B, create owned wasm objects. Call .delete() when finished with them. IDs are plain JavaScript objects and need no deletion.
Plain JavaScript results can contain owned class values: b2World_CollideMover's result.plane and result.point each need .delete().
Reference properties such as jointDef.base, worldDef.gravity, bodyDef.position and transform.p/q are borrowed views into their parent. Do not call .delete() on these views. Delete the parent once; its views then become invalid.
const def = box2d.b2DefaultRevoluteJointDef();
def.base.bodyIdA = bodyA; // base is a borrowed view
def.base.bodyIdB = bodyB;
const jointId = box2d.b2CreateRevoluteJoint(worldId, def);
def.delete();IDs and user data
Treat IDs as opaque handles. A world's index1 is one-based, while an object's world0 is zero-based; use b2Shape_GetWorld, b2Body_GetWorld or b2Joint_GetWorld to retrieve the owning world.
Bodies, shapes and joints expose SetUserData/GetUserData through the C-style functions, for example b2Body_SetUserData(bodyId, id). Store an integer from 0 to 2^32 - 1 (0 means no user data), and keep the corresponding JavaScript object in your own lookup table.
Large worlds (double precision)
Box2D normally stores positions in single precision, which is fine within a few kilometres of the origin. For larger worlds, import the double precision build instead. It is Box2D's large world mode: positions (b2Pos) and body transforms (b2WorldTransform) are doubles, so a body 10,000 km from the origin simulates like one at the origin.
import Box2DFactory from 'box2d3-wasm/double';
const box2d = await Box2DFactory();
const { b2Pos, b2DefaultBodyDef, b2OffsetPos, b2Vec2 } = box2d;
const bodyDef = b2DefaultBodyDef();
bodyDef.position = new b2Pos(10.0e6, 0.0);
// local offsets stay b2Vec2
const pivot = b2OffsetPos(bodyDef.position, new b2Vec2(0.0, 2.0));In the double precision build, world positions must be b2Pos objects (and world transforms b2WorldTransform); local vectors stay b2Vec2. The single precision build exposes b2Pos, b2WorldTransform and b2WorldCastOutput as aliases of b2Vec2, b2Transform and b2CastOutput, so code written with b2Pos runs on both builds. See integration-test/double.mjs.
The debug draw command buffer emits positions relative to an origin you set with SetOrigin(x, y) (the demo renderer uses the camera center), so drawing stays precise far from the world origin.
Build from Source Pre-Requisites
Install Node.js and npm.
The CI toolchain uses Emscripten 6.0.13 and TypeScript 7.x. Install TypeScript and yarn:
npm i -g typescript@7
npm i -g yarnNext, install Emscripten. On macOS, you can use Homebrew to install it.
brew install emscriptenClone the repository with submodules:
git clone --recurse-submodules https://github.com/Birch-san/box2d3-wasm.gitBuild
Run the following commands:
FLAVOUR=deluxe TARGET_TYPE=Debug ./shell/0_build_makefile.sh
emmake make -j8 -C cmake-build-deluxe
FLAVOUR=deluxe TARGET_TYPE=Debug ./shell/1_build_wasm.shC++ wrapper (box2cpp)
The C++ classes (World, Body, Shape, joints…) come from the Birch-san/box2cpp fork. The box2cpp submodule pins the Box2D v3.2 wrapper, and the wasm build includes its committed header directly from box2cpp/include. Generator changes and generated C++ belong in that repository.
After updating Box2D, regenerate and commit the wrapper in box2cpp first (needs gawk and perl, e.g. brew install gawk). From this package's directory:
make -C ../box2cpp generate BOX2D_DIR=../box2dThen update this repository's submodule pin to that published commit.
Box2D fork
The box2d submodule pins codex/box2d-v3.2-wasm-fixes in the Birch-san fork. Both build scripts use this checkout directly. The branch carries two fixes on top of upstream erincatto/box2d:main:
- Mover and pogo joint torque/separation queries no longer assert (for example when drawing joint extras).
b2World_CollideMoverreports collision points in the query frame and on the rounded shape surface.
Box2D draft PR #1 shows only these changes. It is for viewing the patches; the wasm build consumes the branch directly, without merging the draft.
Double precision builds
Set PRECISION=double for both scripts. The output goes to cmake-build-<flavour>-double and build/dist/es/<flavour>-double:
PRECISION=double FLAVOUR=deluxe TARGET_TYPE=Debug ./shell/0_build_makefile.sh
emmake make -j8 -C cmake-build-deluxe-double
PRECISION=double FLAVOUR=deluxe TARGET_TYPE=Debug ./shell/1_build_wasm.shRun Demos
Inside the demo directory, run yarn to install local-web-server locally.
Then, to start the web server run yarn serve.
The samples can also be smoke tested headlessly (each sample is created, stepped, poked with the mouse and destroyed, with Box2D debug assertions enabled when you built with TARGET_TYPE=Debug):
cd ../demo/samples
node smoke_test.mjs # every sample
node smoke_test.mjs benchmark # samples whose name or path matchesServing Requirements
Note that the server runs with the following CORS headers:
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-originThese policies are required for the Box2D3 WebAssembly module to run with threading, because it uses the SharedArrayBuffer feature which requires an isolated context for security reasons.
Regardless of whether you use threading: you may need web server customizations (or good defaults) to serve WASM assets with the correct MIME type (application/wasm).
Run Tests
node integration-test/index.mjs
node integration-test/double.mjsRelease
From box2d3-wasm package's directory,
git clean -dfx build cmake-build-deluxe cmake-build-compat cmake-build-deluxe-double cmake-build-compat-double
for PRECISION in single double; do
SUFFIX=$([ "$PRECISION" = double ] && echo "-double")
for FLAVOUR in deluxe compat; do
PRECISION=$PRECISION FLAVOUR=$FLAVOUR TARGET_TYPE=Release ./shell/0_build_makefile.sh
emmake make -j8 -C cmake-build-$FLAVOUR$SUFFIX
PRECISION=$PRECISION FLAVOUR=$FLAVOUR TARGET_TYPE=Release ./shell/1_build_wasm.sh
done
done
# e.g. major | minor | patch, see https://docs.npmjs.com/cli/v10/commands/npm-version
npm version minor
npm publishUpgrading to Box2D v3.2
box2d3-wasm follows the Box2D C API names, so most changes come straight from the Box2D v3.2 release notes. The ones you are most likely to hit from JavaScript:
- Queries take an origin.
b2World_OverlapAABB,b2World_OverlapShape,b2World_CastShape,b2World_CastMoverandb2World_CollideMovertake ab2Posorigin as the second argument; the AABB, proxy or capsule is relative to it. Passb2Pos_zerofor the old behaviour. - Pre-solve was redesigned.
b2World_SetPreSolveCallback(worldId, preSolve, preContinuous)takes two callbacks (either may benull).preSolve(shapeIdA, shapeIdB, manifold)gets the liveb2Manifold, which you may edit (setmanifold.pointCount = 0to disable the contact).preContinuous(shapeIdA, shapeIdB, point, normal)returnsfalseto skip a time of impact event. - Joints.
b2DestroyJoint(jointId)no longer takes a wake flag. Current values say so (b2RevoluteJoint_GetCurrentAngle,b2PrismaticJoint_GetCurrentTranslation,…GetCurrentMotorTorque/Force), motor speeds are targets (…SetTargetMotorSpeed), and the distance joint usesSetRestLength/SetLimits/GetLowerLimit/GetUpperLimit. The wheel joint axis is the x-axis oflocalFrameA, motor joint defaults are zero, and the new mover and pogo joints are available. - Weld joint reference orientations are set through the rotations in
localFrameA/B, usingb2Joint_SetLocalFrameA/B; there are no separate weld reference-angle functions in this Box2D API. - Bodies and shapes.
b2Body_UpdateMassFromShapes,b2Body_GetLocalCenter,b2Body_GetWorldCenter,b2Body_EnableSleeping,b2Body_IsSleepingEnabled,b2Body_ComputeBounds,b2Shape_GetBoundsandb2Shape_CastRay(shapeId, origin, translation)replace the old names.b2Body_SetTargetTransformtakes a wake flag. - Chains.
b2ChainDef.countis nowpointCount, open chains needghost1andghost2, and every segment of an open chain collides. - Contacts. Contact events and
b2ContactDatacarry acontactId; useb2Contact_IsValidandb2Contact_GetData.b2ManifoldPoint.pointwas removed. - World.
b2World_SetMaxLinearSpeed/GetMaxLinearSpeedreplace theMaximumspelling,b2World_EnableSpeculativeis gone, andb2WorldDef.contactSpeed, restitution iterations/propagation and contact recycling (b2World_SetContactRecycleDistance) are new. Contact recycling is on by default. - Profile and debug draw.
b2ProfileusessolverSetup,constraintsandrestitution;b2DebugDraw.drawContactPointsis nowdrawContacts. - Collision helpers are verb first:
b2CastRayCircle,b2CastShapePolygon,b2ComputeShapeDistance, andb2Compute*Boundsreplaceb2Compute*AABB. - New: world snapshots (
b2World_GetSnapshotreturns aUint8Array,b2World_RestoreFromSnapshot,b2CreateWorldFromSnapshot,b2World_GetStateHash), integer user data on bodies, shapes and joints (b2Body_SetUserData(bodyId, n)), per-body continuoussafetyFactor, wind and drag (b2Shape_ApplyWind), and joint force/torque thresholds. - JavaScript callbacks (pre-solve, custom filter, friction and restitution mixing) only work in single-threaded worlds, because they cannot be called from worker threads.
Not bound yet: recording and replay, and the standalone dynamic tree.
Licensing
Box2D v3 is licensed under the MIT License by Erin Catto.
box2d3-wasm is licensed under the MIT License by Alex Birch & Erik Sombroek.
