GameMaker

exception textworld.generator.maker.ExitAlreadyUsedError[source]

Bases: ValueError

exception textworld.generator.maker.FailedConstraintsError(failed_constraints)[source]

Bases: ValueError

Thrown when a constraint has failed during generation.

Parameters:failed_constraints (List[Action]) – The constraints that have failed
exception textworld.generator.maker.MissingPlayerError[source]

Bases: ValueError

exception textworld.generator.maker.PlayerAlreadySetError[source]

Bases: ValueError

class textworld.generator.maker.GameMaker[source]

Bases: object

Stateful utility class for handcrafting text-based games.

player

WorldEntity – Entity representing the player.

inventory

WorldEntity – Player’s envi entity.

rooms

List[WorldRoom] – The rooms present in this world.

Creates an empty world, with a player and an empty inventory.

add_distractors(nb_distractors)[source]

Adds a number of distractors - random objects.

Parameters:nb_distractors (int) – The number of distractors to add.
Return type:None
add_fact(name, *entities)[source]

Adds a fact.

Parameters:
  • name (str) – The name of the new fact.
  • *entities – A list of WorldEntity as arguments to this fact.
Return type:

None

add_random_quest(max_length)[source]

Generates a random quest for the game.

Calling this method replaced all previous quests.

Parameters:max_length (int) – The maximum length of the quest to generate.
Return type:Quest
Returns:The generated quest.
build(validate=True)[source]

Create a Game instance given the defined facts.

Parameters:validate (optional) – If True, check if the game is valid, i.e. respects all constraints.
Returns:
Return type:Generated game.
compile(path)[source]

Compile this game.

Parameters:path (str) – Path where to save the generated game.
Returns:Path to the game file.
Return type:game_file
connect(exit1, exit2)[source]

Connect two rooms using their exits.

Parameters:
Return type:

WorldPath

Returns:

The path created by the link between two rooms, with no door.

findall(type)[source]

Gets all entities of the given type.

Parameters:type (str) – The type of entity to find.
Return type:List[WorldEntity]
Returns:All entities which match.
new(type, name=None, desc=None)[source]

Creates new entity given its type.

Parameters:
  • type (str) – The type of the entity.
  • name (Optional[str]) – The name of the entity.
  • desc (Optional[str]) – The description of the entity.
Return type:

Union[WorldEntity, WorldRoom]

Returns:

The newly created entity.

new_door(path, name=None, desc=None)[source]

Creates a new door and add it to the path.

Parameters:
  • path (WorldPath) – A path between two rooms where to add the door.
  • name (Optional[str]) – The name of the door. Default: generate one automatically.
  • desc (Optional[str]) – The description of the door.
Return type:

WorldEntity

Returns:

The newly created door.

new_event_using_commands(commands)[source]

Creates a new event using predefined text commands.

This launches a textworld.play session to execute provided commands.

Parameters:commands (List[str]) – Text commands.
Return type:Event
Returns:The resulting event.
new_fact(name, *entities)[source]

Create new fact.

Parameters:
  • name (str) – The name of the new fact.
  • *entities – A list of entities as arguments to the new fact.
Return type:

None

new_quest_using_commands(commands)[source]

Creates a new quest using predefined text commands.

This launches a textworld.play session to execute provided commands.

Parameters:commands (List[str]) – Text commands.
Return type:Quest
Returns:The resulting quest.
new_room(name=None, desc=None)[source]

Create new room entity.

Parameters:
  • name (Optional[str]) – The name of the room.
  • desc (Optional[str]) – The description of the room.
Return type:

WorldRoom

Returns:

The newly created room entity.

record_quest(ask_for_state=False)[source]

Defines the game’s quest by recording the commands.

This launches a textworld.play session.

Parameters:ask_for_state (bool) – If true, the user will be asked to specify which set of facts of the final state are should be true in order to consider the quest as completed.
Return type:Quest
Returns:The resulting quest.
render(interactive=False)[source]

Returns a visual representation of the world. :type interactive: bool :param interactive: opens an interactive session in the browser instead of returning a png. :return: :param save_screenshot: ONLY FOR WHEN interactive == False. Save screenshot in temp directory. :param filename: filename for screenshot

set_player(room)[source]

Place the player in room.

Parameters:room (WorldRoom) – The room the player will start in.

Notes

At the moment, the player can only be place once and cannot be moved once placed.

Raises:PlayerAlreadySetError – If the player has already been set.
Return type:None
set_quest_from_commands(commands, ask_for_state=False)[source]

Defines the game’s quest using predefined text commands.

This launches a textworld.play session.

Parameters:
  • commands (List[str]) – Text commands.
  • ask_for_state (bool) – If true, the user will be asked to specify which set of facts of the final state are should be true in order to consider the quest as completed.
Return type:

Quest

Returns:

The resulting quest.

test()[source]

Test the game being built.

This launches a textworld.play session.

Return type:None
validate()[source]

Check if the world is valid and can be compiled.

A world is valid is the player has been place in a room and all constraints (defined in the knowledge base) are respected.

Return type:bool
facts

All the facts associated to the current game state.

Return type:Iterable[Proposition]
state

Current state of the world.

Return type:State
class textworld.generator.maker.WorldEntity(var, name=None, desc=None)[source]

Bases: object

Represents an entity in the world.

Example of entities commonly found in text-based games: rooms, doors, items, etc.

Parameters:
  • var (Variable) – The underlying variable for the entity which is used by TextWorld’s inference engine.
  • name (Optional[str]) – The name of the entity that will be displayed in-game. Default: generate one according the variable’s type.
  • desc (Optional[str]) – The description of the entity that will be displayed when examining it in the game.
add(*entities)[source]

Add children to this entity.

Return type:None
add_fact(name, *entities)[source]

Adds a fact to this entity.

Parameters:
  • name (str) – The name of the new fact.
  • *entities – A list of entities as arguments to the new fact.
Return type:

None

add_property(name)[source]

Adds a property to this entity.

A property is a fact that only involves one entity. For instance, ‘closed(c)’, ‘open(c)’, and ‘locked(c)’ are all properties.

Parameters:name (str) – The name of the new property.
Return type:None
has_property(name)[source]

Determines if this object has a property with the given name.

Parameters:name of the property. (The) –

Example

>>> from textworld import GameMaker
>>> M = GameMaker()
>>> chest = M.new(type="c", name="chest")
>>> chest.has_property('closed')
False
>>> chest.add_property('closed')
>>> chest.has_property('closed')
True
Return type:bool
facts

All facts related to this entity (or its children content).

Return type:List[Proposition]
id

Unique name used internally.

Return type:str
properties

Properties of this object are things that refer to this object and this object alone. For instance, ‘closed’, ‘open’, and ‘locked’ are possible properties of ‘containers’.

Return type:List[Proposition]
type

Type of this entity.

Return type:str
class textworld.generator.maker.WorldPath(src, src_exit, dest, dest_exit, door=None)[source]

Bases: object

Represents a path between two WorldRoom objects.

A WorldPath encapsulates the source WorldRoom, the source WorldRoomExit, the destination WorldRoom and the destination WorldRoom. Optionally, a linking door can also be provided.

Parameters:
  • src (WorldRoom) – The source room.
  • src_exit (WorldRoomExit) – The exit of the source room.
  • dest (WorldRoom) – The destination room.
  • dest_exit (WorldRoomExit) – The exist of the destination room.
  • door (Optional[WorldEntity]) – The door between the two rooms, if any.
door

The entity representing the door or None if there is none.

Return type:Optional[WorldEntity]
facts

Facts related to this path.

Return type:List[Proposition]
Returns:The facts that make up this path.
class textworld.generator.maker.WorldRoom(*args, **kwargs)[source]

Bases: textworld.generator.maker.WorldEntity

Represents a room in the world.

Takes the same arguments as WorldEntity.

Then, creates a WorldRoomExit for each direction defined in graph_networks.DIRECTIONS, and sets exits to be a dict of those names to the newly created rooms. It then sets an attribute to each name.

Parameters:
  • args – The args to pass to WorldEntity
  • kwargs – The kwargs to pass to WorldEntity
class textworld.generator.maker.WorldRoomExit(src, direction, dest=None)[source]

Bases: object

Represents an exit from a Room.

These are used to connect WorldRoom`s to form `WorldPath`s. `WorldRoomExit`s are linked to each other through their :py:attr:`dest.

When dest is None, it means there is no path leading to this exit yet.

Parameters:
  • src (WorldRoom) – The WorldRoom that the exit is from.
  • direction (str) – The direction the exit is in: north, east, south, and west are common.
  • dest (Optional[WorldRoom]) – The WorldRoomExit that this exit links to (exits are linked to each other).
textworld.generator.maker.get_failing_constraints(state)[source]