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(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

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