textworld

Core

exception textworld.core.EnvInfoMissingError(requester, info)[source]

Bases: NameError

Thrown whenever some environment information EnvInfos.

exception textworld.core.GameNotRunningError(msg='')[source]

Bases: RuntimeError

Error when game is not running (either has terminiated or crashed).

class textworld.core.Agent[source]

Bases: object

Interface for any agent that want to play a text-based game.

act(game_state, reward, done)[source]

Acts upon the current game state.

Parameters:
  • game_state (GameState) – Current game state.

  • reward (float) – Accumulated reward up until now.

  • done (bool) – Whether the game is finished.

Return type:

str

Returns:

Text command to be performed in this current state.

finish(game_state, reward, done)[source]

Let the agent know the game has finished.

Parameters:
  • game_state (GameState) – Game state at the moment the game finished.

  • reward (float) – Accumulated reward up until now.

  • done (bool) – Whether the game has finished normally or not. If False, it means the agent’s used up all of its actions.

Return type:

None

reset(env)[source]

Let the agent set some environment’s flags.

Parameters:

env (Environment) – TextWorld environment.

Return type:

None

property wrappers
class textworld.core.EnvInfos(**kwargs)[source]

Bases: object

Customizing what information will be returned by an environment.

Information can be requested by setting one or more attributes to True. The attribute extras should be a list of strings corresponding to keys in the metadata dictionary of TextWorld generated games.

copy()[source]
admissible_commands

All commands relevant to the current state. This information changes from one step to another.

Type:

bool

property basics: Iterable[str]

Information requested excluding the extras.

Return type:

Iterable[str]

command_templates

Templates for commands understood by the the game. This information doesn’t change from one step to another.

Type:

bool

description

Text description of the current room, i.e. output of the look command. This information changes from one step to another.

Type:

bool

entities

Names of all entities in the game. This information doesn’t change from one step to another.

Type:

bool

extras

Names of extra information which are game specific.

Type:

List[str]

facts

All the facts that are currently true about the world. This information changes from one step to another.

Type:

bool

fail_facts

Mutually exclusive sets of failing facts for each quest. This information doesn’t change from one step to another.

Type:

bool

feedback

Text observation produced by the game in response to previous command. This information changes from one step to another.

Type:

bool

game

Current game in its serialized form. Use with textworld.Game.deserialize.

Type:

bool

intermediate_reward

Reward (proxy) indicating if the player is making progress. This information changes from one step to another.

Type:

bool

inventory

Text listing of the player’s inventory, i.e. output of the inventory command. This information changes from one step to another.

Type:

bool

last_action

The last action performed where None means it was not a valid action. This information changes from one step to another.

Type:

bool

last_command

The last command performed where None means it was not a valid command. This information changes from one step to another.

Type:

bool

location

Name of the player’s current location. This information changes from one step to another.

Type:

bool

lost

Whether the player lost the game. This information changes from one step to another.

Type:

bool

max_score

Maximum reachable score of the game. This information doesn’t change from one step to another.

Type:

bool

moves

Number of moves done so far in the game. This information changes from one step to another.

Type:

bool

objective

Objective of the game described in text. This information doesn’t change from one step to another.

Type:

bool

policy_commands

Sequence of commands leading to a winning state. This information changes from one step to another.

Type:

bool

score

Current score of the game. This information changes from one step to another.

Type:

bool

verbs

Verbs understood by the the game. This information doesn’t change from one step to another.

Type:

bool

win_facts

Mutually exclusive sets of winning facts for each quest. This information doesn’t change from one step to another.

Type:

bool

won

Whether the player won the game. This information changes from one step to another.

Type:

bool

class textworld.core.Environment(request_infos=None)[source]

Bases: object

Class allowing to interact with the game’s interpreter.

The role of an Environment is to handle the communication between user code and the backend interpreter that manages the text-based game. The overall Environment structure is highly inspired by OpenAI’s gym.

Example

Here’s a minimal example of how to interact with an Environment

>>> import textworld
>>> options = textworld.GameOptions()
>>> options.seeds = 1234
>>> options.nb_objects = 5
>>> options.quest_length = 2
>>> game_file, _ = textworld.make(options, path='./')  # Generate a random game.
>>> env = textworld.start(game_file)  # Load the game.
>>> game_state = env.reset()  # Start a new game.
>>> env.render()
I hope you're ready to go into rooms and interact with objects, because you've
just entered TextWorld! Here is how to play! First thing I need you to do is to
ensure that the type G chest is open. And then, pick up the keycard from the
type G chest inside the attic. Got that? Good!

-= Attic =-
You arrive in an attic. A normal kind of place. You begin to take stock of
what's in the room.

You make out a type G chest. You can see a TextWorld style locker. The TextWorld
style locker contains a frisbee and a sock.



There is a TextWorld style key on the floor.
>>> command = "take key"  # Command to send to the game.
>>> game_state, reward, done = env.step(command)
>>> env.render()
(the TextWorld style key)
You pick up the TextWorld style key from the ground.
Parameters:

request_infos (Optional[EnvInfos]) – Information to be included in the game state. By default, only the game’s narrative is included.

close()[source]

Ends the game.

Return type:

None

copy()[source]

Return a copy of this environment at the same state.

Return type:

Environment

Returns:

A copy of this environment at the same state.

load(path)[source]

Loads a new text-based game.

Parameters:

path (str) – Path to the game file to load.

Return type:

None

render(mode='human')[source]

Renders the current state of the game.

Parameters:

mode (str) – The mode to use for rendering.

Return type:

Optional[str]

reset()[source]

Starts game from the beginning.

Return type:

GameState

Returns:

Initial state of the game.

seed(seed=None)[source]

Sets the seed for the random number generator.

Return type:

None

step(command)[source]

Performs a given command.

Parameters:

command (str) – Text command to send to the interpreter.

Return type:

Tuple[GameState, float, bool]

Returns:

A tuple containing the new game state, a reward for performing that command and reaching this new state, and whether the game is finished or not.

property display_command_during_render: bool

Enables/disables displaying the command when rendering.

Return type:

bool

class textworld.core.GameState[source]

Bases: dict

copy()[source]

Returns a deepcopy of this game state.

Return type:

GameState

class textworld.core.Wrapper(env=None)[source]

Bases: object

Special environment that wraps others to provide new functionalities.

Special environment that wraps other Environment objects to provide new functionalities (e.g. transcript recording, viewer, etc).

Parameters:

env (Optional[Environment]) – environment to wrap.

close()[source]
Return type:

None

copy()[source]
Return type:

Wrapper

load(path)[source]
Return type:

None

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

Optional[Any]

reset()[source]
Return type:

GameState

seed(seed=None)[source]
Return type:

List[int]

step(command)[source]
Return type:

Tuple[GameState, float, bool]

property display_command_during_render: bool
Return type:

bool

property unwrapped