{"id":15012436,"url":"https://github.com/microsoft/textworld","last_synced_at":"2025-05-13T23:00:32.528Z","repository":{"id":40444303,"uuid":"138774676","full_name":"microsoft/TextWorld","owner":"microsoft","description":"​TextWorld is a sandbox learning environment for the training and evaluation of reinforcement learning (RL) agents on text-based games.","archived":false,"fork":false,"pushed_at":"2025-01-23T17:17:23.000Z","size":7429,"stargazers_count":1290,"open_issues_count":17,"forks_count":188,"subscribers_count":38,"default_branch":"main","last_synced_at":"2025-04-29T18:57:13.958Z","etag":null,"topics":["reinforcement-learning","text-based-adventure","text-based-game"],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-26T18:00:55.000Z","updated_at":"2025-04-28T22:05:00.000Z","dependencies_parsed_at":"2023-01-23T06:45:07.728Z","dependency_job_id":"c5ce6c5e-63a8-432b-b7cb-1bff2b76beb5","html_url":"https://github.com/microsoft/TextWorld","commit_stats":{"total_commits":415,"total_committers":32,"mean_commits":12.96875,"dds":0.2506024096385542,"last_synced_commit":"3ca9df8df683edf6f59566b5d111e5b42fe297f1"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FTextWorld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FTextWorld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FTextWorld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FTextWorld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/TextWorld/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251565801,"owners_count":21609979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["reinforcement-learning","text-based-adventure","text-based-game"],"created_at":"2024-09-24T19:42:37.826Z","updated_at":"2025-04-29T18:57:27.594Z","avatar_url":"https://github.com/microsoft.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TextWorld\n\n[![PyPI version](https://img.shields.io/pypi/v/textworld.svg?logo=pypi\u0026label=PyPI\u0026logoColor=gold)](https://pypi.org/project/textworld)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/textworld.svg?logo=python\u0026label=Python\u0026logoColor=gold)](https://pypi.org/project/textworld/)\n[![Build Status](https://dev.azure.com/maluuba/TextWorld/_apis/build/status/microsoft.TextWorld?branchName=main)](https://dev.azure.com/maluuba/TextWorld/_build/latest?definitionId=180\u0026branchName=main)\n[![Documentation Status](https://readthedocs.org/projects/textworld/badge/?version=latest)](https://textworld.readthedocs.io/en/stable/?badge=stable)\n[![Join the chat at https://gitter.im/Microsoft/TextWorld](https://badges.gitter.im/Microsoft/TextWorld.svg)](https://gitter.im/Microsoft/TextWorld?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nA text-based game generator and extensible sandbox learning environment for training and testing reinforcement learning (RL) agents. Also check out [aka.ms/textworld](https://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.\n\n## Installation\n\nTextWorld supports __Python 3.9/3.10/3.11/3.12__ for __Linux__ and __macOS__ systems only at the moment. For __Windows__ users, docker can be used as a workaround (see Docker section below).\n\n### Requirements\n\nTextWorld requires some system libraries for its native components.\nOn a Debian/Ubuntu-based system, these can be installed with\n\n    sudo apt update \u0026\u0026 sudo apt install build-essential libffi-dev python3-dev curl git\n\nAnd on macOS, with\n\n    brew install libffi curl git\n\n\u003e **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](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) and [Virtualenv](https://virtualenv.pypa.io/en/stable/)\n\n### Installing TextWorld\n\nThe easiest way to install TextWorld is via [`pip`](https://pypi.org/):\n\n    pip install textworld\n\nOr, after cloning the repo, go inside the root folder of the project (i.e. alongside `setup.py`) and run\n\n    pip install .\n\n#### Visualization\n\nTextWorld comes with some tools to visualize game states. Make sure all dependencies are installed by running\n\n    pip install textworld[vis]\n\nThen, you will need to install either the [Chrome](https://sites.google.com/a/chromium.org/chromedriver/) or [Firefox](https://github.com/mozilla/geckodriver) webdriver (depending on which browser you have currently installed).\nIf you have Chrome already installed you can use the following command to install chromedriver\n\n    pip install chromedriver_installer\n\nCurrent visualization tools include: `take_screenshot`, `visualize` and `show_graph` from [`textworld.render`](https://textworld.readthedocs.io/en/latest/textworld.render.html).\n\n### Docker\n\nA docker container with the latest TextWorld release is available on [DockerHub](https://hub.docker.com/).\n\n    docker pull marccote19/textworld\n    docker run -p 8888:8888 -it --rm marccote19/textworld\n\nThen, in your browser, navigate to the Jupyter notebook's link displayed in your terminal. The link should look like this\n\n    http://127.0.0.1:8888/?token=8d7aaa...e95\n\n\u003e **Note:** See [README.md](docker/README.md) in the docker folder for troubleshooting information.\n\n## Usage\n\n### Generating a game\n\nTextWorld provides an easy way of generating simple text-based games via the `tw-make` script. For instance,\n\n    tw-make custom --world-size 5 --nb-objects 10 --quest-length 5 --seed 1234 --output tw_games/custom_game.z8\n\nwhere `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.z8` will be saved in the `tw_games/` folder.\n\n### Playing a game (terminal)\n\nTo 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\n\n    tw-play tw_games/custom_game.z8\n\n\u003e **Note:** Only Z-machine's games (*.z1 through *.z8) and Glulx's games (*.ulx) are supported.\n\nTo visualize the game state while playing, use the `--viewer [port]` option.\n\n    tw-play tw_games/custom_game.z8 --viewer\n\nA new browser tab should open and track your progress in the game.\n\n### Playing a game (Python + [Gym](https://github.com/openai/gym)-like API)\n\nHere's how you can interact with a text-based game from within Python using a Gym-like API.\n\n```python\nimport textworld.gym\n\n# Register a text-based game as a new environment.\nenv_id = textworld.gym.register_game(\"tw_games/custom_game.z8\",\n                                     max_episode_steps=50)\n\nenv = textworld.gym.make(env_id)  # Start the environment.\n\nobs, infos = env.reset()  # Start new episode.\nenv.render()\n\nscore, moves, done = 0, 0, False\nwhile not done:\n    command = input(\"\u003e \")\n    obs, score, done, infos = env.step(command)\n    env.render()\n    moves += 1\n\nenv.close()\nprint(\"moves: {}; score: {}\".format(moves, score))\n```\n\n\u003e **Note:** To play text-based games without a Gym-like API, see [Playing text-based games with TextWorld.ipynb](notebooks/Playing%20text-based%20games%20with%20TextWorld.ipynb)\n\n## Documentation\n\nFor more information about TextWorld, check the [documentation](https://aka.ms/textworld-docs).\n\n## Visual Studio Code\n\nYou can install the [textworld-vscode extension ](https://marketplace.visualstudio.com/items?itemName=textworld.textworld-vscode) that enables syntax highlighting for editing `.twl` and `.twg` TextWorld files.\n\n## Notebooks\n\nCheck the [notebooks](notebooks) provided with the framework to see what you can do with it. You will need the [Jupyter Notebook](https://jupyter.org/install) to run them. You can install it with\n\n    pip install jupyter\n\n## Citing TextWorld\n\nIf you use TextWorld, please cite the following BibTex:\n\n```text\n@Article{cote18textworld,\n  author = {Marc-Alexandre C\\^ot\\'e and\n            \\'Akos K\\'ad\\'ar and\n            Xingdi Yuan and\n            Ben Kybartas and\n            Tavian Barnes and\n            Emery Fine and\n            James Moore and\n            Ruo Yu Tao and\n            Matthew Hausknecht and\n            Layla El Asri and\n            Mahmoud Adada and\n            Wendy Tay and\n            Adam Trischler},\n  title = {TextWorld: A Learning Environment for Text-based Games},\n  journal = {CoRR},\n  volume = {abs/1806.11532},\n  year = {2018}\n}\n```\n\n## Contributing\n\nThis project welcomes contributions and suggestions.  Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n## License\n\n- [TextWorld](https://github.com/microsoft/TextWorld) - MIT License\n- [Inform7](https://github.com/ganelson/inform) - Artistic License 2.0\n- [Jericho](https://github.com/microsoft/jericho) - GNU General Public License (GPL) v2.0\n- [Fast Downward](https://github.com/MarcCote/downward) - GNU General Public License (GPL) v3.0\n- [Git](https://github.com/DavidKinder/Git) - MIT License\n- [cheakglk](https://github.com/erkyrath/cheapglk) - MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Ftextworld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Ftextworld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Ftextworld/lists"}