textworld¶

Core¶

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

Bases: NameError

Thrown whenever some environment information EnvInfos.

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.

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.

admissible_commands¶

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

Type: bool

property basics¶

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

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

won¶

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

Type: bool

class textworld.core.Environment(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: 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

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¶

Enables/disables displaying the command when rendering.

Return type: bool

class textworld.core.GameState[source]¶: Bases: dict

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

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¶

Return type: bool

property unwrapped¶