Game¶
- class textworld.generator.game.ActionDependencyTree(*args, kb=None, **kwargs)[source]¶
Bases:
DependencyTree
- 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:
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
- 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 aEntityInfo
object.- Return type:
- serialize()[source]¶
Serialize this object.
- Return type:
Mapping
- Returns:
EntityInfo’s data serialized to be JSON compatible.
- 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.
- Parameters:
actions (
Iterable
[Action
]) – The actions to be performed to trigger this event. If an empty list, thenconditions
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.
- 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:
- Returns:
Action that can only be applied when all conditions are statisfied.
- property actions: Tuple[Action]¶
Actions to perform to trigger this event.
- Return type:
Tuple
[Action
]
- property commands: Tuple[str]¶
Human readable version of the actions.
- Return type:
Tuple
[str
]
- condition¶
Action that can only be applied when all conditions are statisfied.
- Type:
- 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.
- property done: bool¶
Check if the quest is done (i.e. triggered or untriggerable).
- Return type:
bool
- property triggered: bool¶
Check whether the event has been triggered.
- Return type:
bool
- property triggering_policy: List[Action]¶
Actions to be performed in order to trigger the event.
- Return type:
List
[Action
]
- property untriggerable: bool¶
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:
- change_grammar(grammar)[source]¶
Changes the grammar used and regenerate all text.
- Return type:
None
- serialize()[source]¶
Serialize this object.
- Results:
Game’s data serialized to be JSON compatible
- Return type:
Mapping
- property command_templates: List[str]¶
All command templates understood in this game.
- Return type:
List
[str
]
- property directions_names: List[str]¶
- Return type:
List
[str
]
- property entity_names: List[str]¶
- Return type:
List
[str
]
- property infos: Dict[str, EntityInfo]¶
Information about the entities in the game.
- Return type:
Dict
[str
,EntityInfo
]
- property max_score: float¶
Sum of the reward of all quests.
- Return type:
float
- property objective: str¶
- Return type:
str
- property objects_names: List[str]¶
The names of all relevant objects in this game.
- Return type:
List
[str
]
- property objects_names_and_types: List[str]¶
The names of all non-player objects along with their type in this game.
- Return type:
List
[str
]
- property objects_types: List[str]¶
All types of objects in this game.
- Return type:
List
[str
]
- property verbs: List[str]¶
Verbs that should be recognized in this game.
- Return type:
List
[str
]
- property walkthrough: Optional[List[str]]¶
- Return type:
Optional
[List
[str
]]
- 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_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
- chaining¶
For customizing the quest generation (see
textworld.generator.ChainingOptions
for the list of available options).- Type:
- grammar¶
For customizing the text generation (see
textworld.generator.GrammarOptions
for the list of available options).- Type:
- property kb: KnowledgeBase¶
The knowledge base containing the logic and the text grammars (see
textworld.generator.KnowledgeBase
for more information).- Return type:
- property quest_breadth: int¶
Number of subquests per independent quest. It controls how nonlinear a quest can be (1 means linear).
- Return type:
int
- property quest_length: int¶
Number of actions that need to be performed to complete the game.
- Return type:
int
- property rngs: Dict[str, RandomState]¶
- Return type:
Dict
[str
,RandomState
]
- property seeds¶
Seeds for the different generation processes.
If
None
, seeds will be sampled fromtextworld.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
).
- property uuid: str¶
- 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, thenwinning_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: bool¶
Whether all non-optional quests are completed.
- Return type:
bool
- property done: bool¶
Whether all non-optional quests are completed or at least one has failed or is unfinishable.
- Return type:
bool
- property failed: bool¶
Whether at least one non-optional quest has failed or is unfinishable.
- Return type:
bool
- property score: int¶
Sum of the reward of all completed quests.
- Return type:
int
- property tracking_quests: bool¶
Whether quests are being tracked or not.
- Return type:
bool
- property valid_actions: List[Action]¶
Actions that are valid at the current state.
- Return type:
List
[Action
]
- property winning_policy: Optional[List[Action]]¶
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
iftracking_quests
isFalse
or the quest has failed.
- class textworld.generator.game.Quest(win_events=(), fail_events=(), reward=None, desc=None, commands=(), optional=False, repeatable=False)[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.
- 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.optional (
bool
) – If True, this quest is optional to finish the game.repeatable (
bool
) – If True, this quest can be completed more than once.
- 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.
- Return type:
Mapping
- Returns:
Quest’s data serialized to be JSON compatible.
- property commands: Iterable[str]¶
List of text commands leading to this quest completion.
- Return type:
Iterable
[str
]
- desc¶
A text description of the quest.
- Type:
str
- property fail_events: Tuple[Event]¶
Mutually exclusive set of failing events. That is, only one such event needs to be triggered in order to fail this quest.
- Return type:
Tuple
[Event
]
- optional¶
Whether this quest is optional or not to finish the game.
- Type:
bool
- repeatable¶
Whether this quest can be completed more than once.
- Type:
bool
- 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.
- property completable: bool¶
Check if the quest has winning events.
- Return type:
bool
- property completed: bool¶
Check whether the quest is completed.
- Return type:
bool
- property done: bool¶
Check if the quest is done (i.e. completed, failed or unfinishable).
- Return type:
bool
- property failed: bool¶
Check whether the quest has failed.
- Return type:
bool
- property unfinishable: bool¶
Check whether the quest is in an unfinishable state.
- Return type:
bool