multi-level-maze 1.0.0

A hierarchical multi-level maze environment for Gymnasium

Multi-Level Maze Gymnasium Environment

Multi-Level Maze is a Gymnasium 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:

pip install multi-level-maze

Then, in your Python environment:

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