# textworld.generator¶

exception textworld.generator.GenerationWarning[source]

Bases: UserWarning

exception textworld.generator.NoSuchQuestExistError[source]

Bases: NameError

textworld.generator.compile_game(game, options=None)[source]

Compile a game.

Parameters: game (Game) – Game object to compile. options (Optional[GameOptions]) – For customizing the game generation (see textworld.GameOptions for the list of available options). The path to compiled game.
textworld.generator.make_game(options)[source]

Make a game (map + objects + quest).

Parameters: options (GameOptions) – For customizing the game generation (see textworld.GameOptions for the list of available options). Game Generated game.
textworld.generator.make_game_with(world, quests=None, grammar=None)[source]
textworld.generator.make_grammar(options={}, rng=None)[source]
Return type: Grammar
textworld.generator.make_map(n_rooms, size=None, rng=None, possible_door_states=['open', 'closed', 'locked'])[source]

Make a map.

Parameters: n_rooms (int) – Number of rooms in the map. size (tuple of int) – Size (height, width) of the grid delimiting the map.
textworld.generator.make_quest(world, options=None)[source]
textworld.generator.make_small_map(n_rooms, rng=None, possible_door_states=['open', 'closed', 'locked'])[source]

Make a small map.

The map will contains one room that connects to all others.

Parameters: n_rooms (int) – Number of rooms in the map (maximum of 5 rooms). possible_door_states (list of str, optional) – Possible states doors can have.
textworld.generator.make_world(world_size, nb_objects=0, rngs=None)[source]

Make a world (map + objects).

Parameters: world_size (int) – Number of rooms in the world. nb_objects (int) – Number of objects in the world.
textworld.generator.make_world_with(rooms, rng=None)[source]

Make a world that contains the given rooms.

Parameters: rooms (list of textworld.logic.Variable) – Rooms in the map. Variables must have type ‘r’.
class textworld.generator.chaining.Chain(initial_state, nodes)[source]

Bases: object

An initial state and a chain of actions forming a quest.

nodes

The dependency tree of this quest.

initial_state

The initial state from which the actions start.

actions

The sequence of actions forming this quest.

class textworld.generator.chaining.ChainNode(action, depth, breadth, parent)[source]

Bases: object

A node in a chain of actions.

action

The action to perform at this step.

depth

This node’s depth in the dependency tree.

breadth

This node’s breadth in the dependency tree.

parent

This node’s parent in the dependency tree.

class textworld.generator.chaining.ChainingOptions[source]

Bases: object

Options for customizing the behaviour of chaining.

backward

Whether to run chaining forwards or backwards. Forward chaining produces a sequence of actions that start at the provided state, while backward chaining produces a sequence of actions that end up at the provided state.

min_length

The minimum length of the generated quests.

max_length

The maximum length of the generated quests.

min_depth

The minimum depth (length) of the generated independent subquests.

max_depth

The maximum depth (length) of the generated independent subquests.

min_breadth

The minimum breadth of the generated quests. When this is higher than 1, the generated quests will have multiple parallel subquests. In this case, min_depth and max_depth limit the length of these independent subquests, not the total size of the quest.

max_breadth

The maximum breadth of the generated quests.

subquests

Whether to also return incomplete quests, which could be extended without reaching the depth or breadth limits.

independent_chains

Whether to allow totally independent parallel chains.

create_variables

Whether new variables may be created during chaining.

fixed_mapping

A fixed mapping from placeholders to variables, for singletons.

rng

If provided, randomize the order of the quests using this random number generator.

logic

The rules of the game.

rules_per_depth

A list of lists of rules for restricting the allowed actions at certain depths.

restricted_types

A set of types that may not have new variables created.

check_action(state, action)[source]

Check if an action should be allowed in this state.

The default implementation disallows actions that would create new facts that don’t mention any new variables.

Parameters: state (State) – The current state. action (Action) – The action being applied. bool Whether that action should be allowed.
check_new_variable(state, type, count)[source]

Check if a new variable should be allowed to be created in this state.

Parameters: state (State) – The current state. type (str) – The type of variable being created. count (int) – The total number of variables of that type. bool Whether that variable should be allowed to be created.
copy()[source]
Return type: ChainingOptions
get_rules(depth)[source]

Get the relevant rules for this depth.

Parameters: depth (int) – The current depth in the chain. Iterable[Rule] The rules that may be applied at this depth in the chain.
fixed_mapping
Return type: GameLogic
logic
Return type: GameLogic
textworld.generator.chaining.get_chains(state, options)[source]

Generates chains of actions (quests) starting from or ending at the given state.

Parameters: state (State) – The initial state for chaining. options (ChainingOptions) – Options to configure chaining behaviour. Iterable[Chain] All possible quests according to the constraints.
textworld.generator.chaining.sample_quest(state, options)[source]

Samples a single chain of actions (a quest) starting from or ending at the given state.

Parameters: state (State) – The initial state for chaining. options (ChainingOptions) – Options to configure chaining behaviour. Set options.rng to sample a random quest. Optional[Chain] A single possible quest.
class textworld.generator.dependency_tree.DependencyTree(element_type=<class 'textworld.generator.dependency_tree.DependencyTreeElement'>, trees=[])[source]

Bases: object

copy()[source]
Return type: DependencyTree
push(value, allow_multi_root=False)[source]

Add a value to this dependency tree.

Adding a value already present in the tree does not modify the tree.

Parameters: value (Any) – value to add. allow_multi_root (bool) – if True, allow the value to spawn an additional root if needed. bool
remove(value)[source]

Remove all leaves having the given value.

The value to remove needs to belong to at least one leaf in this tree. Otherwise, the tree remains unchanged.

Parameters: value (Any) – value to remove from the tree. bool Whether the tree has changed or not.
empty
Return type: bool
leaves_elements
Return type: List[DependencyTreeElement]
leaves_values
Return type: List[Any]
values
Return type: List[Any]
class textworld.generator.dependency_tree.DependencyTreeElement(value)[source]

Bases: object

Representation of an element in the dependency tree.

The notion of dependency and ordering should be defined for these elements.

Subclasses should override depends_on, __lt__ and __str__ accordingly.

depends_on(other)[source]

Check whether this element depends on the other.

Return type: bool
is_distinct_from(others)[source]

Check whether this element is distinct from others.

Return type: bool
class textworld.generator.logger.GameLogger(group_actions=True)[source]

Bases: object

aggregate(other)[source]
collect(game)[source]
display_stats()[source]
static load(filename)[source]
save(filename)[source]
stats()[source]

User interface using urwid

class textworld.generator.user_query.UrwidQuestQuerier(checkboxes)[source]

Bases: urwid.wimp.PopUpLauncher

UI class for query_for_important_quests

cancel_button_clicked(_)[source]
confirm_button_clicked(_)[source]
create_pop_up()[source]

Subclass must override this method and return a widget to be used for the pop-up. This method is called once each time the pop-up is opened.

get_pop_up_parameters()[source]

Subclass must override this method and have it return a dict, eg:

{‘left’:0, ‘top’:1, ‘overlay_width’:30, ‘overlay_height’:4}

This method is called each time this widget is rendered.

class textworld.generator.user_query.UrwidWarningDialog(msg_text)[source]

Bases: urwid.widget.WidgetWrap

Generic message dialog with no text, suitable for warnings.

signals = ['close']
textworld.generator.user_query.query_for_important_facts(actions, facts=None, varinfos=None)[source]

Queries the user, asking which facts are important.

Parameters: actions (List[Action]) – Actions used to determine or extract relevant facts. facts (Optional[List[Proposition]]) – All facts existing at the end of the game. Optional[List[Proposition]] The list of facts that are required to win; or None if facts was not provided; or None if the user cancels.
exception textworld.generator.vtypes.NotEnoughNounsError[source]

Bases: NameError

class textworld.generator.vtypes.VariableType(type, name, parent=None)[source]

Bases: object

classmethod deserialize(data)[source]
Return type: VariableType
classmethod parse(expr)[source]

Parse a variable type expression.

Parameters: expr (str) – The string to parse, in the form name: type -> parent1 & parent2 or name: type for root node. VariableType
serialize()[source]
Return type: str
class textworld.generator.vtypes.VariableTypeTree(vtypes)[source]

Bases: object

Manages hierarchy of types defined in ./grammars/variables.txt. Used for extending the rules.

count(state)[source]

Counts how many objects there are of each type.

descendants(vtype)[source]

Given a variable type, return all possible descendants.

classmethod deserialize(data)[source]
Return type: VariableTypeTree
get_ancestors(vtype)[source]

List all ancestors of a type where the closest ancetors are first.

get_description(vtype)[source]
is_constant(vtype)[source]
is_descendant_of(child, parents)[source]

Return if child is a descendant of parent

classmethod load(path)[source]

sample(parent_type, rng, exceptions=[], include_parent=True, probs=None)[source]

Sample an object type given the parent’s type.

serialize()[source]
Return type: List[~T]
CHEST = 'c'
CLASS_HOLDER = ['c', 's']
SUPPORTER = 's'
textworld.generator.vtypes.get_new(type, types_counts, max_types_counts=None)[source]

Get the next available id for a given type.

textworld.generator.vtypes.parse_variable_types(content)[source]

Parse a list VariableType expressions.