| Name | miniworld-maze JSON |
| Version |
1.4.0
JSON |
| download |
| home_page | None |
| Summary | Multi-room maze environments from the DrStrategy paper. Provides NineRooms-v0, SpiralNineRooms-v0, and TwentyFiveRooms-v0 gymnasium environments. |
| upload_time | 2025-09-08 12:12:07 |
| maintainer | None |
| docs_url | None |
| author | Tim Joseph |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Tim Joseph
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
reinforcement-learning
environment
gymnasium
multi-room-maze
drstrategy
maze-navigation
partial-observability
3d-environments
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MiniWorld DrStrategy - Multi-Room Maze Environment
A refactored implementation of Dr. Strategy's MiniWorld-based maze environments with updated dependencies and modern Python packaging. Based on the now-deprecated [MiniWorld](https://github.com/Farama-Foundation/Miniworld) project and the original [DrStrategy implementation](https://github.com/ahn-ml/drstrategy).
## Environment Observations
### Environment Views
Full environment layout and render-on-position views:
| Full Environment | Partial Top-Down Observations | Partial First-Person Observations |
|---|---|---|
|  |   |   |
## Installation
```bash
pip install miniworld-maze
```
## Usage
### Registered Environments
This package registers the following gymnasium environments:
| Environment ID | Description | Rooms | Max Steps |
|---|---|---|---|
| `NineRooms-v0` | Standard 3×3 grid with adjacent room connections | 9 | 1000 |
| `SpiralNineRooms-v0` | 3×3 grid with spiral connection pattern | 9 | 1000 |
| `TwentyFiveRooms-v0` | Large 5×5 grid with complex navigation | 25 | 1000 |
All environments use `TOP_DOWN_PARTIAL` observation level and factory default room/door sizes by default.
### Basic Usage
See `examples/basic_usage.py` for a complete working example:
```python
#!/usr/bin/env python3
"""
Basic usage example for miniworld-maze environments.
This is a minimal example showing how to create and interact with the environment.
"""
import gymnasium as gym
import miniworld_maze # noqa: F401
def main():
# Create environment using gymnasium registry
env = gym.make("NineRooms-v0", obs_width=64, obs_height=64)
obs, info = env.reset()
# obs is a dictionary containing:
# - 'observation': (64, 64, 3) RGB image array
# - 'desired_goal': (64, 64, 3) RGB image of the goal state
# - 'achieved_goal': (64, 64, 3) RGB image of the current state
# Take a few random actions
for step in range(10):
action = env.action_space.sample()
obs, reward, terminated, truncated, info = env.step(action)
print(f"Step {step + 1}: reward={reward:.3f}, terminated={terminated}")
if terminated or truncated:
obs, info = env.reset()
env.close()
print("Environment closed successfully!")
if __name__ == "__main__":
main()
```
### Headless Environments
When running in headless environments (servers, CI/CD, Docker containers) or when encountering X11/OpenGL context issues, you need to enable headless rendering:
```bash
# Set environment variable before running Python
export PYGLET_HEADLESS=1
python your_script.py
```
Or in your Python code (must be set before importing the library):
```python
import os
os.environ['PYGLET_HEADLESS'] = '1'
import miniworld_maze
# ... rest of your code
```
This configures the underlying pyglet library to use EGL rendering instead of X11, allowing the environments to run without a display server.
## Environment Variants
### Available Environments
The package provides three main environment variants, each with different room layouts and connection patterns:
#### 1. NineRooms (3×3 Grid)
```
-------------
| 0 | 1 | 2 |
-------------
| 3 | 4 | 5 |
-------------
| 6 | 7 | 8 |
-------------
```
A standard 3×3 grid where adjacent rooms are connected. The agent can navigate between rooms through doorways, with connections forming a fully connected grid pattern.
#### 2. SpiralNineRooms (3×3 Spiral Pattern)
```
-------------
| 0 | 1 | 2 |
-------------
| 3 | 4 | 5 |
-------------
| 6 | 7 | 8 |
-------------
```
Same room layout as NineRooms but with a spiral connection pattern. Only specific room pairs are connected, creating a more challenging navigation task with fewer available paths.
#### 3. TwentyFiveRooms (5×5 Grid)
```
---------------------
| 0 | 1 | 2 | 3 | 4 |
---------------------
| 5 | 6 | 7 | 8 | 9 |
---------------------
|10 |11 |12 |13 |14 |
---------------------
|15 |16 |17 |18 |19 |
---------------------
|20 |21 |22 |23 |24 |
---------------------
```
A larger 5×5 grid environment with 25 rooms, providing more complex navigation challenges and longer episode lengths.
### Observation Types
Each environment supports three different observation modes:
- **`TOP_DOWN_PARTIAL`** (default): Agent-centered partial top-down view with limited visibility range (POMDP)
- **`TOP_DOWN_FULL`**: Complete top-down view showing the entire environment
- **`FIRST_PERSON`**: 3D first-person perspective view from the agent's current position
### Action Space
- **Discrete Actions** (default): 7 discrete actions (turn left/right, move forward/backward, strafe left/right, no-op)
- **Continuous Actions**: Continuous control with `continuous=True` parameter
### Environment Configuration
All environments can be customized with the following parameters:
```python
import gymnasium as gym
from miniworld_maze import ObservationLevel
import miniworld_maze # noqa: F401
env = gym.make(
"NineRooms-v0", # Environment variant
obs_level=ObservationLevel.TOP_DOWN_PARTIAL, # Observation type
obs_width=64, # Observation image width
obs_height=64, # Observation image height
room_size=5, # Size of each room in environment units
door_size=2, # Size of doors between rooms
agent_mode="empty", # Agent rendering: "empty", "circle", "triangle"
)
```
### Observation Format
The environment returns observations in dictionary format:
```python
obs = {
'observation': np.ndarray, # (64, 64, 3) RGB image of current view
'desired_goal': np.ndarray, # (64, 64, 3) RGB image of goal location
'achieved_goal': np.ndarray, # (64, 64, 3) RGB image of current state
}
```
### Reward Structure
- **Goal reaching**: Positive reward when agent reaches the goal location
- **Step penalty**: Small negative reward per step to encourage efficiency
- **Episode termination**: When goal is reached or maximum steps exceeded
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "miniworld-maze",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "reinforcement-learning, environment, gymnasium, multi-room-maze, drstrategy, maze-navigation, partial-observability, 3d-environments",
"author": "Tim Joseph",
"author_email": "Tim Joseph <tim@mctigger.com>",
"download_url": "https://files.pythonhosted.org/packages/59/dd/172ab40aa674c3f8c6c84e51c32a7363da449b0117f66362ea82c414801c/miniworld_maze-1.4.0.tar.gz",
"platform": null,
"description": "# MiniWorld DrStrategy - Multi-Room Maze Environment\n\nA refactored implementation of Dr. Strategy's MiniWorld-based maze environments with updated dependencies and modern Python packaging. Based on the now-deprecated [MiniWorld](https://github.com/Farama-Foundation/Miniworld) project and the original [DrStrategy implementation](https://github.com/ahn-ml/drstrategy).\n\n## Environment Observations\n\n### Environment Views\nFull environment layout and render-on-position views:\n\n| Full Environment | Partial Top-Down Observations | Partial First-Person Observations |\n|---|---|---|\n|  |   |   |\n\n## Installation\n\n```bash\npip install miniworld-maze\n```\n\n## Usage\n\n### Registered Environments\n\nThis package registers the following gymnasium environments:\n\n| Environment ID | Description | Rooms | Max Steps |\n|---|---|---|---|\n| `NineRooms-v0` | Standard 3\u00d73 grid with adjacent room connections | 9 | 1000 |\n| `SpiralNineRooms-v0` | 3\u00d73 grid with spiral connection pattern | 9 | 1000 |\n| `TwentyFiveRooms-v0` | Large 5\u00d75 grid with complex navigation | 25 | 1000 |\n\nAll environments use `TOP_DOWN_PARTIAL` observation level and factory default room/door sizes by default.\n\n### Basic Usage\n\nSee `examples/basic_usage.py` for a complete working example:\n\n```python\n#!/usr/bin/env python3\n\"\"\"\nBasic usage example for miniworld-maze environments.\n\nThis is a minimal example showing how to create and interact with the environment.\n\"\"\"\n\nimport gymnasium as gym\nimport miniworld_maze # noqa: F401\n\n\ndef main():\n # Create environment using gymnasium registry\n env = gym.make(\"NineRooms-v0\", obs_width=64, obs_height=64)\n obs, info = env.reset()\n\n # obs is a dictionary containing:\n # - 'observation': (64, 64, 3) RGB image array\n # - 'desired_goal': (64, 64, 3) RGB image of the goal state\n # - 'achieved_goal': (64, 64, 3) RGB image of the current state\n\n # Take a few random actions\n for step in range(10):\n action = env.action_space.sample()\n obs, reward, terminated, truncated, info = env.step(action)\n\n print(f\"Step {step + 1}: reward={reward:.3f}, terminated={terminated}\")\n\n if terminated or truncated:\n obs, info = env.reset()\n\n env.close()\n print(\"Environment closed successfully!\")\n\n\nif __name__ == \"__main__\":\n main()\n```\n\n### Headless Environments\n\nWhen running in headless environments (servers, CI/CD, Docker containers) or when encountering X11/OpenGL context issues, you need to enable headless rendering:\n\n```bash\n# Set environment variable before running Python\nexport PYGLET_HEADLESS=1\npython your_script.py\n```\n\nOr in your Python code (must be set before importing the library):\n\n```python\nimport os\nos.environ['PYGLET_HEADLESS'] = '1'\n\nimport miniworld_maze\n# ... rest of your code\n```\n\nThis configures the underlying pyglet library to use EGL rendering instead of X11, allowing the environments to run without a display server.\n\n## Environment Variants\n\n### Available Environments\n\nThe package provides three main environment variants, each with different room layouts and connection patterns:\n\n#### 1. NineRooms (3\u00d73 Grid)\n```\n-------------\n| 0 | 1 | 2 |\n-------------\n| 3 | 4 | 5 |\n-------------\n| 6 | 7 | 8 |\n-------------\n```\nA standard 3\u00d73 grid where adjacent rooms are connected. The agent can navigate between rooms through doorways, with connections forming a fully connected grid pattern.\n\n#### 2. SpiralNineRooms (3\u00d73 Spiral Pattern)\n```\n-------------\n| 0 | 1 | 2 |\n-------------\n| 3 | 4 | 5 |\n-------------\n| 6 | 7 | 8 |\n-------------\n```\nSame room layout as NineRooms but with a spiral connection pattern. Only specific room pairs are connected, creating a more challenging navigation task with fewer available paths.\n\n#### 3. TwentyFiveRooms (5\u00d75 Grid)\n```\n---------------------\n| 0 | 1 | 2 | 3 | 4 |\n---------------------\n| 5 | 6 | 7 | 8 | 9 |\n---------------------\n|10 |11 |12 |13 |14 |\n---------------------\n|15 |16 |17 |18 |19 |\n---------------------\n|20 |21 |22 |23 |24 |\n---------------------\n```\nA larger 5\u00d75 grid environment with 25 rooms, providing more complex navigation challenges and longer episode lengths.\n\n### Observation Types\n\nEach environment supports three different observation modes:\n\n- **`TOP_DOWN_PARTIAL`** (default): Agent-centered partial top-down view with limited visibility range (POMDP)\n- **`TOP_DOWN_FULL`**: Complete top-down view showing the entire environment\n- **`FIRST_PERSON`**: 3D first-person perspective view from the agent's current position\n\n### Action Space\n\n- **Discrete Actions** (default): 7 discrete actions (turn left/right, move forward/backward, strafe left/right, no-op)\n- **Continuous Actions**: Continuous control with `continuous=True` parameter\n\n### Environment Configuration\n\nAll environments can be customized with the following parameters:\n\n```python\nimport gymnasium as gym\nfrom miniworld_maze import ObservationLevel\nimport miniworld_maze # noqa: F401\n\nenv = gym.make(\n \"NineRooms-v0\", # Environment variant\n obs_level=ObservationLevel.TOP_DOWN_PARTIAL, # Observation type\n obs_width=64, # Observation image width\n obs_height=64, # Observation image height\n room_size=5, # Size of each room in environment units\n door_size=2, # Size of doors between rooms \n agent_mode=\"empty\", # Agent rendering: \"empty\", \"circle\", \"triangle\"\n)\n```\n\n### Observation Format\n\nThe environment returns observations in dictionary format:\n\n```python\nobs = {\n 'observation': np.ndarray, # (64, 64, 3) RGB image of current view\n 'desired_goal': np.ndarray, # (64, 64, 3) RGB image of goal location\n 'achieved_goal': np.ndarray, # (64, 64, 3) RGB image of current state\n}\n```\n\n### Reward Structure\n\n- **Goal reaching**: Positive reward when agent reaches the goal location\n- **Step penalty**: Small negative reward per step to encourage efficiency\n- **Episode termination**: When goal is reached or maximum steps exceeded\n\n\n## License\n\nMIT License - see LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Tim Joseph\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Multi-room maze environments from the DrStrategy paper. Provides NineRooms-v0, SpiralNineRooms-v0, and TwentyFiveRooms-v0 gymnasium environments.",
"version": "1.4.0",
"project_urls": {
"Bug Tracker": "https://github.com/mctigger/miniworld-maze/issues",
"Documentation": "https://github.com/mctigger/miniworld-maze#readme",
"Homepage": "https://github.com/mctigger/miniworld-maze",
"Repository": "https://github.com/mctigger/miniworld-maze"
},
"split_keywords": [
"reinforcement-learning",
" environment",
" gymnasium",
" multi-room-maze",
" drstrategy",
" maze-navigation",
" partial-observability",
" 3d-environments"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "91a99a3f6f4bc8e91df3c29777b854c9adaaa24eca47adde38d043ae5714663c",
"md5": "0ae515317445d875ded35504e1369771",
"sha256": "8f185b6324734b5229404eb8081e359df83a7255913a3f13cf21d3b90abd39a4"
},
"downloads": -1,
"filename": "miniworld_maze-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ae515317445d875ded35504e1369771",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32722655,
"upload_time": "2025-09-08T12:12:04",
"upload_time_iso_8601": "2025-09-08T12:12:04.038675Z",
"url": "https://files.pythonhosted.org/packages/91/a9/9a3f6f4bc8e91df3c29777b854c9adaaa24eca47adde38d043ae5714663c/miniworld_maze-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "59dd172ab40aa674c3f8c6c84e51c32a7363da449b0117f66362ea82c414801c",
"md5": "1807a24d838920ef297dd02b86852065",
"sha256": "abe9f68441af520712291fa0dc0f3792e22130ea869613a8b1aa2a1899ef0692"
},
"downloads": -1,
"filename": "miniworld_maze-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "1807a24d838920ef297dd02b86852065",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32686687,
"upload_time": "2025-09-08T12:12:07",
"upload_time_iso_8601": "2025-09-08T12:12:07.935355Z",
"url": "https://files.pythonhosted.org/packages/59/dd/172ab40aa674c3f8c6c84e51c32a7363da449b0117f66362ea82c414801c/miniworld_maze-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 12:12:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mctigger",
"github_project": "miniworld-maze",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "miniworld-maze"
}
