Skip to content
​TextWorld is a sandbox learning environment for the training and evaluation of reinforcement learning (RL) agents on text-based games.
Branch: master
Clone or download
MarcCote Merge pull request #155 from MarcCote/support_zmachine_gym
Support ZMachine games with Gym API
Latest commit 0b4a1ba Apr 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis Addin pydot as a dependency Oct 25, 2018
benchmark Import the TextWorld code Jul 12, 2018
docker Remove uuid.h dependency Dec 11, 2018
docs docs: Keep the version number in sync Feb 8, 2019
misc Import the TextWorld code Jul 12, 2018
notebooks Fix directory to games Feb 16, 2019
scripts Forgot to load --third-party Feb 20, 2019
src glk: Create the socket name race-free Jan 31, 2019
tests Fix text grammar ebnf Mar 4, 2019
textworld
tools package.sh: Remove architecture-specific files from the sdist Feb 8, 2019
.gitignore
.travis.yml Remove uuid.h dependency Dec 11, 2018
CHANGELOG.md Release 1.1.1 Feb 8, 2019
CONTRIBUTING.md Import the TextWorld code Jul 12, 2018
LICENSE.txt Import the TextWorld code Jul 12, 2018
MANIFEST.in package.sh: Remove architecture-specific files from the sdist Feb 8, 2019
README.md minor Apr 12, 2019
TODO.md Import the TextWorld code Jul 12, 2018
delete_rewritten_files.ps1
glk_build.py Remove unused imports Feb 19, 2019
requirements.txt gym: Relax exact version dependency Mar 28, 2019
rewrite_files.ps1 Import the TextWorld code Jul 12, 2018
setup.py Preparing for release Dec 7, 2018
setup.sh Remove Tatsu lines in setup.sh Jan 25, 2019
tox.ini Import the TextWorld code Jul 12, 2018

README.md

TextWorld

Build Status PyPI version Documentation Status Join the chat at https://gitter.im/Microsoft/TextWorld

A text-based game generator and extensible sandbox learning environment for training and testing reinforcement learning (RL) agents. Also check out aka.ms/textworld for more info about TextWorld and its creators. Have questions or feedback about TextWorld? Send them to textworld@microsoft.com or use the Gitter channel listed above.

Installation

TextWorld requires Python 3 and only supports Linux and macOS systems at the moment.

Requirements

TextWorld requires some system libraries for its native components. On a Debian/Ubuntu-based system, these can be installed with

sudo apt update && sudo apt install build-essential libffi-dev python3-dev curl git

And on macOS, with

brew install libffi curl git

Note: We advise our users to use virtual environments to avoid Python packages from different projects to interfere with each other. Popular choices are Conda Environments and Virtualenv

Installing TextWorld

The easiest way to install TextWorld is via pip:

pip install textworld

Or, after cloning the repo, go inside the root folder of the project (i.e. alongside setup.py) and run

pip install .

Extras

In order to use the take_screenshot or visualize functions in textworld.render, you'll need to install either the Chrome or Firefox webdriver (depending on which browser you have installed). If you have Chrome already installed you can use the following command to install chromedriver

pip install chromedriver_installer

Usage

Generating a game

TextWorld provides an easy way of generating simple text-based games via the tw-make script. For instance,

tw-make custom --world-size 5 --nb-objects 10 --quest-length 5 --seed 1234 --output tw_games/custom_game.ulx

where custom indicates we want to customize the game using the following options: --world-size controls the number of rooms in the world, --nb-objects controls the number of objects that can be interacted with (excluding doors) and --quest-length controls the minimum number of commands that is required to type in order to win the game. Once done, the game custom_game.ulx will be saved in the tw_games/ folder.

Playing a game (terminal)

To play a game, one can use the tw-play script. For instance, the command to play the game generated in the previous section would be

tw-play tw_games/custom_game.ulx

Note: Only Z-machine's games (*.z1 through .z8) and Glulx's games (.ulx) are supported.

Playing a game (Python + Gym)

Here's how you can interact with a text-based game from within Python using OpenAI's Gym framework.

import gym
import textworld.gym

# Register a text-based game as a new Gym's environment.
env_id = textworld.gym.register_game("tw_games/custom_game.ulx",
                                     max_episode_steps=50)

env = gym.make(env_id)  # Start the environment.

obs, infos = env.reset()  # Start new episode.
env.render()

score, moves, done = 0, 0, False
while not done:
    command = input("> ")
    obs, score, done, infos = env.step(command)
    env.render()
    moves += 1

env.close()
print("moves: {}; score: {}".format(moves, score))

Note: To play text-based games without Gym, see Playing text-based games with TextWorld.ipynb

Documentation

For more information about TextWorld, check the documentation.

Notebooks

Check the notebooks provided with the framework to see what you can do with it. You will need the Jupyter Notebook to run them. You can install it with

pip install jupyter

Citing TextWorld

If you use TextWorld, please cite the following BibTex:

@Article{cote18textworld,
  author = {Marc-Alexandre C\^ot\'e and
            \'Akos K\'ad\'ar and
            Xingdi Yuan and
            Ben Kybartas and
            Tavian Barnes and
            Emery Fine and
            James Moore and
            Matthew Hausknecht and
            Layla El Asri and
            Mahmoud Adada and
            Wendy Tay and
            Adam Trischler},
  title = {TextWorld: A Learning Environment for Text-based Games},
  journal = {CoRR},
  volume = {abs/1806.11532},
  year = {2018}
}

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

You can’t perform that action at this time.