# 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]
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. Optional[Action] Whether the tree has changed or not.
class textworld.generator.game.ActionDependencyTreeElement(value)[source]

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
action
Return type: Action
class textworld.generator.game.EntityInfo(id, type)[source]

Bases: object

classmethod deserialize(data)[source]

Creates a EntityInfo from serialized data.

Parameters: data (Mapping[~KT, +VT_co]) – Serialized data with the needed information to build a EntityInfo object. EntityInfo
serialize()[source]

Serialize this object.

Results:
EntityInfo’s data serialized to be JSON compatible
Return type: Mapping[~KT, +VT_co]
adj

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

definite

str – The definite article to use for this entity.

desc

str – Text description displayed when examining this entity in the game.

id

str – Unique name for this entity. It is used when generating

indefinite

str – The indefinite article to use for this entity.

name

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

noun

str – The noun part of the name, if available.

room_type

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

synonyms

List[str] – Alternative names that can be used to refer to this entity.

type

str – The type of this entity.

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[~KT, +VT_co]) – Serialized data with the needed information to build a Event object. 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[~KT, +VT_co]
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. Action Action that can only be applied when all conditions are statisfied.
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. bool 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. None
done

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

Return type: bool
triggered

Check whether the event has been triggered.

Return type: bool
triggering_policy

Actions to be performed in order to trigger the event.

Return type: List[Action]
untriggerable

Check whether the event is in an untriggerable state.

Return type: bool
class textworld.generator.game.Game(world, grammar=None, quests=(), kb=None)[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[~KT, +VT_co]) – Serialized data with the needed information to build a Game object. 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[~KT, +VT_co]
command_templates

All command templates understood in this game.

Return type: List[str]
directions_names
Return type: List[str]
entity_names
Return type: List[str]
infos

Information about the entities in the game.

Return type: Dict[str, EntityInfo]
objective
Return type: str
objects_names

The names of all relevant objects in this game.

Return type: List[str]
objects_names_and_types

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

Return type: List[str]
objects_types

All types of objects in this game.

Return type: List[str]
verbs

Verbs that should be recognized in this game.

Return type: List[str]
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

int – Number of rooms in the game.

nb_objects

int – Number of objects in the game.

nb_parallel_quests

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

quest_length

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

quest_breadth

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

quest_depth

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

path

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

force_recompile

bool – If True, recompile game even if it already exists.

file_ext

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

seeds

Optional[Union[int, Dict]]

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

kb

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

chaining

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

grammar

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

copy()[source]
Return type: GameOptions
kb
Return type: KnowledgeBase
quest_breadth
Return type: int
quest_length
Return type: int
rngs
Return type: Dict[str, RandomState]
seeds
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. None
completed

Whether all quests are completed.

Return type: bool
done

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

Return type: bool
failed

Whether at least one quest has failed or is unfinishable.

Return type: bool
max_score

Sum of the reward of all quests.

Return type: int
score

Sum of the reward of all completed quests.

Return type: int
tracking_quests

Whether quests are being tracked or not.

Return type: bool
valid_actions

Actions that are valid at the current state.

Return type: List[Action]
winning_policy

Actions to be performed in order to complete the game.

Return type: Optional[List[Action]] 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[~KT, +VT_co]) – Serialized data with the needed information to build a Quest object. 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[~KT, +VT_co]
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. None
completed

Check whether the quest is completed.

Return type: bool
done

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

Return type: bool
failed

Check whether the quest has failed.

Return type: bool
unfinishable

Check whether the quest is in an unfinishable state.

Return type: bool
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]