MuJoCo JavaScript Bindings

These are the canonical JavaScript and TypeScript bindings for the MuJoCo physics engine.

This package provides a high-level API that allows you to interact with the core MuJoCo engine compiled into a high-performance WebAssembly (WASM) module. These bindings are developed and maintained by Google DeepMind and are always up to date with the latest developments in MuJoCo. For brevity, the documentation below will often refer to “JavaScript” but the concepts apply equally to TypeScript.

[!IMPORTANT] These bindings are still a WIP. For details, see the Future Work section. Also note that development has primarily taken place on Linux using Google Chrome. If you're working on a different OS or browser, you may encounter some rough edges. We have successfully tested the bindings on MacOS in CI but as of November 13th 2025 Windows in untested (the instructions here have worked on one Windows 11 machine but have failed on other machines).

Prerequisites

[!NOTE] Run all the commands in this README from the top-level directory.

• To compile the bindings.cc file, which generates the .wasm WebAssembly file, .js JavaScript import, and .d.ts TypeScript declaration file, you will need Emscripten SDK version 4.0.10. Later versions may work but are untested. To set up the SDK, do the following, you can run this anywhere but the rest of the commands in this README only work in the shell where you source the emsdk_env.sh script.

  git clone https://github.com/emscripten-core/emsdk.git
  ./emsdk/emsdk install 4.0.10
  ./emsdk/emsdk activate 4.0.10
  source ./emsdk/emsdk_env.sh

• To easily run the JavaScript tests and the demo application, node and npm are required. We recommend managing these using nvm. There are also various JavaScript dependencies needed for the tests, demo, and bindings build process. These dependencies are expected to be located in the wasm folder. To install them and ensure they can be found by later commands, run the following:

  npm install --prefix ./wasm
  export PATH="$(pwd)/wasm/node_modules/.bin:$PATH"

• To modify the bindings python3 is required because the bindings.cc file is generated by a Python script. To run the bindings generator tests, absl is required and pytest will be helpful. Set up a Python environment with these dependencies as follows:

  python3 -m venv .venv
  source .venv/bin/activate
  pip install -r python/build_requirements.txt

[!TIP] Emscripten is well-documented. We recommend reading the sections covering the Emscripten Compiler Settings, the Emscripten SDK, and the Embind library. To understand the limitations and caveats related to using the browser as a platform, see the Porting section.

User Guide

Bindings Generation

The bindings.cc file is compiled to generate to .wasm WebAssembly file, .js JavaScript import, and .d.ts TypeScript declaration file. These are the files you'll use to call MuJoCo from JavaScript. To generate them ensure the npm and Emscripten SDK prerequisites are set up and then run the following:

emcmake cmake -B build && cmake --build build

This command will generate the following folders under the project root:

• build: contains MuJoCo compiled using Emscripten.
• wasm/dist: contains the WebAssembly module, .js and .d.ts files.

Example Application

After generating the bindings you will be ready to write web applications using MuJoCo. We have provided a basic web application that uses Three.js to render a simple simulation, to try it run this command:

npm run dev:demo --prefix ./wasm

You may prefer to write your entire app in C++ and compile it using Emscripten. If you do this, you won’t need to use these bindings, since you’ll be writing minimal JavaScript, and the granularity of these bindings may be inappropriate (e.g., you might want to call multiple MuJoCo functions in the C++ callback invoked by requestAnimationFrame).

We have also found that a hybrid approach can be helpful, as it is often more convenient to work with browser APIs directly in JavaScript. If you choose to write your application in C++ and compile it using Emscripten, you may want to copy a subset of the EMSCRIPTEN_BINDINGS from bindings.cc into your application’s source file.

The package is ESM (type: module) and ships TypeScript types. Ensure your bundler or dev server serves the .wasm asset at runtime.

Named Access

The bindings support named access methods, similar to the Python bindings, allowing convenient access to model and data elements by name or index. For example, you can access a geometry by name using model.geom('mygeom') or a joint using data.jnt('myjoint').

For more details and examples of how to use named access, please refer to the named access tests and documentation.

Memory Management

Embind-wrapped C++ object handles created or returned into JavaScript live on the WebAssembly heap and are not garbage-collected by the JS runtime.

Any heap-allocated C++ object exposed to JS (e.g. via new Module.MyClass(...) or returned as a pointer/reference from a binding) must be explicitly freed when no longer needed to avoid memory leaks.

Use the generated .delete() method on wrapped instances to destroy the underlying C++ object:

const obj = new Module.MyClass(...);
// ... use obj ...
obj.delete(); // free the C++ memory

Be careful to call .delete() exactly once per created object (double-delete is an error). In JS code paths that may throw or return early, ensure deletion happens in finally blocks or wrap lifetime management to avoid leaks.

[!IMPORTANT] Embind's documentation strongly recommends that JavaScript code explicitly deletes any C++ object handles it has received.

Copy vs. Reference

When interacting with MuJoCo objects through the WASM bindings, it's important to understand how data is accessed. Properties on objects like MjModel and MjData can expose data in two ways: by copy or by reference.

1. By Copy (Value-based access)

Some properties return a copy of the data at the time of access. This is common for complex data structures that need to be marshalled from C++ to JavaScript.

A key example is MjData.contact. When you access data.contact, you get an object containing a copy of the contacts at that specific moment in the simulation.

If you step the simulation forward, they will not be updated. You must access data.contact again to get the new contact information.

The object you get is a JavaScript proxy interface generated by Emscripten’s Embind library when you expose a std::vector using register_vector<T>. It is essentially a "bridge" object.

export interface MjContactVec extends ClassHandle {
  /** Appends a new element to the end of the vector, increasing its length by one. */
  push_back(_0: MjContact): void;
  /** Resizes the vector to contain the specified number of elements, filling new slots with the provided value. */
  resize(_0: number, _1: MjContact): void;
  /** Returns the total number of elements currently stored in the vector. */
  size(): number;
  /** Retrieves the element at the specified index, or returns undefined if the index is out of bounds. */
  get(_0: number): MjContact | undefined;
  /** Overwrites the element at the specified index; returns true if successful or false if the index is invalid. */
  set(_0: number, _1: MjContact): boolean;
}

Example:

// Gets contacts at the current time.
const contacts = data.contact;

// Step the simulation
mujoco.mj_step(model, data);

// `contacts` is now stale. To get the new contacts, you must access the property again:
const newContacts = data.contact;

// Remember to delete all created objects when they are no longer needed.
contacts.delete();
newContacts.delete();

2. By Reference (View-based access)

Many properties, especially large numerical arrays, return a live view directly into the WebAssembly memory. This is highly efficient as it avoids copying large amounts of data.

A key example is MjData.qpos (joint positions). When you get a reference to this array, it points directly to the simulation's state data. Any changes in the simulation (e.g., after a call to mj_step) will be immediately reflected in this array.

// `qpos` is a live view into the simulation state.
const qpos = data.qpos;

console.log(qpos[0]); // Print initial position

// Step the simulation
mujoco.mj_step(model, data);

// `qpos` is automatically updated.
console.log(qpos[0]); // Print new position

// Remember to delete all created objects when they are no longer needed.
data.delete();

Data Layout: Row-Major Matrices

When a function from the MuJoCo C API returns a matrix (or needs a matrix as input), these are represented in the JavaScript bindings as flat, one-dimensional TypedArray's. The elements are stored in row-major order.

For example, a 3x10 matrix will be returned as a flat array with 30 elements. The first 10 elements represent the first row, the next 10 represent the second row, and so on.

Example: Accessing an element at (row, col)

// A 3x10 matrix stored as a flat array.
const matrix: Float64Array = ...;
const nRows = 3;
const nCols = 10;

// To access the element at row `i` and column `j`:
const element = matrix[i * nCols + j];

Working with Out Parameters

Many functions in the MuJoCo C API use "out parameters" to return data. This means instead of returning a value, they write the result into one of the arguments passed to them by reference (using pointers). In our JavaScript bindings, you'll need to handle these cases specifically.

There are two main scenarios you'll encounter:

1. Array-like Out Parameters

When a function expects a pointer to a primitive type (like mjtNum* or int*) to write an array of values, you need to pre-allocate memory for the result on the JavaScript side. We provide helper classes for this: mujoco.Uint8Buffer, mujoco.DoubleBuffer, mujoco.FloatBuffer, and mujoco.IntBuffer.

Here's how to use them:

1. Create a buffer: Instantiate the appropriate buffer class with an initial array of the correct size (e.g., an array of zeros).
2. Call the function: Pass the buffer instance to the function as the out parameter.
3. Access the result: Use the .getView() method on the buffer to get a TypedArray view of the data written by the C++ function.
4. Free the memory: When you are done with the buffer, you must call the .delete() method to free the underlying memory and prevent memory leaks.

Example: Rotating a vector

The function mju_rotVecQuat rotates a vector vec by a quaternion quat and stores the result in the res out parameter.

// Create a buffer to hold the 3D vector result.
const res = new mujoco.DoubleBuffer([0, 0, 0]);

const vec = [1, 0, 0];
const quat = [0.707, 0, 0, 0.707]; // 90-degree rotation around z-axis

try {
  // Call the function with the buffer as the out parameter.
  mujoco.mju_rotVecQuat(res, vec, quat);

  // Get the result as a Float64Array.
  const resultView = res.getView();
  console.log(resultView); // Expected: approximately [0, 1, 0]

} finally {
  // IMPORTANT: Free the memory allocated for the buffer.
  res.delete();
}

2. Struct Out Parameters (e.g., mjvCamera*, mjvScene*)

When a function modifies a struct passed by pointer, you should pass an instance of the corresponding JavaScript wrapper class. The underlying C++ struct will be modified in place.

Example: Updating a scene

The function mjv_updateScene populates an mjvScene object with information from mjModel and mjData.

// Create instances of the necessary structs.
const model = mujoco.MjModel.loadFromXML(xmlContent);
const data = new mujoco.MjData(model);
const scene = new mujoco.MjvScene(model, 1000);
const option = new mujoco.MjvOption();
const perturb = new mujoco.MjvPerturb();
const camera = new mujoco.MjvCamera();

// ... (step simulation, etc.)

// Update the scene. The 'scene' object is modified by the function.
mujoco.mjv_updateScene(
    model,
    data,
    option,
    perturb,
    camera,
    mujoco.mjtCatBit.mjCAT_ALL.value,
    scene
);

console.log('Number of geoms in scene:', scene.ngeom);

// Remember to delete all created objects when they are no longer needed.
scene.delete();
camera.delete();
perturb.delete();
option.delete();
data.delete();
model.delete();

As with buffers, you are responsible for managing the memory of these struct instances and must call .delete() on them when you are finished.

Enums

Access via .value:

mujoco.mjtDisableBit.mjDSBL_CLAMPCTRL.value

Constants

Scalar constants will be accessed the same way they are on python, simply:

mujoco.mjNEQDATA

Due to Embind limitations, more complex constants that are not scalar, but are represented in more dimensions are exposed as functions. E.g to use mujoco.mjFRAMESTRING you will need to call a function:

mujoco.get_mjFRAMESTRING()

This will return a javascript array representation of the values in MuJoCo mjFRAMESTRING.

Development

In order to change the bindings you will need to change the bindings.cc file but this should not be done manually. The file is generated using the Python scripts and template files in the codegen folder, to edit the bindings you will need to change those files and re-generate bindings.cc using this command:

PYTHONPATH=python/mujoco python3 -m wasm.codegen.update

The codegen scripts use MuJoCo’s Python introspect library to generate the Embind EMSCRIPTEN_BINDINGS block that binds C++ functions and classes to JavaScript. The functions and classes that are bound are wrappers around MuJoCo's C API. These wrappers provide a convenient place to add features like bounds checking and nice error reporting.

Testing

1. JavaScript API tests. These verify that a wide variety of MuJoCo functions and classes work correctly when called from JavaScript. Run the tests as follows:

   npm run test --prefix ./wasm

2. JavaScript API benchmark tests. The current benchmark tests check JavaScript/C++ shared memory buffers performance. We will increase the coverage of the benchmarks overtime. Run the benchmarks using this command:

   npm run benchmark --prefix ./wasm

3. Bindings generator tests. These are relevant when developing or extending the bindings. The following command finds and runs all test_*.py or *_test.py files in the wasm folder:

   PYTHONPATH=python/mujoco python3 -m pytest ./wasm

Debugging

We provide a “sandbox” app where you can quickly write code to run in your browser. Write your code in the main.ts file and use the following command to execute it in your browser:

npm run dev:sandbox --prefix ./wasm

The page will be blank since the script only logs to the console output. You can add your code at the indicated placeholder and use Chrome DevTools for debugging. It is possible to set up a debug workflow where stack traces and stepping through code across language boundaries work correctly. Our current method to do this only works internally at Google, but it should be possible to replicate the experience with open-source tooling — community suggestions are welcome!

Versioning

Package versions follow the official MuJoCo release versions. For example:

| npm version | MuJoCo version | |-------------|----------------| | 3.5.0 | 3.5.0 |

Future Work

1. Bind all useful APIs. These bindings are not yet complete. While the main MuJoCo APIs (mj_step, mj_loadXML, etc.) are well tested, other APIs (e.g., functions from mjspec.h) remain untested in real web applications (though test code for the mjspec bindings does exist).

2. Improve the developer experience. There is still work to be done to improve the developer experience when developing the WASM bindings. The most obvious issue is that bindings generation is not yet fully automated. As a result, it is currently less convenient than we'd like to identify and apply the changes needed to update the bindings. The goal is to eventually automate all binding code generation and clearly communicate what changes are required in the WASM bindings as a result of C++ updates. This problem should only affect developers working on the MuJoCo engine in C++, not end users writing JavaScript.

3. Improve the documentation. The documentation in this README will eventually be merged into the main MuJoCo documentation once the bindings are complete and named access is implemented. We also intend to review the bindings APIs and make adjustments to minimize differences with the Python bindings (while respecting language idioms) to reduce the amount of additional documentation required.

4. Improve the example. We aim to provide an example application that can be easily modified and embedded into a paper project page (see this example). This could be achieved by extending the Three.js example or by compiling the MuJoCo platform C++ code using the Emscripten toolchain. Community suggestions and contributions are welcome!