Envs

class textworld.gym.envs.textworld_games_env.TextworldGamesEnv(game_files, request_infos=None, action_space=None, observation_space=None)[source]

Bases: gym.core.Env

Environment for playing TextWorld games.

Each time TextworldGamesEnv.reset() is called, a new game from the pool starts. Each game of the pool is guaranteed to be played exactly once before a same game is played for a second time.

Parameters:
  • game_files (List[str]) – Paths of every TextWorld game composing the pool (.ulx + .json).
  • request_infos (Optional[EnvInfos]) – For customizing the information returned by this environment (see textworld.EnvInfos for the list of available information).
  • action_space (Optional[Space]) – The action space of this TextWorld environment. By default, a textworld.gym.spaces.Word instance is used with a max_length of 8 and a vocabulary extracted from the TextWorld game.
  • observation_space (Optional[Space]) – The observation space of this TextWorld environment. By default, a textworld.gym.spaces.Word instance is used with a max_length of 200 and a vocabulary extracted from the TextWorld game.
close()[source]

Close this environment.

Return type:None
render(mode='human')[source]

Renders the current state of this environment.

The rendering is composed of the previous text command (if there’s one) and the text describing the current observation.

Parameters:mode (str) –

Controls where and how the text is rendered. Supported modes are:

  • human: Display text to the current display or terminal and return nothing.
  • ansi: Return a StringIO containing a terminal-style text representation. The text can include newlines and ANSI escape sequences (e.g. for colors).
  • text: Return a string (str) containing the text without any ANSI escape sequences.
Return type:Union[StringIO, str, None]
Returns:Depending on the mode, this method returns either nothing, a string, or a StringIO object.
reset()[source]

Resets the text-based environment.

Resetting this environment means starting the next game in the pool.

Return type:Tuple[str, Dict[str, Any]]
Returns:A tuple (observation, info) where
  • observation: text observed in the initial state;
  • infos: additional information as requested.
seed(seed=None)[source]

Set the seed for this environment’s random generator(s).

This environment use a random generator to shuffle the order in which the games are played.

Parameters:seed (Optional[int]) – Number that will be used to seed the random generators.
Return type:List[int]
Returns:All the seeds used to set this environment’s random generator(s).
skip(nb_games=1)[source]

Skip games.

Parameters:nb_games (int) – Number of games to skip.
Return type:None
step(command)[source]

Runs a command in the text-based environment.

Parameters:command – Text command to send to the game interpreter.
Return type:Tuple[str, Dict[str, Any]]
Returns:A tuple (observation, score, done, info) where
  • observation: text observed in the new state;
  • score: total number of points accumulated so far;
  • done: whether the game is finished or not;
  • infos: additional information as requested.
metadata = {'render.modes': ['human', 'ansi', 'text']}
class textworld.gym.envs.batch_env.BatchEnv(env_id, batch_size)[source]

Bases: gym.core.Env

Environment to run multiple games independently.

Parameters:
  • env_id (list of str or str) – Environment IDs that will compose a batch. If only one env_id is provided, it will be repeated batch_size times.
  • batch_size (int) – Number of independent environments to run.
close()[source]

Override _close in your subclass to perform any necessary cleanup.

Environments will automatically close() themselves when garbage collected or when the program exits.

render(mode='human')[source]

Renders the environment.

The set of supported modes varies per environment. (And some environments do not support rendering at all.) By convention, if mode is:

  • human: render to the current display or terminal and return nothing. Usually for human consumption.
  • rgb_array: Return an numpy.ndarray with shape (x, y, 3), representing RGB values for an x-by-y pixel image, suitable for turning into a video.
  • ansi: Return a string (str) or StringIO.StringIO containing a terminal-style text representation. The text can include newlines and ANSI escape sequences (e.g. for colors).

Note

Make sure that your class’s metadata ‘render.modes’ key includes
the list of supported modes. It’s recommended to call super() in implementations to use the functionality of this method.
Parameters:
  • mode (str) – the mode to render with
  • close (bool) – close all open renderings

Example:

class MyEnv(Env):

metadata = {‘render.modes’: [‘human’, ‘rgb_array’]}

def render(self, mode=’human’):
if mode == ‘rgb_array’:
return np.array(…) # return RGB frame suitable for video
elif mode is ‘human’:
… # pop up a window and render
else:
super(MyEnv, self).render(mode=mode) # just raise an exception
reset()[source]

Reset all environments of the batch.

Returns:Text observations, i.e. command’s feedback. infos: Information requested when creating the environments.
Return type:obs
seed(seed=None)[source]

Sets the seed for this env’s random number generator(s).

Note

Some environments use multiple pseudorandom number generators. We want to capture all such seeds used in order to ensure that there aren’t accidental correlations between multiple generators.

Returns:
Returns the list of seeds used in this env’s random
number generators. The first value in the list should be the “main” seed, or the value which a reproducer should pass to ‘seed’. Often, the main seed equals the provided ‘seed’, but this won’t be true if seed=None, for example.
Return type:list<bigint>
skip(ngames=1)[source]
step(actions)[source]

Perform one action per environment of the batch.

Returns:Text observations, i.e. command’s feedback. reward: Current game score. done: Whether the game is over or not. infos: Information requested when creating the environments.
Return type:obs
class textworld.gym.envs.batch_env.ParallelBatchEnv(env_id, batch_size)[source]

Bases: gym.core.Env

Environment to run multiple games in parallel.

Parameters:
  • env_id (list of str or str) – Environment IDs that will compose a batch. If only one env_id is provided, it will be repeated batch_size times.
  • batch_size (int) – Number of environment to run in parallel.
close()[source]

Override _close in your subclass to perform any necessary cleanup.

Environments will automatically close() themselves when garbage collected or when the program exits.

render(mode='human')[source]

Renders the environment.

The set of supported modes varies per environment. (And some environments do not support rendering at all.) By convention, if mode is:

  • human: render to the current display or terminal and return nothing. Usually for human consumption.
  • rgb_array: Return an numpy.ndarray with shape (x, y, 3), representing RGB values for an x-by-y pixel image, suitable for turning into a video.
  • ansi: Return a string (str) or StringIO.StringIO containing a terminal-style text representation. The text can include newlines and ANSI escape sequences (e.g. for colors).

Note

Make sure that your class’s metadata ‘render.modes’ key includes
the list of supported modes. It’s recommended to call super() in implementations to use the functionality of this method.
Parameters:
  • mode (str) – the mode to render with
  • close (bool) – close all open renderings

Example:

class MyEnv(Env):

metadata = {‘render.modes’: [‘human’, ‘rgb_array’]}

def render(self, mode=’human’):
if mode == ‘rgb_array’:
return np.array(…) # return RGB frame suitable for video
elif mode is ‘human’:
… # pop up a window and render
else:
super(MyEnv, self).render(mode=mode) # just raise an exception
reset()[source]

Reset all environments of the batch.

Returns:Text observations, i.e. command’s feedback. infos: Information requested when creating the environments.
Return type:obs
seed(seed=None)[source]

Sets the seed for this env’s random number generator(s).

Note

Some environments use multiple pseudorandom number generators. We want to capture all such seeds used in order to ensure that there aren’t accidental correlations between multiple generators.

Returns:
Returns the list of seeds used in this env’s random
number generators. The first value in the list should be the “main” seed, or the value which a reproducer should pass to ‘seed’. Often, the main seed equals the provided ‘seed’, but this won’t be true if seed=None, for example.
Return type:list<bigint>
skip(ngames=1)[source]
step(actions)[source]

Perform one action per environment of the batch.

Returns:Text observations, i.e. command’s feedback. reward: Current game score. done: Whether the game is over or not. infos: Information requested when creating the environments.
Return type:obs
textworld.gym.envs.utils.shuffled_cycle(iterable, rng, nb_loops=-1)[source]

Yield each element of iterable one by one, then shuffle the elements and start yielding from the start. Stop after nb_loops loops.

Parameters:
  • iterable (Iterable[Any]) – Iterable containing the elements to yield.
  • rng (RandomState) – Random generator used to shuffle the elements after each loop.
  • nb_loops (int) – Number of times to go through all the elements. If set to -1, loop an infinite number of times.
Return type:

Iterable[Any]