[](https://github.com/chrisjcc/quoridor/actions/workflows/claude-code-review.yml)
<!-- [](https://github.com/chrisjcc/quoridor/actions/workflows/claude-code-review.yml) -->
# 🧠 Quoridor-RL: A Multi-Agent RL Environment for the Quoridor Board Game
**Quoridor-RL** is a Python-based simulation environment for the Quoridor board game, compatible with the Gymnasium API and multi-agent RL training using Ray RLlib. It also includes a 3D interactive web viewer built with Three.js, and supports human interaction, imitation learning, and deployment on Hugging Face Spaces.
<div align="center">
<img src="https://github.com/chrisjcc/quoridor/blob/main/images/quoridor_board.png" alt="Quoridor Board" width="500"/>
<!-- <img src="https://raw.githubusercontent.com/chrisjcc/quoridor/main/images/quoridor_board.png" alt="Quoridor Board" width="500"/> -->
</div>
---
## ✨ Features
- ✅ Fully rule-compliant 2- and 4-player Quoridor engine
- ♻️ Multi-agent training support (Ray RLlib)
- 🎮 Human-agent interaction mode
- 📈 Episode logging for imitation learning
- 🧠 Gymnasium-compatible environment
- 🌐 3D visualization in the browser (Three.js)
- 🚀 Hugging Face Space ready
---
## 📦 Installation
### Python Game Engine
```bash
pip install quoridor-env
```
JavaScript Viewer
```bash
cd web-viewer/
npm install
npm run dev
```
🧪 Quick Start: Training with Ray RLlib
```python
from ray.rllib.algorithms.ppo import PPOConfig
from quoridor.env import QuoridorEnv
config = PPOConfig().environment(env=QuoridorEnv, env_config={...})
algo = config.build()
algo.train()
See training_examples/ for full MARL setups.
```
🌍 Web Viewer
The web UI is built with Three.js and supports:
- Live replay of RL episodes
- Human-vs-agent gameplay
- Drag-and-drop wall placement
- API polling or WebSocket update
Launch
```bash
cd web-viewer/
npm run dev
```
📊 Observation & Action Spaces
Observation
Shape: (C, 9, 9)
Channels:
- Player positions
- Opponent positions
- Goal rows
- Horizontal/vertical walls
Action
Discrete:
- 0–3: move in cardinal directions
- 4–N: place wall at encoded location and orientation
See docs/observation_action.md for details.
🧠 Imitation Learning Support
Episodes are logged to JSONL or `.npz` with:
- `observations`, `actions`, `rewards`, `next_observations`, `dones`
Compatible with `HumanCompatibleAI/imitation`:
```bash
imitation-train expert_demos.npz --algo=bc
```
🚀 Hugging Face Space
You can deploy the environment and viewer together on Hugging Face Spaces.
Example layout:
```bash
huggingface-space/
├── app.py # Gradio or Flask API server
├── assets/ # Quoridor model data
└── web/ # Built JS assets
📜 License
MIT License. See `LICENSE`.
```
🤝 Contributing
Pull requests and feature suggestions are welcome! Please open an issue to discuss major changes first.
Raw data
{
"_id": null,
"home_page": "https://github.com/chrisjcc/quoridor",
"name": "quoridor-env",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "quoridor gymnasium reinforcement-learning board-game",
"author": "Christian Contreras",
"author_email": "chrisjcc@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/a4/93/3a2b17554a5d1309ffe6c1e7a49cc05154ac7ce171bf1f1ba130d1643a45/quoridor_env-0.2.6.tar.gz",
"platform": null,
"description": "[](https://github.com/chrisjcc/quoridor/actions/workflows/claude-code-review.yml)\n\n<!-- [](https://github.com/chrisjcc/quoridor/actions/workflows/claude-code-review.yml) -->\n\n# \ud83e\udde0 Quoridor-RL: A Multi-Agent RL Environment for the Quoridor Board Game\n\n**Quoridor-RL** is a Python-based simulation environment for the Quoridor board game, compatible with the Gymnasium API and multi-agent RL training using Ray RLlib. It also includes a 3D interactive web viewer built with Three.js, and supports human interaction, imitation learning, and deployment on Hugging Face Spaces.\n\n<div align=\"center\">\n <img src=\"https://github.com/chrisjcc/quoridor/blob/main/images/quoridor_board.png\" alt=\"Quoridor Board\" width=\"500\"/>\n <!-- <img src=\"https://raw.githubusercontent.com/chrisjcc/quoridor/main/images/quoridor_board.png\" alt=\"Quoridor Board\" width=\"500\"/> -->\n</div>\n\n---\n\n## \u2728 Features\n\n- \u2705 Fully rule-compliant 2- and 4-player Quoridor engine\n- \u267b\ufe0f Multi-agent training support (Ray RLlib)\n- \ud83c\udfae Human-agent interaction mode\n- \ud83d\udcc8 Episode logging for imitation learning\n- \ud83e\udde0 Gymnasium-compatible environment\n- \ud83c\udf10 3D visualization in the browser (Three.js)\n- \ud83d\ude80 Hugging Face Space ready\n\n---\n\n## \ud83d\udce6 Installation\n\n### Python Game Engine\n\n```bash\npip install quoridor-env\n```\n\nJavaScript Viewer\n```bash\ncd web-viewer/\nnpm install\nnpm run dev\n```\n\n\ud83e\uddea Quick Start: Training with Ray RLlib\n```python\n\nfrom ray.rllib.algorithms.ppo import PPOConfig\nfrom quoridor.env import QuoridorEnv\n\nconfig = PPOConfig().environment(env=QuoridorEnv, env_config={...})\nalgo = config.build()\nalgo.train()\nSee training_examples/ for full MARL setups.\n```\n\n\ud83c\udf0d Web Viewer\nThe web UI is built with Three.js and supports:\n- Live replay of RL episodes\n- Human-vs-agent gameplay\n- Drag-and-drop wall placement\n- API polling or WebSocket update\n\nLaunch\n```bash\ncd web-viewer/\nnpm run dev\n```\n\n\ud83d\udcca Observation & Action Spaces\nObservation\nShape: (C, 9, 9)\nChannels:\n- Player positions\n- Opponent positions\n- Goal rows\n- Horizontal/vertical walls\n\nAction\nDiscrete:\n- 0\u20133: move in cardinal directions\n- 4\u2013N: place wall at encoded location and orientation\n\nSee docs/observation_action.md for details.\n\n\ud83e\udde0 Imitation Learning Support\nEpisodes are logged to JSONL or `.npz` with:\n- `observations`, `actions`, `rewards`, `next_observations`, `dones`\n\nCompatible with `HumanCompatibleAI/imitation`:\n\n```bash\nimitation-train expert_demos.npz --algo=bc\n```\n\n\ud83d\ude80 Hugging Face Space\nYou can deploy the environment and viewer together on Hugging Face Spaces.\n\nExample layout:\n\n```bash\nhuggingface-space/\n\u251c\u2500\u2500 app.py # Gradio or Flask API server\n\u251c\u2500\u2500 assets/ # Quoridor model data\n\u2514\u2500\u2500 web/ # Built JS assets\n\ud83d\udcdc License\nMIT License. See `LICENSE`.\n```\n\n\ud83e\udd1d Contributing\nPull requests and feature suggestions are welcome! Please open an issue to discuss major changes first.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Quoridor game engine with Gym environment for RL",
"version": "0.2.6",
"project_urls": {
"Homepage": "https://github.com/chrisjcc/quoridor"
},
"split_keywords": [
"quoridor",
"gymnasium",
"reinforcement-learning",
"board-game"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f93c7f12bc5d6d48a2b5263a0dd434ba7c84fdce03434a48446621f257b3e84c",
"md5": "e8c6b40787edb3adde2d12f76c0a7ac5",
"sha256": "b9ca05b77366d505cf06bf9fae7849d668f1fb39a9b9f14396fbc70a23ba3355"
},
"downloads": -1,
"filename": "quoridor_env-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8c6b40787edb3adde2d12f76c0a7ac5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22264,
"upload_time": "2025-07-31T15:29:39",
"upload_time_iso_8601": "2025-07-31T15:29:39.756816Z",
"url": "https://files.pythonhosted.org/packages/f9/3c/7f12bc5d6d48a2b5263a0dd434ba7c84fdce03434a48446621f257b3e84c/quoridor_env-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a4933a2b17554a5d1309ffe6c1e7a49cc05154ac7ce171bf1f1ba130d1643a45",
"md5": "62165f8c8820ef32411e0e79bca6f92f",
"sha256": "7b31f5ebe09244fedcb31454948988bc60529018bd55b0fb964e4db080d31bea"
},
"downloads": -1,
"filename": "quoridor_env-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "62165f8c8820ef32411e0e79bca6f92f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 49751,
"upload_time": "2025-07-31T15:29:40",
"upload_time_iso_8601": "2025-07-31T15:29:40.887327Z",
"url": "https://files.pythonhosted.org/packages/a4/93/3a2b17554a5d1309ffe6c1e7a49cc05154ac7ce171bf1f1ba130d1643a45/quoridor_env-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 15:29:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chrisjcc",
"github_project": "quoridor",
"github_not_found": true,
"lcname": "quoridor-env"
}
JSON
