GameMaker¶
- 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
- class textworld.generator.maker.GameMaker(options=None)[source]¶
Bases:
object
Stateful utility class for handcrafting text-based games.
- player¶
Entity representing the player.
- Type
- inventory¶
Entity representing the player’s inventory.
- Type
- nowhere¶
List of out-of-world entities (e.g. objects that would only appear later in a game).
- Type
List[WorldEntity]
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
exit1 (
WorldRoomExit
) – The exit of the first room to link.exit2 (
WorldRoomExit
) – The exit of the second room to link.
- Return type
- 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
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 aWorldRoom
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
- 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
- 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
- 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
- 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
- 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
- Returns
The resulting quest.
- 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
]
- 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_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
- 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 sourceWorldRoom
, the sourceWorldRoomExit
, the destinationWorldRoom
and the destinationWorldRoom
. 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
isNone
, it means there is no path leading to this exit yet.