mujoco 3.2.3 → 3.2.4

package/README.md

@@ -1,15 +1,131 @@
-# MuJoCo WASM bindings
+# 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](#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`](codegen/generated/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.
+
+  ```sh
+  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](https://github.com/nvm-sh/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:
+
+  ```sh
+  npm install --prefix ./wasm
+  export PATH="$(pwd)/wasm/node_modules/.bin:$PATH"
+  ```
+
+- To modify the bindings `python3` is required because the [`bindings.cc`](codegen/generated/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:
+
+  ```sh
+  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](https://emscripten.org/docs/tools_reference/settings_reference.html),
+> the [Emscripten SDK](https://emscripten.org/docs/tools_reference/emsdk.html),
+> and the [Embind](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html)
+> library. To understand the limitations and caveats related to using the
+> browser as a platform, see the
+> [Porting](https://emscripten.org/docs/porting/index.html#porting) section._
+
+## User Guide
+
+### Bindings Generation
+
+The [`bindings.cc`](codegen/generated/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:
 
-Official WebAssembly (WASM) bindings for the MuJoCo physics engine, compiled from the MuJoCo C/C++ sources into WASM with JS glue (Emscripten + Embind). The package ships prebuilt ESM-ready JS/WASM artifacts and TypeScript types for immediate use.
+```sh
+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
 
-**Important**:_These bindings are still a WIP_.
+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:
 
-## Install
 ```sh
-npm install mujoco
+npm run dev:demo --prefix ./wasm
 ```
 
-## Quick start (ESM / TypeScript)
+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.
+
+### 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](tests/bindings_test.ts#L1876-L2378) and [documentation](https://mujoco.readthedocs.io/en/stable/python.html#named-access).
+
+## Usage Guide
+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.
+
+### Install
+```sh
+npm install mujoco
+```
 
 ```ts
 import loadMujoco from 'mujoco';
@@ -28,9 +144,6 @@ const data = new mujoco.MjData(model);
 mujoco.mj_step(model, data);
 ```
 
-## Usage Guide
-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.
-
 ### Copy vs. Reference
 
 #### 1. By Copy (Value-based access)
@@ -187,13 +300,74 @@ mujoco.get_mjFRAMESTRING()
 
 This will return a javascript array representation of the values in MuJoCo `mjFRAMESTRING`.
 
-## Notes
+### About assets
 The package is ESM (`type: module`) and ships TypeScript types.
 
 Ensure your bundler or dev server serves the `.wasm` asset at runtime.
 
-### Development
-For detailed build instructions see the repository [README](https://github.com/google-deepmind/mujoco/tree/main/wasm#mujoco-javascript-bindings) (Emscripten toolchain, Embind bindings, producing the .wasm artifact, and targets for Node and browser).
+## Development
+
+In order to change the bindings you will need to change the [`bindings.cc`](codegen/generated/bindings.cc)
+file but this should not be done manually. The file is generated using the
+Python scripts and template files in the [`codegen`](codegen) folder, to edit
+the bindings you will need to change those files and re-generate [`bindings.cc`](codegen/generated/bindings.cc)
+using this command:
+
+```sh
+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:
+
+   ```sh
+   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:
+
+   ```sh
+   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:
+
+   ```sh
+   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`](tests/sandbox/main.ts) file and use
+the following command to execute it in your browser:
+
+```sh
+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.
@@ -203,6 +377,34 @@ For example:
 |-------------|----------------|
 | 3.5.0       | 3.5.0          |
 
----
-
-For full engine documentation, see: https://mujoco.readthedocs.io
+## 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](#example-application).**
+   We aim to provide an example application that can be easily modified and
+   embedded into a paper project page (see [this example](https://kzakka.com/robopianist/)).
+   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!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco",
-  "version": "3.2.3",
+  "version": "3.2.4",
   "description": "MuJoCo WASM bindings",
   "repository": {
     "type": "git",
@@ -15,8 +15,9 @@
     "mujoco",
     "physics",
     "wasm",
+    "google",
+    "deepmind",
     "webassembly",
-    "bindings",
     "simulation",
     "robotics",
     "emscripten",