gym-zelda-1

An OpenAI Gym environment for The Legend of Zelda (i.e., Zelda 1) on The Nintendo Entertainment System (NES) based on the nes-py emulator.

Installation

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

pip install gym-zelda-1

Usage

Python

You must import gym_zelda_1 before trying to make an environment. This is because gym 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.

from nes_py.wrappers import JoypadSpace
import gym_zelda_1
from gym_zelda_1.actions import MOVEMENT

env = gym_zelda_1.make('Zelda1-v0')
env = JoypadSpace(env, MOVEMENT)

done = True
for step in range(5000):
    if done:
        state = env.reset()
    state, reward, done, info = env.step(env.action_space.sample())
    env.render()

env.close()

NOTE: gym_zelda_1.make is just an alias to gym.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.

gym_zelda_1 -m <`human` or `random`>

Step

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

Reward Function

TODO: The reward function is a complicated work in progress.

`info` dictionary

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

Key	Type	Description
`current_level`	`int`	The current level Link is in (0 for overworld)
`x_pos`	`int`	Link's x position in the screen (from the left)
`y_pos`	`int`	Link's y position in the screen (from the top)
`direction`	`str`	Link's direction as one of {"N", "S", "E", "W"}
`has_candled`	`bool`	Whether Link has candled the current room
`pulse_1`	`str`	The signal playing through pulse 1
`pulse_2`	`str`	The signal playing through pulse 2
`killed_enemies`	`int`	The number of enemies killed
`number_of_deaths`	`int`	The number of times Link has died
`sword`	`str`	The kind of sword Link has
`number_of_bombs`	`int`	The number of bombs in Link's inventory
`arrows_type`	`str`	The kind of arrows in Link's inventory
`has_bow`	`bool`	Whether Link has the bow in his inventory
`candle_type`	`str`	The type of candle in Link's inventory
`has_whistle`	`bool`	Whether Link has the whistle in his inventory
`has_food`	`bool`	Whether Link has food in his inventory
`potion_type`	`str`	The type of potion in Link's inventory
`has_magic_rod`	`bool`	Whether Link has the magic rod in his inventory
`has_raft`	`bool`	Whether Link has the raft in his inventory
`has_magic_book`	`bool`	Whether Link has the magic book in his inventory
`ring_type`	`str`	The type of ring in Link's inventory
`has_step_ladder`	`bool`	Whether Link has the step ladder in his inventory
`has_magic_key`	`bool`	Whether Link has the magic key in his inventory
`has_power_bracelet`	`bool`	Whether Link has the power bracelet in his inventory
`has_letter`	`bool`	Whether Link has the letter in his inventory
`is_clock_possessed`	`bool`	Whether the clock is possessed
`rupees`	`int`	The number of rupess Link has collected
`keys`	`int`	The number of keys in Link's inventory
`heart_containers`	`int`	The number of heart containers that Link has
`hearts`	`float`	The number of remaining health Link has
`has_boomerang`	`bool`	Whether Link has the boomerang in his inventory
`has_magic_boomerang`	`bool`	Whether Link has the magic boomerang in his inventory
`has_magic_shield`	`bool`	Whether Link has the magic shield in his inventory
`max_number_of_bombs`	`int`	The maximum number of bombs Link can carry

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 {OpenAI Gym}},
  URL = {https://github.com/Kautenja/gym-zelda-1},
  year = {2019},
}

References

The following references contributed to the construction of this project.

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

Kautenja/gym-zelda-1