Repository files navigation

DeepMind Lab is a 3D learning environment based on id Software'sQuake III Arena viaioquake3 andother open source software.

DeepMind Lab provides a suite of challenging 3D navigation and puzzle-solvingtasks for learning agents. Its primary purpose is to act as a testbed forresearch in artificial intelligence, especially deep reinforcement learning.

Disclaimer: This is not an official Google product.

If you useDeepMind Lab in your research and would like to citetheDeepMind Lab environment, we suggest you citetheDeepMind Lab paper.

You can reach us atlab@deepmind.com.

• GetBazel from bazel.io.

• Clone DeepMind Lab, e.g. by running

$ git clone https://github.com/deepmind/lab$cd lab

For a live example of a random agent, run

lab$ bazel run :python_random_agent --define graphics=sdl -- \               --length=10000 --width=640 --height=480

Here is somemore detailed build documentation,including how to install dependencies if you don't have them.

To enable compiler optimizations, pass the flag--compilation_mode=opt, or-c opt for short, to eachbazel build,bazel test andbazel run command.The flag is omitted from the examples here for brevity, but it should be usedfor real training and evaluation where performance matters.

To test the game using human input controls, run

lab$ bazel run :game -- --level_script=tests/empty_room_test --level_setting=logToStdErr=true# or:lab$ bazel run :game -- -l tests/empty_room_test -s logToStdErr=true

Leave thelogToStdErr setting off to disable most log output.

The values of observations that the environment exposes can be printed at everystep by adding a flag--observation OBSERVATION_NAME for each observation ofinterest.

lab$ bazel run :game -- --level_script=lt_chasm --observation VEL.TRANS --observation VEL.ROT

DeepMind Lab ships with an example random agent inpython/random_agent.pywhich can be used as a starting point for implementing a learning agent. To letthis agent interact with DeepMind Lab for training, run

lab$ bazel run :python_random_agent

ThePython API isused for agent-environment interactions. We also provide bindings to DeepMind's"dm_env" general API for reinforcementlearning, as well as a way to build a self-contained PIP package; see theseparate documentationfor details.

DeepMind Lab ships withdifferentlevels implementing differenttasks. These tasks can be configured using Lua scripts, as described in theLuaAPI.

DeepMind Lab is built from theioquake3 game engine, and it uses the toolsq3map2 andbspc for map creation. Bug fixes and cleanups that originatewith those projects are best fixed upstream and then merged intoDeepMind Lab.

• bspc is taken fromgithub.com/TTimo/bspc,revision d9a372db3fb6163bc49ead41c76c801a3d14cf80. There are virtually nolocal modifications, although we integrate this code with the main ioq3 codeand do not use their copy in thedeps directory. We expect this code to bestable.

• q3map2 is taken fromgithub.com/TTimo/GtkRadiant,revision d3d00345c542c8d7cc74e2e8a577bdf76f79c701. A few minor localmodifications add synchronization. We also expect this code to be stable.

• ioquake3 is taken fromgithub.com/ioquake/ioq3,revision 29db64070aa0bae49953bddbedbed5e317af48ba. The code contains extensivemodifications and additions. We aim to merge upstream changes occasionally.

We are very grateful to the maintainers of these repositories for all their hardwork on maintaining high-quality code bases.

DeepMind Lab currently ships as source code only. It depends on a few externalsoftware libraries, which we ship in several different ways:

• Thezlib,glib,libxml2,jpeg andpng libraries are referenced asexternal Bazel sources, and Bazel BUILD files are provided. The dependentcode itself should be fairly portable, but the BUILD rules we ship arespecific to Linux on x86. To build on a different platform you will mostlikely have to edit those BUILD files.

• Message digest algorithms are included in this package (in//third_party/md), taken from the referenceimplementations of their respective RFCs. A "generic reinforcement learningAPI" is included in//third_party/rl_api, which hasalso been created by theDeepMind Lab authors. This code is portable.

• EGL headers are included in this package (in//third_party/GL/{EGL,KHR}),taken from the Khronos OpenGL/OpenGL ES XML API Registry atwww.khronos.org/registry/EGL. Theheaders have been modified slightly to remove the dependency of EGL on X.

• Several additional libraries are required but are not shipped in any form;they must be present on your system:

  • SDL 2
  • gettext (required byglib)
  • OpenGL: A hardware driver and library are needed for hardware-acceleratedhuman play. The headless library that machine learning agents will want touse can use either hardware-accelerated rendering via EGL or GLX orsoftware rendering via OSMesa, depending on the--define headless=...build setting.
  • Python 2.7 (other versions might work, too) with NumPy, PIL (a few testsrequire a NumPy version of at least 1.8), or Python 3 (at least 3.5) withNumPy and Pillow.

The build rules are using a few compiler settings that are specific to GCC. Ifsome flags are not recognized by your compiler (typically those would bespecific warning suppressions), you may have to edit those flags. The warningsshould be noisy but harmless.