# Multi-Level Maze Gymnasium Environment
**Multi-Level Maze** is a [Gymnasium](https://gymnasium.farama.org/) environment that generates hierarchical mazes using recursive spanning-tree connectivity.
Each maze consists of multiple levels of structure, where every sub-block is internally connected.
---
## Getting Started
### Installation
You can install it using:
```bash
pip install multi-level-maze
```
Then, in your Python environment:
```python
import gymnasium as gym
import multi_level_maze
env = gym.make("MultiLevelMaze-v0", size=3, levels=3, maze_seed=2, max_steps=1000, cell_size=30)
obs, info = env.reset()
done, truncated = False, False
while not (done or truncated):
env.render()
action = env.action_space.sample()
obs, reward, done, truncated, info = env.step(action)
env.close()
```
---
## Environment Parameters
You can customize the environment using the following arguments when creating it with `gym.make("MultiLevelMaze-v0", ...)`.
| Argument | Type | Default | Description |
| ------------ | ---- | ------- | -------------------------------------------------------------------------- |
| `size` | int | 3 | Base grid size for each level. The total maze size is `size ** levels`. |
| `levels` | int | 2 | Number of hierarchical levels (recursive subdivisions). |
| `max_steps` | int | 1000 | Maximum steps per episode before truncation. |
| `cell_size` | int | 50 | Pixel size of each maze cell in render mode. |
| `maze_seed` | int | 1 | Seed controlling the maze structure. Fixed per environment. |
| `render_fps` | int | 5 | Frames per second when rendering with Pygame. |
---
### Reproducibility
* The **maze structure** is fixed by `maze_seed` and reused across resets.
* The **starting position and goal** are randomized each time you call `reset(seed=...)`.
* Using the same `seed` reproduces the same starting and goal positions.
* To generate a completely new maze, reinstantiate the environment with a different `maze_seed`.
---
## Observations and Actions
**Observation Space:**
A concatenated vector of one-hot encodings representing the agent’s and goal’s positions at each hierarchical level.
**Action Space:**
Discrete with 4 actions:
| Action | Meaning |
| ------ | ---------- |
| 0 | Move up |
| 1 | Move down |
| 2 | Move left |
| 3 | Move right |
---
## Citation
If you use this environment in your research, please cite it using the `CITATION.cff` file included in this repository.
---
## License
```
Copyright (C) 2025 Ali Jahani
This program is free software; you can redistribute it and/or modify it under the terms of the
GNU General Public License as published by the Free Software Foundation; either version 3 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program;
if not, see https://www.gnu.org/licenses.
```
---
## TODO
* [ ] **Vectorization**
Raw data
{
"_id": null,
"home_page": null,
"name": "multi-level-maze",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "reinforcement-learning, gymnasium, maze, environment, hierarchical, nested, multi-level",
"author": null,
"author_email": "Ali Jahani <alijahani@gmx.com>",
"download_url": "https://files.pythonhosted.org/packages/d1/a7/cfc6d1dd751f097ad4c30ead0da215cedf9e9e1c4c2af84e1ed52ce74e41/multi_level_maze-1.0.0.tar.gz",
"platform": null,
"description": "# Multi-Level Maze Gymnasium Environment\n\n**Multi-Level Maze** is a [Gymnasium](https://gymnasium.farama.org/) environment that generates hierarchical mazes using recursive spanning-tree connectivity.\nEach maze consists of multiple levels of structure, where every sub-block is internally connected.\n\n![Screenshot](./maze.png?raw=true \"Screenshot\")\n\n---\n\n## Getting Started\n\n### Installation\n\nYou can install it using:\n\n```bash\npip install multi-level-maze\n```\n\nThen, in your Python environment:\n\n```python\nimport gymnasium as gym\nimport multi_level_maze\n\nenv = gym.make(\"MultiLevelMaze-v0\", size=3, levels=3, maze_seed=2, max_steps=1000, cell_size=30)\nobs, info = env.reset()\n\ndone, truncated = False, False\nwhile not (done or truncated):\n env.render()\n action = env.action_space.sample()\n obs, reward, done, truncated, info = env.step(action)\n\nenv.close()\n```\n\n---\n\n## Environment Parameters\n\nYou can customize the environment using the following arguments when creating it with `gym.make(\"MultiLevelMaze-v0\", ...)`.\n\n| Argument | Type | Default | Description |\n| ------------ | ---- | ------- | -------------------------------------------------------------------------- |\n| `size` | int | 3 | Base grid size for each level. The total maze size is `size ** levels`. |\n| `levels` | int | 2 | Number of hierarchical levels (recursive subdivisions). |\n| `max_steps` | int | 1000 | Maximum steps per episode before truncation. |\n| `cell_size` | int | 50 | Pixel size of each maze cell in render mode. |\n| `maze_seed` | int | 1 | Seed controlling the maze structure. Fixed per environment. |\n| `render_fps` | int | 5 | Frames per second when rendering with Pygame. |\n\n---\n\n### Reproducibility\n\n* The **maze structure** is fixed by `maze_seed` and reused across resets.\n* The **starting position and goal** are randomized each time you call `reset(seed=...)`.\n* Using the same `seed` reproduces the same starting and goal positions.\n* To generate a completely new maze, reinstantiate the environment with a different `maze_seed`.\n\n---\n\n## Observations and Actions\n\n**Observation Space:**\nA concatenated vector of one-hot encodings representing the agent\u2019s and goal\u2019s positions at each hierarchical level.\n\n**Action Space:**\nDiscrete with 4 actions:\n\n| Action | Meaning |\n| ------ | ---------- |\n| 0 | Move up |\n| 1 | Move down |\n| 2 | Move left |\n| 3 | Move right |\n\n---\n\n## Citation\n\nIf you use this environment in your research, please cite it using the `CITATION.cff` file included in this repository.\n\n---\n\n## License\n\n```\nCopyright (C) 2025 Ali Jahani\n\nThis program is free software; you can redistribute it and/or modify it under the terms of the\nGNU General Public License as published by the Free Software Foundation; either version 3 of\nthe License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\nSee the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program;\nif not, see https://www.gnu.org/licenses.\n```\n\n---\n\n## TODO\n\n* [ ] **Vectorization**\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A hierarchical multi-level maze environment for Gymnasium",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [
"reinforcement-learning",
" gymnasium",
" maze",
" environment",
" hierarchical",
" nested",
" multi-level"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bdd534f9c9a849c547f23316619707f13f6ee2731a76793abf8f568bf7c8393d",
"md5": "807cbf21ee35615d10189b3161a960d0",
"sha256": "a485698352e733abd44f2ed2b52a154619cefb8647d9636b08067a32d308a39e"
},
"downloads": -1,
"filename": "multi_level_maze-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "807cbf21ee35615d10189b3161a960d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 19652,
"upload_time": "2025-10-21T15:31:44",
"upload_time_iso_8601": "2025-10-21T15:31:44.274485Z",
"url": "https://files.pythonhosted.org/packages/bd/d5/34f9c9a849c547f23316619707f13f6ee2731a76793abf8f568bf7c8393d/multi_level_maze-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d1a7cfc6d1dd751f097ad4c30ead0da215cedf9e9e1c4c2af84e1ed52ce74e41",
"md5": "2630cb3aa36f23999be8f340465a0ac2",
"sha256": "02f22ab8dde7a0a1fdf899592db865da7fed356425e36202eb29027c13472303"
},
"downloads": -1,
"filename": "multi_level_maze-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2630cb3aa36f23999be8f340465a0ac2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20072,
"upload_time": "2025-10-21T15:31:46",
"upload_time_iso_8601": "2025-10-21T15:31:46.304355Z",
"url": "https://files.pythonhosted.org/packages/d1/a7/cfc6d1dd751f097ad4c30ead0da215cedf9e9e1c4c2af84e1ed52ce74e41/multi_level_maze-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 15:31:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "multi-level-maze"
}
JSON