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_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.

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.

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

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

property facts

All the facts associated to the current game state.

Return type

Iterable[Proposition]

property 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

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

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

None

remove_property(name)[source]
Return type

None

property facts

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

Return type

List[Proposition]

property id

Unique name used internally.

Return type

str

property name

Name of this entity.

Return type

str

property 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]

property type

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

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

Return type

Optional[WorldEntity]

property 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

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]