Skip to content

/ lab

A customisable 3D platform for agent-based AI research
machine-learning artificial-intelligence neural-networks deep-learning
C Lua C++ Python GLSL ShaderLab Other
  1. C 80.3%
  2. Lua 8.1%
  3. C++ 7.7%
  4. Python 1.4%
  5. GLSL 1.2%
  6. ShaderLab 0.5%
  7. Other 0.8%
Branch: master
Find file
Clone or download

Clone with HTTPS

Use Git or checkout with SVN using the web URL.

Open in Desktop Download ZIP

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio

If nothing happens, download the GitHub extension for Visual Studio and try again.

Latest commit

@tkoeppe
tkoeppe [pip] Update instructions to refer to a map that allows for rewards. 
The original instructions that promised a reward of "11.0" were left
over from an early, unreleased state that used a different map that
was never released. The map that we used for the released version,
tests/empty_room_test, does not actually contain any rewards.

This change switches the map in the example over to
demos/extra_entities, which contains four apples in front of the spawn
point. Walking forward for a bit will collect those apples, and thus
produce a reward of 4.0.
Latest commit 9c1e1b9 Jan 7, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets [assets, deepmind] Minor style fixes Jan 11, 2019
assets_oa [bots] Correct typo in bot `Leonis`, skill level 1. Sep 2, 2019
bazel [travis, python.BUILD] Switch Travis distro to "bionic" Dec 2, 2019
data [datasets] Add MNIST dataset. May 4, 2018
deepmind [engine] Fix a bug that caused loss of angular velocity information. Dec 5, 2019
docs [docs] Update hyperlink in build.md Nov 21, 2019
engine [engine] Add missing inclusion of own-header Jan 6, 2020
examples [game] Add --observation flag to the :game executable. Feb 12, 2019
game_scripts [psychlab] Additional Psychlab levels: explore_goal_locations Dec 5, 2019
lua_tests [game_scripts] A decorator for defining properties Oct 30, 2019
public [dmlab_so_loader] Refactor loading of unique DSOs; using mkstemp(s) Oct 22, 2019
python [pip] Update instructions to refer to a map that allows for rewards. Jan 7, 2020
q3map2 [q3map2] Avoid division by zero Feb 23, 2018
testing [deepmind, public, testing] Use Abseil hash maps Oct 22, 2018
third_party [rl_api] Remove license comment that is redundant with the canonical … Oct 31, 2019
.gitignore .gitignore rules for Bazel output Nov 30, 2016
.travis.bazelrc [BUILD, travis] Exclude expensive tests from Travis. Dec 5, 2019
.travis.yml [travis] Add a step to build all targets Dec 2, 2019
BUILD [BUILD, travis] Exclude expensive tests from Travis. Dec 5, 2019
CONTRIBUTING Rules for contributing Nov 29, 2016
LICENSE Initial commit Nov 29, 2016
README.md [pip, README] Include the dm_env bindings module in the PIP package. Nov 22, 2019
RELEASE_NOTES.md [engine] Fix a bug that caused loss of angular velocity information. Dec 5, 2019
WORKSPACE [WORKSPACE, bazel] Move external BUILD files into "bazel" directory Nov 20, 2019
dmlab.lds [dmlab.lds] Remove exposition of unneeded symbol 'google_find_phdr'. Nov 20, 2019

README.md

DeepMind Lab

DeepMind Lab is a 3D learning environment based on id Software's Quake III Arena via ioquake3 and other open source software.

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

About

Disclaimer: This is not an official Google product.

If you use DeepMind Lab in your research and would like to cite the DeepMind Lab environment, we suggest you cite the DeepMind Lab paper.

You can reach us at [email protected].

Getting started on Linux

$ 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 some more 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 each bazel build, bazel test and bazel run command. The flag is omitted from the examples here for brevity, but it should be used for real training and evaluation where performance matters.

Play as a human

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 the logToStdErr setting off to disable most log output.

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

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

Train an agent

DeepMind Lab ships with an example random agent in python/random_agent.py which can be used as a starting point for implementing a learning agent. To let this agent interact with DeepMind Lab for training, run

lab$ bazel run :python_random_agent

The Python API is used for agent-environment interactions. We also provide bindings to DeepMind's "dm_env" general API for reinforcement learning, as well as a way to build a self-contained PIP package; see the separate documentation for details.

DeepMind Lab ships with different levels implementing different tasks. These tasks can be configured using Lua scripts, as described in the Lua API.

Upstream sources

DeepMind Lab is built from the ioquake3 game engine, and it uses the tools q3map2 and bspc for map creation. Bug fixes and cleanups that originate with those projects are best fixed upstream and then merged into DeepMind Lab.

  • bspc is taken from github.com/TTimo/bspc, revision d9a372db3fb6163bc49ead41c76c801a3d14cf80. There are virtually no local modifications, although we integrate this code with the main ioq3 code and do not use their copy in the deps directory. We expect this code to be stable.

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

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

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

External dependencies, prerequisites and porting notes

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

  • The zlib, glib, libxml2, jpeg and png libraries are referenced as external Bazel sources, and Bazel BUILD files are provided. The dependent code itself should be fairly portable, but the BUILD rules we ship are specific to Linux on x86. To build on a different platform you will most likely have to edit those BUILD files.

  • Message digest algorithms are included in this package (in //third_party/md), taken from the reference implementations of their respective RFCs. A "generic reinforcement learning API" is included in //third_party/rl_api, which has also been created by the DeepMind 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 at www.khronos.org/registry/EGL. The headers 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 by glib)
    • OpenGL: A hardware driver and library are needed for hardware-accelerated human play. The headless library that machine learning agents will want to use can use either hardware-accelerated rendering via EGL or GLX or software rendering via OSMesa, depending on the --define headless=... build setting.
    • Python 2.7 (other versions might work, too) with NumPy, PIL (a few tests require a NumPy version of at least 1.8), or Python 3 (at least 3.5) with NumPy and Pillow.

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

You can’t perform that action at this time.