# textworld¶

## Core¶

exception textworld.core.GameNotRunningError[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. str 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. None
reset(env)[source]

Let the agent set some environment’s flags.

Parameters: env (Environment) – TextWorld environment. None
class textworld.core.Environment[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.

activate_state_tracking()[source]

Enables state tracking.

Return type: None
close()[source]

Ends the game.

Return type: None
compute_intermediate_reward()[source]

Enables intermediate reward computation.

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

Renders the current state of the game.

Parameters: mode (str) – The mode to use for rendering. Optional[str]
reset()[source]

Starts game from the beginning.

Return type: GameState 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. Tuple[GameState, float, bool] 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.
display_command_during_render

Enables/disables displaying the command when rendering.

Return type: bool
metadata

For instance, it can contain the supported rendering modes 'render.modes': {'human', 'text', 'ansi'}.

Return type: Mapping[~KT, +VT_co]
class textworld.core.GameState(env=None)[source]

Bases: object

Representation of the state of a text-based game.

This object can be used to get additional information about the current state of the game.

Create a game state.

Parameters: env (Optional[Environment]) – Environment that can be used to fetch additional information.
init(output)[source]

Initializes the game state from intro text.

Parameters: output (str) – Text displayed when the game starts. None
update(command, output)[source]

Creates a new game state with the new information.

Parameters: command (str) – Command sent to the game’s interpreter. output (str) – Response from the game’s interpreter.
Returns
The new state of the game.
Return type: GameState
command

Last command sent to the interpreter.

Return type: str
description

Description at the current location.

It’s usually the output of the “look” command.

Return type: str
feedback

Interpreter’s response after issuing last command.

Return type: str
game_ended

Whether the game is finished or not.

Return type: bool
has_lost

Whether the player has lost the game or not.

Return type: bool
has_won

Whether the player has won the game or not.

Return type: bool
inventory

Player’s inventory.

It’s usually the output of the “inventory” command.

Return type: str
location

Name of the current location.

Return type: str
max_score

Max score for this game.

It’s usually the output of the “score” command.

Return type: float
nb_moves

Number of actions perfomed up until now.

Return type: int
score

Current score.

It’s usually the output of the “score” command.

Return type: float
class textworld.core.Wrapper(env)[source]

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 (Environment) – environment to wrap.
activate_state_tracking()[source]

Enables state tracking.

Return type: None
close()[source]

Ends the game.

Return type: None
compute_intermediate_reward()[source]

Enables intermediate reward computation.

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

Renders the current state of the game.

Parameters: mode (str) – The mode to use for rendering. Optional[Any]
reset()[source]

Starts game from the beginning.

Return type: GameState Initial state of the game.
seed(seed=None)[source]

Sets the seed for the random number generator.

Return type: List[int]
step(command)[source]

Performs a given command.

Parameters: command (str) – Text command to send to the interpreter. Tuple[GameState, float, bool] 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.
display_command_during_render

Enables/disables displaying the command when rendering.

Return type: bool
metadata

For instance, it can contain the supported rendering modes 'render.modes': {'human', 'text', 'ansi'}.
Return type: Mapping[~KT, +VT_co]