textworld.gym

textworld.gym.utils.register_game(gamefile, request_infos=None, batch_size=None, auto_reset=False, max_episode_steps=50, asynchronous=True, action_space=None, observation_space=None, name='', **kwargs)[source]

Make an environment for a particular game.

Parameters
  • gamefile (str) – Path for the TextWorld game (*.ulx|*.z[1-8]).

  • request_infos (Optional[EnvInfos]) –

    For customizing the information returned by this environment (see textworld.EnvInfos for the list of available information).

    Warning

    Only supported for TextWorld games (i.e., with a corresponding *.json file).

  • batch_size (Optional[int]) –

    If provided, it indicates the number of games to play at the same time. By default, a single game is played at once.

    Warning

    When batch_size is provided (even for batch_size=1), env.step expects a list of commands as input and outputs a list of states. env.reset also outputs a list of states.

  • auto_reset (bool) – If True, each game independently resets once it is done (i.e., reset happens on the next env.step call). Otherwise, once a game is done, subsequent calls to env.step won’t have any effects.

  • max_episode_steps (int) – Number of steps allocated to play each game. Once exhausted, the game is done.

  • asynchronous (bool) – If True, games in the batch are played in parallel. Only when batch size is greater than one.

  • action_space (Optional[Space]) – The action space be used with OpenAI baselines. (see textworld.gym.spaces.Word).

  • observation_space (Optional[Space]) – The observation space be used with OpenAI baselines (see textworld.gym.spaces.Word).

  • name (str) – Name for the new environment, i.e. “tw-{name}-v0”. By default, the returned env_id is “tw-v0”.

Return type

str

Returns

The corresponding gym-compatible env_id to use.

Example

>>> from textworld.generator import make_game, compile_game
>>> options = textworld.GameOptions()
>>> options.seeds = 1234
>>> game = make_game(options)
>>> game.extras["more"] = "This is extra information."
>>> gamefile = compile_game(game)

>>> import gym
>>> import textworld.gym
>>> from textworld import EnvInfos
>>> request_infos = EnvInfos(description=True, inventory=True, extras=["more"])
>>> env_id = textworld.gym.register_game(gamefile, request_infos)
>>> env = gym.make(env_id)
>>> ob, infos = env.reset()
>>> print(infos["extra.more"])
This is extra information.
textworld.gym.utils.register_games(gamefiles, request_infos=None, batch_size=None, auto_reset=False, max_episode_steps=50, asynchronous=True, action_space=None, observation_space=None, name='', **kwargs)[source]

Make an environment that will cycle through a list of games.

Parameters
  • gamefiles (List[str]) – Paths for the TextWorld games (*.ulx|*.z[1-8]).

  • request_infos (Optional[EnvInfos]) –

    For customizing the information returned by this environment (see textworld.EnvInfos for the list of available information).

    Warning

    Only supported for TextWorld games (i.e., with a corresponding *.json file).

  • batch_size (Optional[int]) –

    If provided, it indicates the number of games to play at the same time. By default, a single game is played at once.

    Warning

    When batch_size is provided (even for batch_size=1), env.step expects a list of commands as input and outputs a list of states. env.reset also outputs a list of states.

  • auto_reset (bool) – If True, each game independently resets once it is done (i.e., reset happens on the next env.step call). Otherwise, once a game is done, subsequent calls to env.step won’t have any effects.

  • max_episode_steps (int) – Number of steps allocated to play each game. Once exhausted, the game is done.

  • asynchronous (bool) – If True, games in the batch are played in parallel. Only when batch size is greater than one.

  • action_space (Optional[Space]) – The action space be used with OpenAI baselines. (see textworld.gym.spaces.Word).

  • observation_space (Optional[Space]) – The observation space be used with OpenAI baselines (see textworld.gym.spaces.Word).

  • name (str) – Name for the new environment, i.e. “tw-{name}-v0”. By default, the returned env_id is “tw-v0”.

Return type

str

Returns

The corresponding gym-compatible env_id to use.

Example

>>> from textworld.generator import make_game, compile_game
>>> options = textworld.GameOptions()
>>> options.seeds = 1234
>>> game = make_game(options)
>>> game.extras["more"] = "This is extra information."
>>> gamefile = compile_game(game)

>>> import gym
>>> import textworld.gym
>>> from textworld import EnvInfos
>>> request_infos = EnvInfos(description=True, inventory=True, extras=["more"])
>>> env_id = textworld.gym.register_games([gamefile], request_infos)
>>> env = gym.make(env_id)
>>> ob, infos = env.reset()
>>> print(infos["extra.more"])
This is extra information.