Package: textworld
TextWorldA text-based game generator and extensible sandbox learning environment for training and testing reinforcement learning (RL) agents. Also check outaka.ms/textworldfor more info about TextWorld and its creators. Have questions or feedback about TextWorld? Send them totextworld@microsoft.comor use the Gitter channel listed above.InstallationTextWorld supportsPython 3.9/3.10/3.11/3.12forLinuxandmacOSsystems only at the moment. ForWindowsusers, docker can be used as a workaround (see Docker section below).RequirementsTextWorld requires some system libraries for its native components.
On a Debian/Ubuntu-based system, these can be installed withsudo apt update && sudo apt install build-essential libffi-dev python3-dev curl gitAnd on macOS, withbrew install libffi curl gitNote:We advise our users to use virtual environments to avoid Python packages from different projects to interfere with each other. Popular choices areConda EnvironmentsandVirtualenvInstalling TextWorldThe easiest way to install TextWorld is viapip:pip install textworldOr, after cloning the repo, go inside the root folder of the project (i.e. alongsidesetup.py) and runpip install .VisualizationTextWorld comes with some tools to visualize game states. Make sure all dependencies are installed by runningpip install textworld[vis]Then, you will need to install either theChromeorFirefoxwebdriver (depending on which browser you have currently installed).
If you have Chrome already installed you can use the following command to install chromedriverpip install chromedriver_installerCurrent visualization tools include:take_screenshot,visualizeandshow_graphfromtextworld.render.DockerA docker container with the latest TextWorld release is available onDockerHub.docker pull marccote19/textworld
docker run -p 8888:8888 -it --rm marccote19/textworldThen, in your browser, navigate to the Jupyter notebook's link displayed in your terminal. The link should look like thishttp://127.0.0.1:8888/?token=8d7aaa...e95Note:SeeREADME.mdin the docker folder for troubleshooting information.UsageGenerating a gameTextWorld provides an easy way of generating simple text-based games via thetw-makescript. For instance,tw-make custom --world-size 5 --nb-objects 10 --quest-length 5 --seed 1234 --output tw_games/custom_game.z8wherecustomindicates we want to customize the game using the following options:--world-sizecontrols the number of rooms in the world,--nb-objectscontrols the number of objects that can be interacted with (excluding doors) and--quest-lengthcontrols the minimum number of commands that is required to type in order to win the game. Once done, the gamecustom_game.z8will be saved in thetw_games/folder.Playing a game (terminal)To play a game, one can use thetw-playscript. For instance, the command to play the game generated in the previous section would betw-play tw_games/custom_game.z8Note:Only Z-machine's games (*.z1 through.z8) and Glulx's games (.ulx) are supported.To visualize the game state while playing, use the--viewer [port]option.tw-play tw_games/custom_game.z8 --viewerA new browser tab should open and track your progress in the game.Playing a game (Python +Gym-like API)Here's how you can interact with a text-based game from within Python using a Gym-like API.importtextworld.gym# Register a text-based game as a new environment.env_id=textworld.gym.register_game("tw_games/custom_game.z8",max_episode_steps=50)env=textworld.gym.make(env_id)# Start the environment.obs,infos=env.reset()# Start new episode.env.render()score,moves,done=0,0,Falsewhilenotdone:command=input("> ")obs,score,done,infos=env.step(command)env.render()moves+=1env.close()print("moves:{}; score:{}".format(moves,score))Note:To play text-based games without a Gym-like API, seePlaying text-based games with TextWorld.ipynbDocumentationFor more information about TextWorld, check thedocumentation.Visual Studio CodeYou can install thetextworld-vscode extensionthat enables syntax highlighting for editing.twland.twgTextWorld files.NotebooksCheck thenotebooksprovided with the framework to see what you can do with it. You will need theJupyter Notebookto run them. You can install it withpip install jupyterCiting TextWorldIf 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
            Ruo Yu Tao 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}
}ContributingThis 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, visithttps://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 theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor
contactopencode@microsoft.comwith any additional questions or comments.