Jericho Quick-start¶
Install¶
Jericho requires Linux, Python 3, Spacy, and basic build tools like gcc.
There are two ways to install Jericho:
From PyPi¶
pip3 install jericho
python3 -m spacy download en_core_web_sm
From Github¶
- Clone Jericho Repository:
git clone https://github.com/microsoft/jericho.git
- Install Jericho:
cd jericho; pip3 install .
python3 -m spacy download en_core_web_sm
Acquire Games¶
An archive of games can be downloaded as follows:
wget https://github.com/BYU-PCCL/z-machine-games/archive/master.zip
unzip master.zip
Jericho-supported games may be found in the jericho-game-suite
subdirectory.
Basic Usage¶
Jericho implements a reinforcement learning interface in which the agent provides string-based actions, and the environment responds with string-based observations, rewards, and termination status:
from jericho import *
# Create the environment, optionally specifying a random seed
env = FrotzEnv("z-machine-games-master/jericho-game-suite/zork1.z5")
initial_observation, info = env.reset()
done = False
while not done:
# Take an action in the environment using the step fuction.
# The resulting text-observation, reward, and game-over indicator is returned.
observation, reward, done, info = env.step('open mailbox')
# Total score and move-count are returned in the info dictionary
print('Total Score', info['score'], 'Moves', info['moves'])
print('Scored', info['score'], 'out of', env.get_max_score())
Game Dictionary¶
jericho.FrotzEnv.get_dictionary()
returns the list of vocabulary words recognized by a game:
print('Recognized Vocabulary Words', list(env.get_dictionary()))
Note that most games recognize words up to a fixed length of 6 or 9 characters, so truncated words like ‘northe’ are functionally equivalent to ‘northeast.’ For more information see Game Dictionary.
Loading and Saving¶
It’s possible to save and load the game state using jericho.FrotzEnv.get_state()
and jericho.FrotzEnv.set_state()
:
from jericho import *
env = FrotzEnv(rom_path)
state = env.get_state() # Save the game to state
env.step('attack troll') # Oops!
'You swing and miss. The troll neatly removes your head.'
env.set_state(state) # Restore to saved state
Object Tree¶
The object tree is an internal representation of game state. Jericho provides functions to access all or parts of this tree. For more information see Object Tree.
all_objects = env.get_world_objects()
print('Me:', env.get_player_object())
print('My Inventory:', env.get_inventory())
print('My Current Location:', env.get_player_location())
Getting Valid Actions¶
One of the most common difficulties with parser-based text games is identifying which actions are recognized by the parser and applicable in the current location. Jericho’s jericho.FrotzEnv.get_valid_actions()
provides a best-guess list of valid-actions that will have an effect on the current game state:
>>> from jericho import *
>>> env = FrotzEnv("z-machine-games-master/jericho-game-suite/zork1.z5")
>>> env.reset()
'You are standing in an open field west of a white house, with a boarded front door. There is a small mailbox here.'
>>> valid_actions = env.get_valid_actions()
['south', 'open mailbox', 'west', 'north']
Walkthroughs¶
Jericho provides walkthroughs for supported games using jericho.FrotzEnv.get_walkthrough()
. To use the walkthrough, it is necessary to reset the environment with the desired seed:
>>> from jericho import *
>>> env = FrotzEnv("z-machine-games-master/jericho-game-suite/zork1.z5")
>>> walkthrough = env.get_walkthrough()
>>> for act in walkthrough:
>>> env.step(act)