gym-zelda-1

A Gymnasium environment for The Legend of Zelda (i.e., Zelda 1) on The Nintendo Entertainment System (NES) based on the nes-py emulator. This wrapper keeps a deliberately narrow, lower-maturity scope: it exposes Zelda RAM state and NES control semantics for experimentation, while expecting users to supply their own legally obtained ROM and task-specific training wrappers. CI currently tests CPython 3.13 and 3.14 on macOS, Linux, and Windows.

Installation

The preferred installation of gym-zelda-1 is from pip:

pip install gym-zelda-1

Python 3.13 or newer is required. The supported CI targets are CPython 3.13 and 3.14.

gym-zelda-1 does not distribute Nintendo ROM assets. Provide your own legally obtained Zelda ROM through the package's expected local workflow.

Usage

Python

You must import gym_zelda_1 before trying to make an environment. This is because Gymnasium environments are registered at runtime. By default, gym_zelda_1 environments use the full NES action space of 256 discrete actions. To constrain this, gym_zelda_1.actions provides an action list called MOVEMENT (20 discrete actions) for the nes_py.wrappers.JoypadSpace wrapper.

import gymnasium as gym
from nes_py.wrappers import JoypadSpace
import gym_zelda_1
from gym_zelda_1.actions import MOVEMENT

env = gym.make('Zelda1-v0', render_mode='human')
env = JoypadSpace(env, MOVEMENT)

observation, info = env.reset(seed=123)
for step in range(5000):
    action = env.action_space.sample()
    observation, reward, terminated, truncated, info = env.step(action)
    done = terminated or truncated
    env.render()

    if done:
        observation, info = env.reset()

env.close()

NOTE: gym_zelda_1.make is just an alias to gymnasium.make for convenience.

NOTE: remove calls to render in training code for a nontrivial speedup.

Command Line

gym_zelda_1 features a command line interface for playing environments using either the keyboard, or uniform random movement.

Print the command-line help with:

gym_zelda_1 -h

gym_zelda_1 --mode human --actionspace movement
gym_zelda_1 --mode random --steps 500 --render --actionspace movement
gym_zelda_1 --mode random --steps 5000 --no-render --seed 123 --actionspace movement --no-progress

Use --actionspace full for the default 256-action NES controller space, or --actionspace movement for the gym_zelda_1.actions.MOVEMENT preset with nes_py.wrappers.JoypadSpace. Human mode always requires rendering; headless --no-render playback is available in random mode.

Step

Info about the rewards and info returned by the step method.

Zelda1-v0 is a navigation and state-inspection sandbox. It exposes Zelda RAM state through info, preserves the full NES action and observation contract, and leaves task objectives such as route completion, dungeon progress, or time limits to caller-provided wrappers.

Reward Function

The reward is always 0.0. This neutral reward is deliberate: the current v0 environment does not infer long-horizon Zelda progress from partial RAM signals. Use external wrappers when training against a specific navigation, combat, or collection objective.

Termination and Truncation

The environment has no internal terminal condition. terminated is always False for Zelda1-v0; death is treated as a non-terminal recovery sequence. When Link reaches zero health, the environment advances through the death and continue flow before subsequent gameplay continues.

Low health is characterized by the health meter as being above zero and at or below one heart. The pulse 2 audio RAM byte can identify transient death and continue cues (Death Spiral and Continue Screen), but these cues are not used as episode lifecycle signals in v0. The registered Zelda1-v0 spec does not set max_episode_steps, so Gymnasium does not add a registration-level TimeLimit; truncated remains False unless a caller applies an external limit wrapper.

info dictionary

The info dictionary returned by the step method contains the following keys:

Publishing

PyPI releases are published by the Publish to PyPI GitHub Actions workflow through PyPI trusted publishing, not by local twine credentials. Configure the PyPI project publisher with owner Kautenja, repository gym-zelda-1, workflow filename publish.yml, and environment pypi.

Releases should follow the current GitHub Actions flow:

1. Create and push a tag that matches pyproject.toml's version, with or without a leading v.
2. Let the CI workflow build and attach release artifacts for that tag.
3. Publish a GitHub Release from that tag to trigger the trusted-publishing workflow.

Citation

Please cite gym-zelda-1 if you use it in your research.

@misc{gym-zelda-1,
  author = {Christian Kauten},
  howpublished = {GitHub},
  title = {{The Legend of Zelda} for {Gymnasium}},
  URL = {https://github.com/Kautenja/gym-zelda-1},
  year = {2019},
}

References

The following references contributed to the construction of this project.

1. The Legend of Zelda: RAM Map. Data Crystal ROM Hacking.
2. The Legend of Zelda: Memory Addresses. NES Hacker.