Metadata-Version: 2.4
Name: multi_user_gymnasium
Version: 0.1.3
Summary: A platform for running interactive experiments in the browser with standard simulation environments.
Author: Chase McDonald
Author-email: Chase McDonald <chasecmcdonald@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: zensical ; extra == 'docs'
Requires-Dist: eventlet ; extra == 'server'
Requires-Dist: flask ; extra == 'server'
Requires-Dist: flask-login>=0.6.3 ; extra == 'server'
Requires-Dist: flask-socketio ; extra == 'server'
Requires-Dist: gymnasium ; extra == 'server'
Requires-Dist: msgpack ; extra == 'server'
Requires-Dist: pandas ; extra == 'server'
Requires-Dist: flatten-dict ; extra == 'server'
Requires-Dist: pytest>=8.0 ; extra == 'test'
Requires-Dist: playwright>=1.49 ; extra == 'test'
Requires-Dist: pytest-playwright>=0.6 ; extra == 'test'
Requires-Dist: pytest-timeout>=2.3 ; extra == 'test'
Requires-Python: >=3.10
Provides-Extra: docs
Provides-Extra: server
Provides-Extra: test
Description-Content-Type: text/markdown

# Multi-User Gymnasium (MUG)

![PyPI - Version](https://img.shields.io/pypi/v/multi-user-gymnasium)
![PyPI - Downloads](https://img.shields.io/pypi/dm/multi-user-gymnasium)

<div align="center">
  <img src="docs/assets/images/mug_logo.png" alt="MUG logo" width="300"/>
</div>

Multi-User Gymnasium (MUG) converts [Gymnasium](https://gymnasium.farama.org/) and [PettingZoo](https://pettingzoo.farama.org/) environments into browser-based, multi-user experiments. It enables Python simulation environments to be accessed online, allowing humans to interact with them individually or alongside AI agents and other participants.

## What does MUG offer?

- **Same environment, training to deployment.** Run user experiments in the browser against the exact same simulation environments you use to train your AI agents without any rewrites or ports.
- **In-browser execution.** Python environments and AI policies can run client-side for zero-latency experiences for participants. Heavier environments---or those that can't be compiled to run in the browser---can be run on the server.
- **Multi-human Experiments.** Built-in networking, rollback netcode, and waiting rooms for multi-participant experiments.
- **Experiment orchestration.** Scene flow, [participant management, and data collection](https://multi-user-gymnasium.readthedocs.io/en/latest/core-concepts/participants-and-data/) out of the box.
- **Extensive customizability.** Advanced hooks and configuration for custom rendering, matchmaking, scene logic, and more.

Get started by reading the [documentation](https://multi-user-gymnasium.readthedocs.io/).

## Installation

```bash
pip install multi-user-gymnasium[server]
```

<div align="center">
  <img src="docs/assets/images/overcooked_example.apng" alt="Overcooked human-AI demo" width="600"/>
</div>


## Development

MUG uses [uv](https://docs.astral.sh/uv/) for package management. From a cloned repository:

```bash
# Create the environment and install all dependencies (server, test, docs)
uv sync --all-extras

# Run the unit tests
uv run pytest tests/unit

# Run an example
uv run python -m examples.slime_volleyball.slimevb_human_ai
```

Dependencies are locked in `uv.lock`; after changing dependencies in
`pyproject.toml`, run `uv lock` and commit the updated lockfile.

### Releasing

Bump `version` in `pyproject.toml`, then build and publish with uv:

```bash
uv build
uv publish  # reads UV_PUBLISH_TOKEN or prompts for PyPI credentials
```

## Citation

If you use MUG in your research, please cite:

```bibtex
@article{mcdonald2026cogrid,
  title={CoGrid \& the Multi-User Gymnasium: A Framework for Multi-Agent Experimentation},
  author={McDonald, Chase and Gonzalez, Cleotilde},
  journal={arXiv preprint arXiv:2604.15044},
  year={2026}
}
```

## MUG in the Wild

Below are a list of projects that have used MUG. If you use it in your research, please let us know or open a PR for it to be added here.

```bibtex
@article{mcdonald2025controllable,
  title={Controllable Complementarity: Subjective Preferences in Human-AI Collaboration},
  author={McDonald, Chase and Gonzalez, Cleotilde},
  journal={arXiv preprint arXiv:2503.05455},
  year={2025}
}
```

## Acknowledgements

- This project was originally inspired by the work by Carroll et al. in their [Overcooked-AI demo](https://github.com/HumanCompatibleAI/overcooked-demo/tree/master). Most notably in the use of their Overcooked environment and assets in our examples, as well as the use of Phaser (with their client-server implementation).
