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