WASM compatibility§

The nphysics crate, as well as the nphysics testbed are compatible with WebAssembly (WASM) by relying on the stdweb crate. For example, all the demos on this website (see the Demo menu on top of this page) are the result of compiling the nphysics testbed for the wasm32-unknown-unknown target using cargo-web. This section describes how to setup your development environment to work with nphysics for WASM. This is a pretty standard procedure and your file hierarchy should basically look like that in the end.

Setup your development tools§

First, make sure you work with the nightly compiler:

rustup toolchain install nightly
rustup default nightly

You have to install the wasm32-unknown-unknown target with rustup as well as the cargo-web binary which we will use for compiling and deploying our project:

rustup target add wasm32-unknown-unknown
cargo install -f cargo-web

Setup and build your project§

Now we will create a binary that depends on nphysics2d and compile it with cargo-web. First initialize your project with:

cargo new --bin demo_nphysics_wasm
cd demo_nphysics_wasm

Edit the Cargo.toml file to include nphysics2d as a dependency:

[package]
name = "demo_nphysics_wasm"
version = "0.1.0"
authors = [ "you" ]

[dependencies]
nphysics2d = "0.14"

Before compiling our project, we need to add a .html file which will serve as a web page containing our WASM app. This can be done by adding an index.html file in a new static/ folder.

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>nphysics wasm example</title>
        <style>
            html, body, canvas {
                margin: 0px;
                padding: 0px;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <canvas id="canvas"></canvas>
        <script src="canvas.js"></script>
    </body>
</html>

Note that we added here a canvas which will be useful if you intend to do some rendering. Finally, we can build our application with:

cargo web deploy --target=wasm32-unknown-unknown --release

Further details on the cargo web command can be found here. Using nphysics itself on your WASM project is just as simple as using nphysics for other platforms: add an extern crate nphysics2d (or extern crate nphysics3d) to your main.rs file and use all the features you need as usual!

Working with wasm-bindgen§

The tutorial presented so far relied on the stdweb crate. You might however prefer to use the competing solution wasm-bindgen instead. To achieve this, you will need to prevent nphysics from depending on stdweb to avoid incompatibilities. In your Cargo.toml file, you have to disable the default nphysics features, and enable use-wasm-bindgen. For example:

nphysics3d = { version = "0.14", default-features = false, features = [ "dim3", "use-wasm-bindgen" ] }
nphysics2d = { version = "0.14", default-features = false, features = [ "dim2", "use-wasm-bindgen" ] }

The nphysics testbed