| Name | gym-zelda-pygame JSON |
| Version |
0.1.9
JSON |
| download |
| home_page | None |
| Summary | A ROM-free Zelda-like Gymnasium environment built on Pygame. |
| upload_time | 2025-08-10 20:00:02 |
| maintainer | None |
| docs_url | None |
| author | Henry LeCates |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2025 Henry LeCates
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
gymnasium
pygame
zelda
rl
environment
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# gym-zelda-pygame
A **Gymnasium** environment that wraps the Clear Code Pygame “Zelda” game into a **ROM-free**, modern RL playground. It exposes a pixel-observation interface, discrete actions, sensible rewards, and familiar wrappers (skip-frames, gray-scale resize to 84×84, frame-stack, normalize, channel-first) so you can train DQN/PPO/IMPALA-style agents without touching emulators or legacy Gym.
## Motivation
I recently finished a playthrough of **_The Legend of Zelda: Breath of the Wild_** and wanted to experiment with applying **reinforcement learning** to a Zelda-style world. Most existing environments either:
- rely on **ROMs/emulators**, or
- are tangled up with **deprecated `gym` + NumPy compatibility issues**.
## Installation
gym-zelda-pygame is published on **PyPI**. Install with:
```bash
pip install gym-zelda-pygame
```
## Environment Details
### Spaces
- **Action Space**: `Discrete(8)`
0) no-op
1) move up
2) move down
3) move left
4) move right
5) attack
6) magic
7) menu
- **Observation Space**: `Box(low=0, high=255, shape=(720, 1280, 3), dtype=uint8)` by default
(Typically wrap this 84×84 grayscale and stack frames for learning)
### Rendering
- `render_mode="human"`: Pygame window (60 FPS throttle)
- `render_mode="rgb_array"`: returns the current frame as a numpy array
- Headless safety: when not using `"human"`, SDL dummy drivers are used automatically.
### Episode Termination
- Episode ends when:
- Player health ≤ 0, or
- All enemies defeated
### Reward
Default (configurable) reward shaping in `ZeldaEnv`:
- Small step penalty: `-0.001` per step (encourage efficiency)
- Health changes: penalty for loss, small reward for gain
- Experience gain: small positive reward
- Enemy defeats: large positive reward (`+10.0` per enemy)
- Death penalty: `-100.0`
You can pass a **custom reward function** via `custom_reward_fn`:
```python
def my_reward_fn(current_state, previous_state, episode_steps):
# current_state: dict with keys shown below
# previous_state: same keys for previous step
# return float
...
env = ZeldaEnv(render_mode="rgb_array", custom_reward_fn=my_reward_fn)
```
### Info Dict
Each step() returns an info dict with:
```python
{
'episode_steps': int,
'player_health': int,
'player_exp': int,
'enemy_count': int,
'player_pos': (x: int, y: int),
}
```
## Credit
- **Game code** adapted from Clear Code’s Zelda tutorial: [clear-code-projects/Zelda](https://github.com/clear-code-projects/Zelda)
- **Graphics and audio assets** courtesy of Pixel-boy/AAA under CC0: [Ninja Adventure asset pack](https://pixel-boy.itch.io/ninja-adventure-asset-pack)
Respect the original projects’ licenses and assets. This environment is an RL wrapper around their codebase to support education.
Raw data
{
"_id": null,
"home_page": null,
"name": "gym-zelda-pygame",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "reinforcement-learning, gymnasium, pygame, zelda, rl, environment",
"author": "Henry LeCates",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a0/a7/7c4d2e38c5ed44e638f3799dc119f49f5d01393d74b5b1584be6e4b43597/gym_zelda_pygame-0.1.9.tar.gz",
"platform": null,
"description": "# gym-zelda-pygame\n\nA **Gymnasium** environment that wraps the Clear Code Pygame \u201cZelda\u201d game into a **ROM-free**, modern RL playground. It exposes a pixel-observation interface, discrete actions, sensible rewards, and familiar wrappers (skip-frames, gray-scale resize to 84\u00d784, frame-stack, normalize, channel-first) so you can train DQN/PPO/IMPALA-style agents without touching emulators or legacy Gym.\n\n## Motivation\n\nI recently finished a playthrough of **_The Legend of Zelda: Breath of the Wild_** and wanted to experiment with applying **reinforcement learning** to a Zelda-style world. Most existing environments either:\n- rely on **ROMs/emulators**, or\n- are tangled up with **deprecated `gym` + NumPy compatibility issues**.\n\n## Installation\ngym-zelda-pygame is published on **PyPI**. Install with:\n\n```bash\npip install gym-zelda-pygame\n```\n\n## Environment Details\n\n### Spaces\n\n- **Action Space**: `Discrete(8)`\n 0) no-op\n 1) move up\n 2) move down\n 3) move left\n 4) move right\n 5) attack\n 6) magic\n 7) menu\n \n- **Observation Space**: `Box(low=0, high=255, shape=(720, 1280, 3), dtype=uint8)` by default \n(Typically wrap this 84\u00d784 grayscale and stack frames for learning)\n\n### Rendering\n\n- `render_mode=\"human\"`: Pygame window (60 FPS throttle)\n- `render_mode=\"rgb_array\"`: returns the current frame as a numpy array\n- Headless safety: when not using `\"human\"`, SDL dummy drivers are used automatically.\n\n### Episode Termination\n\n- Episode ends when:\n- Player health \u2264 0, or\n- All enemies defeated\n\n### Reward\n\nDefault (configurable) reward shaping in `ZeldaEnv`:\n- Small step penalty: `-0.001` per step (encourage efficiency)\n- Health changes: penalty for loss, small reward for gain\n- Experience gain: small positive reward\n- Enemy defeats: large positive reward (`+10.0` per enemy)\n- Death penalty: `-100.0`\n\nYou can pass a **custom reward function** via `custom_reward_fn`:\n```python\ndef my_reward_fn(current_state, previous_state, episode_steps):\n # current_state: dict with keys shown below\n # previous_state: same keys for previous step\n # return float\n ...\nenv = ZeldaEnv(render_mode=\"rgb_array\", custom_reward_fn=my_reward_fn)\n```\n\n### Info Dict\n\nEach step() returns an info dict with: \n```python\n{\n 'episode_steps': int,\n 'player_health': int,\n 'player_exp': int,\n 'enemy_count': int,\n 'player_pos': (x: int, y: int),\n}\n```\n\n## Credit\n\n- **Game code** adapted from Clear Code\u2019s Zelda tutorial: [clear-code-projects/Zelda](https://github.com/clear-code-projects/Zelda)\n- **Graphics and audio assets** courtesy of Pixel-boy/AAA under CC0: [Ninja Adventure asset pack](https://pixel-boy.itch.io/ninja-adventure-asset-pack)\n\nRespect the original projects\u2019 licenses and assets. This environment is an RL wrapper around their codebase to support education.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Henry LeCates\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": "A ROM-free Zelda-like Gymnasium environment built on Pygame.",
"version": "0.1.9",
"project_urls": null,
"split_keywords": [
"reinforcement-learning",
" gymnasium",
" pygame",
" zelda",
" rl",
" environment"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3434e3a76ae72cee41e579498056fe424995184a781f2d4331f6febf7ca0c815",
"md5": "b96340b15d52ee2cace67ac61644d971",
"sha256": "0c756a5b6cd783b2df11ae5437cba531ce789807fa8a70c2e967be6570b43dbd"
},
"downloads": -1,
"filename": "gym_zelda_pygame-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b96340b15d52ee2cace67ac61644d971",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 2518304,
"upload_time": "2025-08-10T20:00:00",
"upload_time_iso_8601": "2025-08-10T20:00:00.526285Z",
"url": "https://files.pythonhosted.org/packages/34/34/e3a76ae72cee41e579498056fe424995184a781f2d4331f6febf7ca0c815/gym_zelda_pygame-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a0a77c4d2e38c5ed44e638f3799dc119f49f5d01393d74b5b1584be6e4b43597",
"md5": "3e11bc59227abec84d4aebd4a9efa829",
"sha256": "7299842b6eb7384779ea1d0341496703f6f8bb124f552ebe82b87b677abd1f8b"
},
"downloads": -1,
"filename": "gym_zelda_pygame-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "3e11bc59227abec84d4aebd4a9efa829",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 2428980,
"upload_time": "2025-08-10T20:00:02",
"upload_time_iso_8601": "2025-08-10T20:00:02.316977Z",
"url": "https://files.pythonhosted.org/packages/a0/a7/7c4d2e38c5ed44e638f3799dc119f49f5d01393d74b5b1584be6e4b43597/gym_zelda_pygame-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 20:00:02",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "gym-zelda-pygame"
}
