mujoco_wasm

The project provides a JavaScript interface to run MuJoCo 3.3.8 models in the browser using official WebAssembly bindings.

Workflow

1. Load the Module: Import load_mujoco and await its execution.
2. File System Setup: Use mujoco.FS to manage the Emscripten Virtual File System (e.g., creating directories, mounting memory file systems, and writing files fetched from the network).
3. Initialize Model and Data: Load an XML model using mujoco.MjModel.loadFromXML() and create a corresponding data object with new mujoco.MjData(model).
4. Simulation Loop: Use mujoco.mj_step(model, data) to advance the simulation and mujoco.mj_forward(model, data) for forward kinematics.
5. Access State: Model properties (like opt.timestep) and data buffers (like qpos, qvel, ctrl, xpos) are accessible as typed arrays.
6. Cleanup: Explicitly call .delete() on model and data objects to free resources.

import load_mujoco from "./dist/mujoco_wasm.js";

// Load the MuJoCo Module
const mujoco = await load_mujoco();

// Set up Emscripten's Virtual File System
mujoco.FS.mkdir('/working');
mujoco.FS.mount(mujoco.MEMFS, { root: '.' }, '/working');
mujoco.FS.writeFile("/working/humanoid.xml", await (await fetch("./assets/scenes/humanoid.xml")).text());

// Load model and create data
let model = mujoco.MjModel.loadFromXML("/working/humanoid.xml");
let data  = new mujoco.MjData(model);

// Access model properties directly
let timestep = model.opt.timestep;
let nbody = model.nbody;

// Access data buffers (typed arrays)
let qpos = data.qpos;  // Joint positions
let qvel = data.qvel;  // Joint velocities
let ctrl = data.ctrl;  // Control inputs
let xpos = data.xpos; // Body positions

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

// Run forward kinematics
mujoco.mj_forward(model, data);

// Reset simulation
mujoco.mj_resetData(model, data);

// Apply forces (force, torque, point, body, qfrc_target)
mujoco.mj_applyFT(model, data, [fx, fy, fz], [tx, ty, tz], [px, py, pz], bodyId, data.qfrc_applied);

// Clean up
data.delete();
model.delete();

The setupGUI function initializes a user interface for interacting with a MuJoCoDemo instance. It configures several interactive elements:

• Scene Selection: A dropdown menu to switch between predefined XML scenes (e.g., "Humanoid", "Cassie", "Mug"). Changing the selection triggers a scene reload.
• Help Menu: Accessible via the F1 key. It displays a dark, transparent overlay with a table of actions and their corresponding keyboard triggers.
• Simulation Controls (under a "Simulation" folder):
  • Pause Simulation: Toggles simulation pausing. Triggered via the checkbox or the Space key.
  • Reload: Reloads the current XML model. Triggered via the button or Ctrl + L.
  • Reset: Resets the simulation to its initial state. Triggered via the button or Backspace.
  • Keyframe Slider: Allows loading specific keyframes from the model. The slider's visibility and range are automatically updated based on the number of keyframes in the loaded model.
  • Noise Controls: Sliders for ctrlnoiserate and ctrlnoisestd (range 0.0 to 2.0, step 0.01).
• Actuators: Automatically generates sliders for all actuators in the model that have limited control ranges. These are grouped under an "Actuators" folder.
• Camera Reset: Resets the free camera to a default position. Triggered via Ctrl + A.

Note: setupGUI modifies the parentContext (an instance of MuJoCoDemo) by adding to its updateGUICallbacks and params objects.

import { setupGUI } from './mujocoUtils.js';

// Assuming parentContext is an instance of MuJoCoDemo
setupGUI(parentContext);

The loadSceneFromURL function asynchronously loads a MuJoCo model from the Emscripten Virtual File System and prepares the Three.js visualization.

Parameters:

• mujoco: The MuJoCo WASM namespace object.
• filename: The name of the .xml file located in the /working/ directory of the MuJoCo Virtual File System.
• parent: The MuJoCoDemo context object (which contains the Three.js scene).

Behavior:

1. Clears existing model and data from the parent context.
2. Loads the model using mujoco.MjModel.loadFromXML("/working/" + filename).
3. Initializes mujoco.MjData.
4. Creates a Three.js Group named "MuJoCo Root" to hold all visual elements.
5. Iterates through MuJoCo geoms to create corresponding Three.js geometries (Spheres, Capsules, Cylinders, Boxes, and Meshes).
6. Handles material properties including colors, transparency, specular intensity, and textures.
7. Parses and visualizes tendons and flex elements using InstancedMesh.
8. Parses and adds lights defined in the XML.

Returns: An array containing [model, data, bodies, lights].

const [model, data, bodies, lights] = await loadSceneFromURL(mujoco, 'humanoid.xml', parentContext);

Because MuJoCo and Three.js use different coordinate systems/handedness, these utility functions perform the necessary 'swizzling' to ensure visual accuracy.

getPosition(buffer, index, target, swizzle = true)

Extracts a position vector from a buffer at a specific index and applies it to a THREE.Vector3 target.

• swizzle: true (Default): Converts MuJoCo coordinates to Three.js: (x, z, -y).
• swizzle: false: Uses raw coordinates: (x, y, z).

getQuaternion(buffer, index, target, swizzle = true)

Extracts a quaternion from a buffer at a specific index and applies it to a THREE.Quaternion target.

• swizzle: true (Default): Converts MuJoCo quaternions to Three.js: (-y, -w, z, -x).
• swizzle: false: Uses raw coordinates: (x, y, z, w).

const pos = new THREE.Vector3();
getPosition(data.qpos, index, pos);

const quat = new THREE.Quaternion();
getQuaternion(data.qpos, index, quat);