Metadata-Version: 2.5
Name: mjswan
Version: 0.11.0
Summary: Browser-based MuJoCo simulation with real-time policy control
Project-URL: GitHub, https://github.com/ttktjmt/mjswan
Author: mjswan Developers
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: mujoco==3.11.0
Requires-Dist: nodeenv>=1.9.1
Requires-Dist: onnx>=1.20.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: check
Requires-Dist: pyright>=1.1.407; extra == 'check'
Requires-Dist: ruff==0.16.0; extra == 'check'
Requires-Dist: ty==0.0.77; extra == 'check'
Provides-Extra: dev
Requires-Dist: huggingface-hub>=0.26.0; extra == 'dev'
Requires-Dist: mjlab==1.6.0; extra == 'dev'
Requires-Dist: pre-commit>=3.3.2; extra == 'dev'
Requires-Dist: pyright>=1.1.407; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff==0.16.0; extra == 'dev'
Requires-Dist: torch>=2.9.1; extra == 'dev'
Requires-Dist: ty==0.0.77; extra == 'dev'
Requires-Dist: wandb>=0.23.1; extra == 'dev'
Provides-Extra: examples
Requires-Dist: huggingface-hub>=0.26.0; extra == 'examples'
Requires-Dist: mjlab==1.6.0; extra == 'examples'
Requires-Dist: onnxruntime>=1.21.0; extra == 'examples'
Requires-Dist: torch>=2.9.1; extra == 'examples'
Requires-Dist: wandb>=0.23.1; extra == 'examples'
Provides-Extra: hf
Requires-Dist: huggingface-hub>=0.26.0; extra == 'hf'
Provides-Extra: mjlab
Requires-Dist: mjlab==1.6.0; extra == 'mjlab'
Requires-Dist: torch>=2.9.1; extra == 'mjlab'
Provides-Extra: wandb
Requires-Dist: wandb>=0.23.1; extra == 'wandb'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://github.com/ttktjmt/mjswan/raw/main/assets/banner.svg" alt="mjswan" width="60%">
</p>
<p align="center">
  <strong><em>Real-time Interactive RL Simulation in Your Browser</em></strong>
</p>

<p align="center">
  <a href="https://github.com/ttktjmt/mjswan/actions/workflows/deploy.yml"><img src="https://github.com/ttktjmt/mjswan/actions/workflows/deploy.yml/badge.svg" alt="deploy"/></a>
  <a href="https://github.com/ttktjmt/mjswan/actions/workflows/pytest.yml"><img src="https://github.com/ttktjmt/mjswan/actions/workflows/pytest.yml/badge.svg" alt="test"/></a>
  <a href="https://mjswan.readthedocs.io"><img src="https://img.shields.io/readthedocs/mjswan?logo=readthedocs" alt="docs"/></a>
  <a href="https://pypi.org/project/mjswan"><img src="https://img.shields.io/pypi/v/mjswan.svg?logo=pypi" alt="pypi version"></a>
  <a href="https://www.npmjs.com/package/mjswan"><img src="https://img.shields.io/npm/v/mjswan.svg?logo=nodedotjs" alt="npm version"></a>
</p>

<p align="center">
  mjswan is a powerful framework for creating interactive MuJoCo simulations with real-time policy control, running entirely in the browser. Built on top of <a href="https://github.com/google-deepmind/mujoco/tree/main/wasm">mujoco wasm</a>, <a href="https://github.com/microsoft/onnxruntime">onnxruntime</a>, and <a href="https://github.com/mrdoob/three.js/">three.js</a>, it enables easy sharing of RL simulation demos as static sites, perfect for GitHub Pages hosting.
</p>

<p align="center">
  <a href="https://ttktjmt.github.io/mjswan/"><img src="assets/demo.webp" width="70%"/></a>
</p>

<p align="center">
  <em>Check out the demo ― <a href="https://ttktjmt.github.io/mjswan/">ttktjmt.github.io/mjswan</a></em>
</p>

---


## News

- **2026-08-17**: Created [mjswan_playground](https://github.com/ttktjmt/mjswan_playground), a collection of mjswan demos
- **2026-08-15**: Became mjlab-native, covering most [mjlab](https://github.com/mujocolab/mjlab) tasks
- **2026-06-02**: Adopted for the [MuscleMimic](https://github.com/amathislab/musclemimic) live demo [[Demo](https://mjswan-musclemimic.pages.dev/), [X](https://x.com/ckli85/status/2100242247547572394)]
- **2026-05-06**: Adopted for the [GentleHumanoid](https://gentle-humanoid.axell.top/#/) live demo [[Demo](https://mjswan-gentlehumanoid.pages.dev/), [X](https://x.com/Axell_wppr/status/2051878574874148953)]
- **2026-04-08**: Featured in the [MuJoCo README](https://github.com/google-deepmind/mujoco#first-party-bindings)


## Features

- **Real-time**: Run mujoco simulations and policy control in real time.
- **Interactive**: Change the state of objects by applying forces.
- **Cross-platform**: Works seamlessly on desktop and mobile devices.
- **VR & AR Support**: Native WebXR viewer with tracked hands that interact with objects.
- **Client-only**: All computation runs in the browser. No server for simulation is required.
- **Easy Sharing**: Host as a static site for effortless demo distribution (e.g., GitHub Pages).
- **Portable**: Embed the simulation in a web page or Google Colab notebook.
- **mjlab-native**: Create a web demo of any [mjlab](https://github.com/mujocolab/mjlab) tasks with minimal effort.
- **Customizable**: Visualize your mujoco models and onnx policies quickly.


## Quick Start

mjswan can be installed with `pip`:
``` sh
pip install mjswan  # or 'mjswan[dev]', 'mjswan[examples]'
```

or with `npm`:
``` sh
npm install mjswan
```

The demos live in `examples/`, which the wheel does not ship, so run them with the
`mjswan` CLI from a clone of this repository (after `pip install -e '.[examples]'`):
``` sh
mjswan demo          # lists the bundled demos
mjswan demo simple   # runs the simple demo
```

The minimum python script for a sanity check:
``` python
import os, mujoco, mjswan

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

builder = mjswan.Builder()
builder.add_project(name="Sanity Check").add_scene(name="Test Model", spec=mjspec)
app = builder.build()
app.launch()
```

For detailed instructions, visit the [documentation](https://mjswan.readthedocs.io).


## Acknowledgments

This project was greatly inspired by the [Facet project demo](https://facet.pages.dev/) from the research group at Tsinghua University.<br>
It is also built upon the excellent work of [zalo/mujoco_wasm](https://github.com/zalo/mujoco_wasm), one of the earliest efforts to run MuJoCo simulations in a browser.


## License

This project is licensed under the [Apache-2.0 License](LICENSE). When using mjswan, please retain attribution notices in the app to help other users discover this project.
