Game¶

exception textworld.generator.game.UnderspecifiedEventError[source]¶: Bases: NameError

exception textworld.generator.game.UnderspecifiedQuestError[source]¶: Bases: NameError

class textworld.generator.game.ActionDependencyTree(*args, kb=None, **kwargs)[source]¶

Bases: textworld.generator.dependency_tree.DependencyTree

copy()[source]¶

Return type: ActionDependencyTree

flatten()[source]¶

Generates a flatten representation of this dependency tree.

Actions are greedily yielded by iteratively popping leaves from the dependency tree.

Return type: Iterable[Action]

remove(action)[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 – value to remove from the tree.
Return type: Tuple[bool, Optional[Action]]
Returns: Whether the tree has changed or not.

class textworld.generator.game.ActionDependencyTreeElement(value)[source]¶

Bases: textworld.generator.dependency_tree.DependencyTreeElement

Representation of an Action in the dependency tree.

The notion of dependency and ordering is defined as follows:

action1 depends on action2 if action1 needs the propositions added by action2;
action1 should be performed before action2 if action2 removes propositions needed by action1.

depends_on(other)[source]¶

Check whether this action depends on the other.

Action1 depends on action2 when the intersection between the propositions added by action2 and the preconditions of the action1 is not empty, i.e. action1 needs the propositions added by action2.

Return type: bool

is_distinct_from(others)[source]¶

Check whether this element is distinct from others.

We check if self.action has any additional information that others actions don’t have. This helps us to identify whether a group of nodes in the dependency tree already contain all the needed information that self.action would bring.

Return type: bool

property action¶

Return type: Action

class textworld.generator.game.EntityInfo(id, type)[source]¶

Bases: object

Additional information about entities in the game.

classmethod deserialize(data)[source]¶

Creates a EntityInfo from serialized data.

Parameters: data (Mapping) – Serialized data with the needed information to build a EntityInfo object.
Return type: EntityInfo

serialize()[source]¶

Serialize this object.

Results:: EntityInfo’s data serialized to be JSON compatible

Return type: Mapping

adj¶

The adjective (i.e. descriptive) part of the name, if available.

Type: str

definite¶

The definite article to use for this entity.

Type: str

desc¶

Text description displayed when examining this entity in the game.

Type: str

id¶

Unique name for this entity. It is used when generating

Type: str

indefinite¶

The indefinite article to use for this entity.

Type: str

name¶

The name that will be displayed in-game to identify this entity.

Type: str

noun¶

The noun part of the name, if available.

Type: str

room_type¶

Type of the room this entity belongs to. It used to influence its name during text generation.

Type: str

synonyms¶

Alternative names that can be used to refer to this entity.

Type: List[str]

type¶

The type of this entity.

Type: str

class textworld.generator.game.Event(actions=(), conditions=(), commands=())[source]¶

Bases: object

Event happening in TextWorld.

An event gets triggered when its set of conditions become all statisfied.

actions¶: Actions to be performed to trigger this event

commands¶: Human readable version of the actions.

condition¶: textworld.logic.Action that can only be applied when all conditions are statisfied.

Parameters

actions (Iterable[Action]) – The actions to be performed to trigger this event. If an empty list, then conditions must be provided.
conditions (Iterable[Proposition]) – Set of propositions which need to be all true in order for this event to get triggered.
commands (Iterable[str]) – Human readable version of the actions.

copy()[source]¶

Copy this event.

Return type: Event

classmethod deserialize(data)[source]¶

Creates an Event from serialized data.

Parameters: data (Mapping) – Serialized data with the needed information to build a Event object.
Return type: Event

is_triggering(state)[source]¶

Check if this event would be triggered in a given state.

Return type: bool

serialize()[source]¶

Serialize this event.

Results:: Event’s data serialized to be JSON compatible.

Return type: Mapping

set_conditions(conditions)[source]¶

Set the triggering conditions for this event.

Parameters: conditions (Iterable[Proposition]) – Set of propositions which need to be all true in order for this event to get triggered.
Return type: Action
Returns: Action that can only be applied when all conditions are statisfied.

property actions

Return type: Iterable[Action]

property commands

Return type: Iterable[str]

class textworld.generator.game.EventProgression(event, kb)[source]¶

Bases: object

EventProgression monitors a particular event.

Internally, the event is represented as a dependency tree of relevant actions to be performed.

Parameters: quest – The quest to keep track of its completion.

compress_policy(state)[source]¶

Compress the policy given a game state.

Parameters: state (State) – Current game state.
Return type: bool
Returns: Whether the policy was compressed or not.

update(action=None, state=None)[source]¶

Update event progression given available information.

Parameters

action (Optional[Action]) – Action potentially affecting the event progression.
state (Optional[State]) – Current game state.

Return type

None

property done¶

Check if the quest is done (i.e. triggered or untriggerable).

Return type: bool

property triggered¶

Check whether the event has been triggered.

Return type: bool

property triggering_policy¶

Actions to be performed in order to trigger the event.

Return type: List[Action]

property untriggerable¶

Check whether the event is in an untriggerable state.

Return type: bool

class textworld.generator.game.Game(world, grammar=None, quests=())[source]¶

Bases: object

Game representation in TextWorld.

A Game is defined by a world and it can have quest(s) or not. Additionally, a grammar can be provided to control the text generation.

Parameters

world (World) – The world to use for the game.
quests (Iterable[Quest]) – The quests to be done in the game.
grammar (Optional[Grammar]) – The grammar to control the text generation.

change_grammar(grammar)[source]¶

Changes the grammar used and regenerate all text.

Return type: None

copy()[source]¶

Make a shallow copy of this game.

Return type: Game

classmethod deserialize(data)[source]¶

Creates a Game from serialized data.

Parameters: data (Mapping) – Serialized data with the needed information to build a Game object.
Return type: Game

classmethod load(filename)[source]¶

Creates Game from serialized data saved in a file.

Return type: Game

save(filename)[source]¶

Saves the serialized data of this game to a file.

Return type: None

serialize()[source]¶

Serialize this object.

Results:: Game’s data serialized to be JSON compatible

Return type: Mapping

property command_templates¶

All command templates understood in this game.

Return type: List[str]

property directions_names¶

Return type: List[str]

property entity_names¶

Return type: List[str]

property infos¶

Information about the entities in the game.

Return type: Dict[str, EntityInfo]

property max_score¶

Sum of the reward of all quests.

Return type: int

property objective¶

Return type: str

property objects_names¶

The names of all relevant objects in this game.

Return type: List[str]

property objects_names_and_types¶

The names of all non-player objects along with their type in this game.

Return type: List[str]

property objects_types¶

All types of objects in this game.

Return type: List[str]

property verbs¶

Verbs that should be recognized in this game.

Return type: List[str]

property walkthrough¶

Return type: Optional[List[str]]

property win_condition¶

All win conditions, one for each quest.

Return type: List[Collection[Proposition]]

class textworld.generator.game.GameOptions[source]¶

Bases: object

Options for customizing the game generation.

nb_rooms¶

Number of rooms in the game.

Type: int

nb_objects¶

Number of objects in the game.

Type: int

nb_parallel_quests¶

Number of parallel quests, i.e. not sharing a common goal.

Type: int

quest_length¶

Number of actions that need to be performed to complete the game.

Type: int

quest_breadth¶

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

Type: int

quest_depth¶

Number of actions that need to be performed to solve a subquest.

Type: int

path¶

Path of the compiled game (.ulx or .z8). Also, the source (.ni) and metadata (.json) files will be saved along with it.

Type: str

force_recompile¶

If True, recompile game even if it already exists.

Type: bool

file_ext¶

Type of the generated game file. Either .z8 (Z-Machine) or .ulx (Glulx). If path already has an extension, this is ignored.

Type: str

seeds¶

Seeds for the different generation processes.

If None, seeds will be sampled from textworld.g_rng.

If int, it acts as a seed for a random generator that will be used to sample the other seeds.

If dict, the following keys can be set:

'map': control the map generation;

'objects': control the type of objects and their location;

'quest': control the quest generation;

'grammar': control the text generation.

For any key missing, a random number gets assigned (sampled from textworld.g_rng).

Type: Optional[Union[int, Dict]]

kb¶

The knowledge base containing the logic and the text grammars (see textworld.generator.KnowledgeBase for more information).

Type: KnowledgeBase

chaining¶

For customizing the quest generation (see textworld.generator.ChainingOptions for the list of available options).

Type: ChainingOptions

grammar¶

For customizing the text generation (see textworld.generator.GrammarOptions for the list of available options).

Type: GrammarOptions

copy()[source]¶

Return type: GameOptions

property kb

Return type: KnowledgeBase

property quest_breadth

Return type: int

property quest_length

Return type: int

property rngs¶

Return type: Dict[str, RandomState]

property seeds

property uuid¶

Return type: str

class textworld.generator.game.GameProgression(game, track_quests=True)[source]¶

Bases: object

GameProgression keeps track of the progression of a game.

If tracking_quests is True, then winning_policy will be the list of Action that need to be applied in order to complete the game.

Parameters

game (Game) – The game for which to track progression.
track_quests (bool) – whether quest progressions are being tracked.

update(action)[source]¶

Update the state of the game given the provided action.

Parameters: action (Action) – Action affecting the state of the game.
Return type: None

property completed¶

Whether all quests are completed.

Return type: bool

property done¶

Whether all quests are completed or at least one has failed or is unfinishable.

Return type: bool

property failed¶

Whether at least one quest has failed or is unfinishable.

Return type: bool

property score¶

Sum of the reward of all completed quests.

Return type: int

property tracking_quests¶

Whether quests are being tracked or not.

Return type: bool

property valid_actions¶

Actions that are valid at the current state.

Return type: List[Action]

property winning_policy¶

Actions to be performed in order to complete the game.

Return type: Optional[List[Action]]
Returns: A policy that leads to winning the game. It can be None if tracking_quests is False or the quest has failed.

class textworld.generator.game.Quest(win_events=(), fail_events=(), reward=None, desc=None, commands=())[source]¶

Bases: object

Quest representation in TextWorld.

A quest is defined by a mutually exclusive set of winning events and a mutually exclusive set of failing events.

win_events¶: Mutually exclusive set of winning events. That is, only one such event needs to be triggered in order to complete this quest.

fail_events¶: Mutually exclusive set of failing events. That is, only one such event needs to be triggered in order to fail this quest.

reward¶: Reward given for completing this quest.

desc¶: A text description of the quest.

commands¶: List of text commands leading to this quest completion.

Parameters

win_events (Iterable[Event]) – Mutually exclusive set of winning events. That is, only one such event needs to be triggered in order to complete this quest.
fail_events (Iterable[Event]) – Mutually exclusive set of failing events. That is, only one such event needs to be triggered in order to fail this quest.
reward (Optional[int]) – Reward given for completing this quest. By default, reward is set to 1 if there is at least one winning events otherwise it is set to 0.
desc (Optional[str]) – A text description of the quest.
commands (Iterable[str]) – List of text commands leading to this quest completion.

copy()[source]¶

Copy this quest.

Return type: Quest

classmethod deserialize(data)[source]¶

Creates a Quest from serialized data.

Parameters: data (Mapping) – Serialized data with the needed information to build a Quest object.
Return type: Quest

is_failing(state)[source]¶

Check if this quest is failing in that particular state.

Return type: bool

is_winning(state)[source]¶

Check if this quest is winning in that particular state.

Return type: bool

serialize()[source]¶

Serialize this quest.

Results:: Quest’s data serialized to be JSON compatible

Return type: Mapping

property commands

Return type: Iterable[str]

property fail_events

Return type: Iterable[Event]

property win_events

Return type: Iterable[Event]

class textworld.generator.game.QuestProgression(quest, kb)[source]¶

Bases: object

QuestProgression keeps track of the completion of a quest.

Internally, the quest is represented as a dependency tree of relevant actions to be performed.

Parameters: quest (Quest) – The quest to keep track of its completion.

update(action=None, state=None)[source]¶

Update quest progression given available information.

Parameters

action (Optional[Action]) – Action potentially affecting the quest progression.
state (Optional[State]) – Current game state.

Return type

None

property completable¶

Check if the quest has winning events.

Return type: bool

property completed¶

Check whether the quest is completed.

Return type: bool

property done¶

Check if the quest is done (i.e. completed, failed or unfinishable).

Return type: bool

property failed¶

Check whether the quest has failed.

Return type: bool

property unfinishable¶

Check whether the quest is in an unfinishable state.

Return type: bool

property winning_policy¶

Actions to be performed in order to complete the quest.

Return type: Optional[List[Action]]

textworld.generator.game.gen_commands_from_actions(actions, kb=None)[source]¶

Return type: List[str]