mjswan – Real‑time Interactive MuJoCo in the Browser

What it is

mjswan is a Python/JavaScript library that lets you run MuJoCo physics simulations entirely in the web browser. It bundles the MuJoCo‑WASM engine, an ONNX runtime for neural‑network policies, and Three.js for 3‑D rendering, so a reinforcement‑learning (RL) demo can be shared as a static web page (e.g., on GitHub Pages) with no server‑side compute.

Core capabilities

Feature	What it means for you
Real‑time simulation & policy control	Load a MuJoCo model, attach an ONNX policy, and see the agent act frame‑by‑frame in the browser.
Interactive manipulation	Users can apply forces to objects with mouse, touch, or VR controllers, letting you explore “what‑if” scenarios live.
Cross‑platform (desktop, mobile, WebXR)	Works on regular browsers and on VR/AR headsets via WebXR, with hand‑tracking support.
Client‑only	All physics, rendering, and inference happen locally; no backend server is required.
Static‑site friendly	The whole demo compiles to static assets, perfect for GitHub Pages or embedding in notebooks.
mjlab‑native	A built‑in skill (`mjlab-to-mjswan`) converts any task from the `mjlab` benchmark suite into a web demo.
Customizable visualisation	You can plug in your own Three.js shaders, change camera controls, or overlay additional UI widgets.

How to get started

Install – either via pip (pip install mjswan) or npm (npm install mjswan).
Run a demo – after cloning the repo, install the example extras and launch a demo with the CLI:
```
mjswan demo simple
```

Write your own app – a minimal script looks like this:

import os, mujoco, mjswan
model_path = os.path.join(os.path.dirname(mujoco.__file__), "testdata", "model.xml")
spec = mujoco.MjSpec.from_file(model_path)

builder = mjswan.Builder()
builder.add_project(name="Sanity Check")\
       .add_scene(name="Test Model", spec=spec)
app = builder.build()
app.launch()   # opens a browser window with the simulation

Replace the model and optionally attach an ONNX policy to see an RL agent act.

Where it shines

Teaching & demos – Show RL concepts to students without asking them to install heavy native binaries.
Research reproducibility – Publish a paper’s MuJoCo experiment as a single URL that anyone can run.
Rapid prototyping – Iterate on policies or environment tweaks and instantly view the effect in the browser.

Ecosystem & extensions

mjswan Cloud – a hosted service (beta) that lets you upload demos and share them without building the static site yourself.
mjswan_playground – a curated collection of ready‑made demos ranging from simple pendulums to humanoid locomotion.
mjlab‑to‑mjswan skill – converts tasks from the mjlab benchmark suite into web‑ready simulations.

Documentation & community

Full docs: https://mjswan.readthedocs.io
Demo site: https://ttktjmt.github.io/mjswan/
CI badges show that the project is actively tested (GitHub Actions, PyTest, ReadTheDocs).

License

Apache‑2.0 – you can use, modify, and redistribute the code, provided you keep the attribution notices.

Bottom line: If you need a lightweight way to showcase MuJoCo‑based RL environments in a browser—whether for teaching, sharing research demos, or building interactive web‑apps—mjswan gives you a ready‑made stack that handles physics, inference, and 3‑D rendering without any server component.

ttktjmt/mjswan