mujoco 3.2.4 → 3.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco",
-  "version": "3.2.4",
+  "version": "3.2.5",
   "description": "MuJoCo WASM bindings",
   "repository": {
     "type": "git",

package/README.md

@@ -1,410 +0,0 @@
-# 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:
-
-```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
-
-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:
-
-```sh
-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.
-
-### 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';
-
-const mujoco = await loadMujoco();
-
-const model = mujoco.MjModel.fromXMLString(`
-<mujoco>
-  <worldbody>
-    <geom type="sphere" size="0.1"/>
-  </worldbody>
-</mujoco>
-`);
-
-const data = new mujoco.MjData(model);
-mujoco.mj_step(model, data);
-```
-
-### Copy vs. 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 a new array containing the contacts at that specific moment in the simulation. If you step the simulation forward, this array will not be updated. You must access `data.contact` again to get the new contact information.
-
-Example:
-```typescript
-// 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;
-```
-
-#### 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.
-
-```typescript
-// `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
-```
-
-### 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)`
-```typescript
-// 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.
-
-```typescript
-// 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`.
-```typescript
-// 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`:
-```javascript
-mujoco.mjtDisableBit.mjDSBL_CLAMPCTRL.value
-```
-
-### Constants
-Scalar constants will be accessed the same way they are on python, simply:
-
-```javascript
-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:
-
-```javascript
-mujoco.get_mjFRAMESTRING()
-```
-
-This will return a javascript array representation of the values in MuJoCo `mjFRAMESTRING`.
-
-### 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
-
-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.
-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](#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!