TextWorld

一个基于文本的游戏生成器，同时也是一个可扩展的沙盒学习环境，用于训练和测试强化学习（RL）智能体。更多关于TextWorld及其创建者的信息，请访问 aka.ms/textworld。如果您对TextWorld有任何疑问或反馈，请发送至 textworld@microsoft.com 或使用上方列出的Gitter频道。

安装

目前，TextWorld仅支持在__Linux__和__macOS__系统上运行__Python 3.9/3.10/3.11/3.12__。对于__Windows__用户，可以使用Docker作为替代方案（详见下方的Docker部分）。

要求

TextWorld的原生组件需要一些系统库的支持。在基于Debian/Ubuntu的系统上，可以通过以下命令安装这些依赖：

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

而在macOS上，则可以使用以下命令：

brew install libffi curl git

注意: 我们建议用户使用虚拟环境，以避免不同项目中的Python包相互干扰。常用的工具有Conda Environments和Virtualenv。

安装TextWorld

安装TextWorld最简单的方式是通过pip：

pip install textworld

或者，在克隆仓库后，进入项目的根目录（即setup.py所在的目录），然后运行：

pip install .

可视化

TextWorld自带了一些用于可视化游戏状态的工具。请确保所有依赖项都已安装，运行以下命令：

pip install textworld[vis]

随后，您还需要安装Chrome或Firefox的WebDriver（取决于您当前安装的浏览器）。如果您已经安装了Chrome，可以使用以下命令安装chromedriver：

pip install chromedriver_installer

当前可用的可视化工具包括：textworld.render模块中的take_screenshot、visualize和show_graph。

Docker

最新版本的TextWorld容器已在DockerHub上发布。

docker pull marccote19/textworld
docker run -p 8888:8888 -it --rm marccote19/textworld

然后，在您的浏览器中打开终端显示的Jupyter Notebook链接。该链接应类似于：

http://127.0.0.1:8888/?token=8d7aaa...e95

注意: 有关故障排除信息，请参阅docker文件夹中的README.md。

使用

生成游戏

TextWorld提供了一个简单的脚本tw-make来生成基于文本的小型游戏。例如：

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

其中，custom表示我们将使用以下选项自定义游戏：--world-size控制世界中的房间数量，--nb-objects控制可交互对象的数量（不包括门），而--quest-length则控制赢得游戏所需的最少指令数。完成后，游戏custom_game.z8将被保存到tw_games/文件夹中。

玩游戏（终端）

要玩游戏，可以使用tw-play脚本。例如，运行上一节生成的游戏的命令如下：

tw-play tw_games/custom_game.z8

注意: 目前仅支持Z-machine格式的游戏（.z1至.z8）。

在游戏过程中，若想可视化游戏状态，可以使用--viewer [port]选项。

tw-play tw_games/custom_game.z8 --viewer

此时会打开一个新的浏览器标签页，实时跟踪您的游戏进度。

玩游戏（Python + 类似Gym的API）

以下是使用类似Gym的API从Python内部与基于文本的游戏交互的方法。

import textworld.gym

# 将一个基于文本的游戏注册为新的环境。
env_id = textworld.gym.register_game("tw_games/custom_game.z8",
                                     max_episode_steps=50)

env = textworld.gym.make(env_id)  # 启动环境。

obs, infos = env.reset()  # 开始新回合。
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))

注意: 如果您希望在没有类似Gym的API的情况下玩基于文本的游戏，请参阅Playing text-based games with TextWorld.ipynb。

文档

有关TextWorld的更多信息，请查阅文档。

Visual Studio Code

您可以安装textworld-vscode扩展，它支持.twl和.twg TextWorld文件的语法高亮显示。

笔记本

请查看框架附带的笔记本，了解其功能。运行这些笔记本需要Jupyter Notebook，您可以通过以下命令安装：

pip install jupyter

引用TextWorld

如果您使用了TextWorld，请引用以下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}
}

贡献

本项目欢迎贡献和建议。大多数贡献都需要您签署一份贡献者许可协议（CLA），声明您有权且确实将您的贡献使用权授予我们。有关详细信息，请访问 https://cla.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地为 PR 添加标记或评论。请按照机器人提供的指示操作。对于使用我们 CLA 的所有仓库，您只需执行此操作一次。

本项目已采用 微软开源行为准则。如需更多信息，请参阅 行为准则常见问题解答，或通过电子邮件 opencode@microsoft.com 联系我们，提出任何其他问题或意见。

许可证

• TextWorld - MIT 许可证
• Inform7 - 艺术家许可证 2.0
• Jericho - GNU 通用公共许可证 (GPL) v2.0
• Fast Downward - GNU 通用公共许可证 (GPL) v3.0
• Git - MIT 许可证

TextWorld 快速上手指南

TextWorld 是一个基于文本的游戏生成器和可扩展的沙盒学习环境，专为训练和测试强化学习（RL）智能体而设计。

环境准备

系统要求

• 操作系统：仅支持 Linux 和 macOS。
  • Windows 用户请使用 Docker 方案（见安装部分）。
• Python 版本：3.9 / 3.10 / 3.11 / 3.12
• 建议：推荐使用虚拟环境（如 Conda 或 Virtualenv）以避免依赖冲突。

前置依赖

在安装 TextWorld 之前，请先安装必要的系统库：

Debian/Ubuntu 系统：

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

macOS 系统：

brew install libffi curl git

安装步骤

1. 基础安装

通过 pip 安装是最便捷的方式：

pip install textworld

(注：国内用户可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源加速)

若已从 GitHub 克隆仓库，可在项目根目录运行：

pip install .

2. 可选：可视化组件

若需使用游戏状态可视化工具，请安装额外依赖：

pip install textworld[vis]

随后需根据本地浏览器安装对应的 WebDriver：

• Chrome 用户：

  pip install chromedriver_installer
  

• Firefox 用户：请手动下载并配置 geckodriver。

3. 可选：Docker 方案（适用于 Windows 或隔离环境）

docker pull marccote19/textworld
docker run -p 8888:8888 -it --rm marccote19/textworld

运行后，在浏览器中访问终端显示的 Jupyter Notebook 链接（例如 http://127.0.0.1:8888/?token=...）即可开始使用。

基本使用

1. 生成游戏

使用 tw-make 脚本快速生成一个自定义文本游戏。以下命令生成一个包含 5 个房间、10 个可交互物体且通关最少需要 5 步的游戏：

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

生成的游戏文件 custom_game.z8 将保存在 tw_games/ 目录下。

2. 在终端玩游戏

使用 tw-play 脚本直接体验生成的游戏：

tw-play tw_games/custom_game.z8

若希望在浏览器中实时可视化游戏状态，可添加 --viewer 参数：

tw-play tw_games/custom_game.z8 --viewer

3. 通过 Python 代码交互 (Gym API)

TextWorld 提供了类似 OpenAI Gym 的接口，方便集成到强化学习流程中：

import textworld.gym

# 注册游戏环境
env_id = textworld.gym.register_game("tw_games/custom_game.z8",
                                     max_episode_steps=50)

env = textworld.gym.make(env_id)  # 启动环境

obs, infos = env.reset()  # 开始新回合
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))