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

exit1 (WorldRoomExit) – The exit of the first room to link.
exit2 (WorldRoomExit) – The exit of the second room to link.

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

room1 (WorldRoom) – One of the two rooms.
room2 (WorldRoom) – The other room.

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

entity (WorldEntity) – Entity to move.
new_location (WorldEntity) – Where to move the entity.

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.

If the type is 'r', then a WorldRoom object is returned.
Otherwise, a WorldEntity is returned.

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¶

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