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

exception textworld.generator.maker.QuestError[source]

Bases: ValueError

class textworld.generator.maker.GameMaker(options=None)[source]

Bases: object

Stateful utility class for handcrafting text-based games.

player

Entity representing the player.

Type:

WorldEntity

inventory

Entity representing the player’s inventory.

Type:

WorldEntity

nowhere

List of out-of-world entities (e.g. objects that would only appear later in a game).

Type:

List[WorldEntity]

rooms

The rooms present in this world.

Type:

List[WorldRoom]

paths

The connections between the rooms.

Type:

List[WorldPath]

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

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

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.

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.

find_by_name(name)[source]

Find an entity using its name.

Return type:

Optional[WorldEntity]

find_path(room1, room2)[source]

Get the path between two rooms, if it exists.

Parameters:
Return type:

Optional[WorldEntity]

Returns:

The matching path path, if it exists.

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.

generate_distractors(nb_distractors)[source]

Generates a number of distractors - random objects.

Parameters:

nb_distractors (int) – The number of distractors to game will contain.

Return type:

None

generate_random_quests(nb_quests=1, length=1, breadth=1)[source]

Generates random quests for the game.

Warning

This method overrides any previous quests the game had.

Parameters:
  • nb_quests – Number of parallel quests, i.e. not sharing a common goal.

  • length (int) – Number of actions that need to be performed to complete the game.

  • breadth (int) – Number of subquests per independent quest. It controls how nonlinear a quest can be (1: linear).

Return type:

List[Quest]

Returns:

The generated quests.

import_graph(G)[source]

Convert Graph object to a list of Proposition.

Parameters:

G (Graph) – Graph defining the structure of the world.

Return type:

List[WorldRoom]

move(entity, new_location)[source]

Move an entity to a new location.

Parameters:
Return type:

None

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()[source]

Defines the game’s quest by recording the commands.

This launches a textworld.play session.

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)[source]

Defines the game’s quest using predefined text commands.

This launches a textworld.play session.

Parameters:

commands (List[str]) – Text commands.

Return type:

Quest

Returns:

The resulting quest.

set_walkthrough(commands)[source]
test(walkthrough=False)[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

property facts: Iterable[Proposition]

All the facts associated to the current game state.

Return type:

Iterable[Proposition]

property state: State

Current state of the world.

Return type:

State

class textworld.generator.maker.WorldEntity(var, name=None, desc=None, kb=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:

property. (The name of 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

remove(*entities)[source]
remove_fact(name, *entities)[source]
Return type:

None

remove_property(name)[source]
Return type:

None

property facts: List[Proposition]

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

Return type:

List[Proposition]

property id: str

Unique name used internally.

Return type:

str

property name: str

Name of this entity.

Return type:

str

property properties: List[Proposition]

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]

property type: str

Type of this entity.

Return type:

str

class textworld.generator.maker.WorldPath(src, src_exit, dest, dest_exit, door=None, kb=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.

property door: Optional[WorldEntity]

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

Return type:

Optional[WorldEntity]

property facts: List[Proposition]

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

east
north
south
west
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, kb=None)[source]