Frotz Environment

The Frotz Environment is the interface between a learning agent and an interactive fiction game.

class jericho.FrotzEnv(story_file, seed=None)

The Frotz Environment is a fast interface to Z-Machine games.

Parameters:
  • story_file (path) – Path to a Z-machine rom file (.z3/.z5/.z6/.z8).
  • seed (int) –

    Seed the random number generator used by the emulator. Default: use walkthrough’s seed if it exists,

    otherwise use value of -1 which changes with time.
bindings

Gets information pertaining to the currently loaded game. Returns a dictionary with the following keys:

  • name: Name of the game. E.g. zork1
  • rom: Name of the file used to load the game. E.g. zork1.z5
  • walkthrough: A walkthrough for the game.
  • seed: Seed necessary to replicate the walkthrough.
  • grammar: List of action templates for the game.
  • max_word_length: Maximum number of characters per word recognized by the parser.
Returns:Dictionary containing game-specific bindings if it exists. Otherwise, an empty dictionary.
Example: 
>>> import jericho
>>> env = jericho.FrotzEnv('zork1')
>>> env.bindings
{
'name': 'zork1',
'rom': 'zork1.z5',
'seed': 12,
'max_word_length': 6,
'minimal_actions': 'Ulysses/wait/pray/inventory/go down/...',
'grammar': 'again/g;answer/reply;back;barf/chomp/...',
'walkthrough': 'N/N/U/Get egg/D/S/E/Open window/...'
}

Note

Walkthroughs are defined for only a few games.

close()

Cleans up the FrotzEnv, freeing any allocated memory.

copy()

Forks this FrotzEnv instance.

game_over()

Returns True if the game is over and the player has lost.

get_dictionary()

Returns a list of jericho.DictionaryWord words recognized by the game’s parser. See Game Dictionary.

get_inventory()

Returns a list of jericho.ZObject in the player’s posession.

get_max_score()

Returns the integer maximum possible score for the game.

get_moves()

Returns the integer number of moves taken by the player in the current episode.

get_object(obj_num)

Returns a jericho.ZObject with the corresponding number or None if the object doesn’t exist in the Object Tree.

Parameters:obj_num (int) – Object number between 0 and len(get_world_objects()).
get_player_location()

Returns the jericho.ZObject corresponding to the location of the player in the world.

get_player_object()

Returns the jericho.ZObject corresponding to the player.

get_score()

Returns the integer current game score.

get_state()

Returns the internal game state. This state can be subsequently restored using jericho.FrotzEnv.set_state().

Returns:Tuple of (ram, stack, pc, sp, fp, frame_count, rng). 
>>> from jericho import *
>>> env = FrotzEnv(rom_path)
>>> state = env.get_state()
>>> env.step('attack troll') # Oops!
'You swing and miss. The troll neatly removes your head.'
>>> env.set_state(state) # Whew, let's try something else
get_valid_actions(use_object_tree=True, use_ctypes=True, use_parallel=True)

Attempts to generate a set of unique valid actions from the current game state.

Parameters:
  • use_object_tree (boolean) – Query the Object Tree for names of surrounding objects.
  • use_ctypes (boolean) – Uses the optimized ctypes implementation of valid action filtering.
  • use_parallel (boolean) – Uses the parallized implementation of valid action filtering.
Returns:

A list of valid actions.
get_walkthrough()

Returns the walkthrough for the game.

Returns:A list containing walkthrough action strings needed to complete the game.

Note

To reproduce the walkthrough it’s also necessary to reset the environment with use_walkthrough_seed=True.

get_world_objects(clean=False)

Returns an array containing all the jericho.ZObject in the game.

Parameters:clean (Boolean) – If True, disconnects noisy objects like Zork1’s thief from the Object Tree. This is mainly useful if using world objects as an indication of unique game state.
Returns:Array of jericho.ZObject.
Example: 
>>> from jericho import *
>>> env = FrotzEnv('zork1.z5')
>>> env.get_world_objects()
 Obj0:  Parent0 Sibling0 Child0 Attributes [] Properties [],
 Obj1: pair hands Parent247 Sibling2 Child0 Attributes [14, 28] Properties [18, 16],
 Obj2: zorkmid Parent247 Sibling3 Child0 Attributes [] Properties [18, 17],
 Obj3: way Parent247 Sibling5 Child0 Attributes [14] Properties [18, 17, 16],
 Obj4: cretin Parent180 Sibling181 Child0 Attributes [7, 9, 14, 30] Properties [18, 17, 7],
 Obj5: you Parent247 Sibling6 Child0 Attributes [30] Properties [18, 17],
 ...
 Obj250: board Parent249 Sibling73 Child0 Attributes [14] Properties [18, 17]
get_world_state_hash()

Returns a MD5 hash of the clean world-object-tree. Such a hash may be useful for identifying when the agent has reached new states or returned to existing ones.

Example: 
>>> env = FrotzEnv('zork1.z5')
>>> env.reset()
# Start at West of the House with the following hash
>>> env.get_world_state_hash()
'79c750fff4368efef349b02ff50ffc23'
>>> env.step('n')
# Moving to North of House changes the hash
>>> get_world_state_hash(env)
'8a3a8538c0019a69128f755e4b719fbd'
>>> env.step('w')
# Moving back to West of House we recover the original hash
>>> env.get_world_state_hash()
'79c750fff4368efef349b02ff50ffc23'
load(story_file, seed=None)

Loads a Z-Machine game.

Parameters:
  • story_file (path) – Path to a Z-machine rom file (.z3/.z5/.z6/.z8).
  • seed (int) –

    Seed the random number generator used by the emulator. Default: use walkthrough’s seed if it exists,

    otherwise use value of -1 which changes with time.
reset()

Resets the game.

Parameters:use_walkthrough_seed – Seed the emulator to reproduce the walkthrough.
Returns:A tuple containing the initial observation, and a dictionary of info.
Return type:string, dictionary
seed(seed=None)

Changes seed used for the emulator’s random number generator.

Parameters:seed –

Seed the random number generator used by the emulator. Default: use walkthrough’s seed if it exists,

otherwise use value of -1 which changes with time.
Returns:The value of the seed.

Note

jericho.FrotzEnv.reset() must be called before the seed takes effect.

set_state(state)

Sets the game’s internal state.

Parameters:state (tuple) – Tuple of (ram, stack, pc, sp, fp, frame_count, rng) as obtained by jericho.FrotzEnv.get_state(). 
>>> from jericho import *
>>> env = FrotzEnv(rom_path)
>>> state = env.get_state()
>>> env.step('attack troll') # Oops!
'You swing and miss. The troll neatly removes your head.'
>>> env.set_state(state) # Whew, let's try something else
step(action)

Takes an action and returns the next state, reward, termination

Parameters:action (string) – Text command to send to the interpreter.
Returns:A tuple containing the game’s textual response to the action, the immediate reward, a boolean indicating whether the game is over, and a dictionary of info.
Return type:string, float, boolean, dictionary
victory()

Returns True if the game is over and the player has won.