Skip to content

Commit 63eef3b

Browse files
tkoeppetkoeppe
committed
Documentation update
1 parent 26576c7 commit 63eef3b

9 files changed

+1540
-2
lines changed

Diff for: ‎README.md

+149-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,150 @@
1-
# DeepMind Lab
1+
# <img src="docs/logo.png" alt="DeepMind Lab">
22

3-
A 3D learning environment.
3+
*DeepMind Lab* is a 3D learning environment based on id Software's
4+
[Quake III Arena](https://github.com/id-Software/Quake-III-Arena) via
5+
[ioquake3](https://github.com/ioquake/ioq3) and
6+
[other open source software](#upstream-sources).
7+
8+
<div align="center">
9+
<a href="https://www.youtube.com/watch?v=M40rN7afngY"
10+
target="_blank">
11+
<img src="http://img.youtube.com/vi/M40rN7afngY/0.jpg"
12+
alt="DeepMind Lab - Nav Maze Level 1"
13+
width="240" height="180" border="10" />
14+
</a>
15+
<a href="https://www.youtube.com/watch?v=gC_e8AHzvOw"
16+
target="_blank">
17+
<img src="http://img.youtube.com/vi/gC_e8AHzvOw/0.jpg"
18+
alt="DeepMind Lab - Stairway to Melon Level"
19+
width="240" height="180" border="10" />
20+
</a>
21+
<a href="https://www.youtube.com/watch?v=7syZ42HWhHE"
22+
target="_blank">
23+
<img src="http://img.youtube.com/vi/7syZ42HWhHE/0.jpg"
24+
alt="DeepMind Lab - Laser Tag Space Bounce Level (Hard)"
25+
width="240" height="180" border="10" />
26+
</a>
27+
<br /><br />
28+
</div>
29+
30+
*DeepMind Lab* provides a suite of challenging 3D navigation and puzzle-solving
31+
tasks for learning agents. Its primary purpose is to act as a testbed for
32+
research in artificial intelligence, especially deep reinforcement learning.
33+
34+
## About
35+
36+
Disclaimer: This is not an official Google product.
37+
38+
If you use *DeepMind Lab* in your research and would like to cite
39+
the *DeepMind Lab* environment, we suggest you cite
40+
the [DeepMind Lab paper](https://deepmind.com/documents/deepmind_lab.pdf).
41+
42+
You can reach us at [[email protected]](mailto:[email protected]).
43+
44+
## Getting started on Linux
45+
46+
* Get [Bazel from bazel.io](http://bazel.io/docs/install.html).
47+
48+
* Clone DeepMind Lab, e.g. by running
49+
50+
```shell
51+
$ git clone https://github.com/deepmind/lab
52+
$ cd lab
53+
```
54+
55+
* For a live example of a random agent, run
56+
57+
```shell
58+
lab$ bazel run :random_agent --define headless=false -- \
59+
--length=10000 --width=640 --height=480
60+
```
61+
62+
Here is some [more detailed build documentation](docs/build.md),
63+
including how to install dependencies if you don't have them.
64+
65+
### Play as a human
66+
67+
To test the game using human input controls, run
68+
69+
```shell
70+
lab$ bazel run :game -- --level_script tests/demo_map
71+
```
72+
73+
### Train an agent
74+
75+
*DeepMind Lab* ships with an example random agent in
76+
[`python/random_agent.py`](python/random_agent.py)
77+
which can be used as a starting point for implementing a learning agent. To let
78+
this agent interact with DeepMind Lab for training, run
79+
80+
```shell
81+
lab$ bazel run :random_agent
82+
```
83+
84+
The Python API for the agent-environment interaction is described
85+
in [docs/python_api.md](docs/python_api.md).
86+
87+
*DeepMind Lab* ships with different levels implementing different tasks. These
88+
tasks can be configured using Lua scripts,
89+
as described in [docs/lua_api.md](docs/lua_api.md).
90+
91+
-----------------
92+
93+
## Upstream sources
94+
95+
*DeepMind Lab* is built from the *ioquake3* game engine, and it uses the tools
96+
*q3map2* and *bspc* for map creation. Bug fixes and cleanups that originate
97+
with those projects are best fixed upstream and then merged into *DeepMind Lab*.
98+
99+
* *bspc* is taken from [github.com/TTimo/bspc](https://github.com/TTimo/bspc),
100+
revision e6f90a2dc02916aa2298da6ace70a8333b3f2405. There are virtually no
101+
local modifications, although we integrate this code with the main ioq3 code
102+
and do not use their copy in the `deps` directory. We expect this code to be
103+
stable.
104+
105+
* *q3map2* is taken from
106+
[github.com/TTimo/GtkRadiant](https://github.com/TTimo/GtkRadiant),
107+
revision 8557f1820f8e0c7cef9d52a78b2847fa401a4a95. A few minor local
108+
modifications add synchronization and use C99 constructs to replace
109+
formerly non-portable or undefined behaviour. We also expect this code to be
110+
stable.
111+
112+
* *ioquake3* is taken from
113+
[github.com/ioquake/ioq3](https://github.com/ioquake/ioq3),
114+
revision 1c1e1f61f180596c925a4ac0eddba4806d1369cd. The code contains extensive
115+
modifications and additions. We aim to merge upstream changes occasionally.
116+
117+
We are very grateful to the maintainers of these repositories for all their hard
118+
work on maintaining high-quality code bases.
119+
120+
## External dependencies, prerequisites and porting notes
121+
122+
*DeepMind Lab* currently ships as source code only. It depends on a few external
123+
software libraries, which we ship in several different ways:
124+
125+
* The `zlib`, `glib`, `libxml2`, `jpeg` and `png` libraries are referenced as
126+
external Bazel sources, and Bazel BUILD files are provided. The dependent
127+
code itself should be fairly portable, but the BUILD rules we ship are
128+
specific to Linux on x86. To build on a different platform you will most
129+
likely have to edit those BUILD files.
130+
131+
* Message digest algorithms are included in this package (in
132+
[`//third_party/md`](third_party/md)), taken from the reference
133+
implementations of their respective RFCs. A "generic reinforcement learning
134+
API" is included in [`//third_party/rl_api`](third_party/rl_api), which has
135+
also been created by the *DeepMind Lab* authors. This code is portable.
136+
137+
* Several additional libraries are required but are not shipped in any form;
138+
they must be present on your system:
139+
* SDL 2
140+
* Lua 5.1 (later versions might work, too)
141+
* gettext (required by `glib`)
142+
* OpenGL: a hardware driver and library are needed for hardware-accelerated
143+
human play, and OSMesa is required for the software-rendering, headless
144+
library that machine learning agents will want to use.
145+
* Python 2.7 (other versions might work, too)
146+
147+
The build rules are using a few compiler settings that are specific to GCC. If
148+
some flags are not recognized by your compiler (typically those would be
149+
specific warning suppressions), you may have to edit those flags. The warnings
150+
should be noisy but harmless.

Diff for: ‎docs/build.md

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
(Switch to: [Lua](lua_api.md) &middot; [Python](python_api.md) &middot;
2+
[Level Generation](level_generation.md) &middot;
3+
[Tensor](tensor.md) &middot; [Text Levels](text_level.md) &middot;
4+
Build &middot;
5+
[Known Issues](issues.md))
6+
7+
# How to build *DeepMind Lab*
8+
9+
*DeepMind Lab* uses [Bazel](https://www.bazel.io/) as its build system. Its main
10+
`BUILD` file defines a number of *build targets* and their dependencies. The
11+
build rules should work out of the box on Debian (Jessie or newer) and Ubuntu
12+
(version 14.04 or newer), provided the required packages are installed.
13+
*DeepMind Lab* also builds on other Linux systems, but some changes to the build
14+
files might be required, see below.
15+
16+
*DeepMind Lab* is written in C99 and C++11, and you will need a sufficiently
17+
modern compiler. GCC 4.8 should suffice.
18+
19+
### Step-by-step instructions for Debian or Ubuntu
20+
21+
Tested on Debian 8.6 (Jessie) and Ubuntu 14.04 (Trusty) and newer.
22+
23+
1. Install Bazel by adding a custom APT repository, as described
24+
[on the Bazel homepage](http://bazel.io/docs/install.html#ubuntu) or using
25+
an [installer](https://github.com/bazelbuild/bazel/releases).
26+
This should also install GCC and zip.
27+
28+
2. Install *DeepMind Lab*'s dependencies:
29+
30+
```shell
31+
$ sudo apt-get install lua5.1 liblua5.1-0-dev libffi-dev gettext \
32+
freeglut3-dev libsdl2-dev libosmesa6-dev python-dev python-numpy
33+
```
34+
35+
3. [Clone or download *DeepMind Lab*](https://github.com/deepmind/lab).
36+
37+
4. Build *DeepMind Lab* and run a random agent:
38+
39+
```shell
40+
$ cd lab
41+
# Build the Python interface to DeepMind Lab with OpenGL
42+
lab$ bazel build :deepmind_lab.so --define headless=glx
43+
# Build and run the tests for it
44+
lab$ bazel run :python_module_test --define headless=glx
45+
# Rebuild the Python interface in non-headless mode and run a random agent
46+
lab$ bazel run :random_agent --define headless=false
47+
```
48+
49+
The Bazel target `:deepmind_lab.so` builds the Python module that interfaces
50+
*DeepMind Lab*. It can be build in headless hardware rendering mode (`--define
51+
headless=glx`), headless software rendering mode (`--define headless=osmesa`) or
52+
non-headless mode (`--define headless=false`).
53+
54+
The random agent target `:random_agent` has a number of optional command line
55+
arguments. Run
56+
57+
``` shell
58+
lab$ bazel run :random_agent -- --help
59+
```
60+
61+
to see those.
62+
63+
### Building on Red Hat Enterprise Linux Server
64+
65+
Tested on release 7.2 (Maipo).
66+
67+
1. Add the Extra Packages as described on
68+
[fedoraproject.org](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F)
69+
2. Install Bazel's and DeepMind Lab's dependencies
70+
71+
```shell
72+
sudo yum -y install unzip java-1.8.0-openjdk lua lua-devel libffi-devel zip \
73+
java-1.8.0-openjdk-devel gcc gcc-c++ freeglut-devel SDL2 SDL2-devel \
74+
mesa-libOSMesa-devel python-devel numpy
75+
```
76+
3. Download and run
77+
a [Bazel binary installer](https://github.com/bazelbuild/bazel/releases),
78+
e.g.
79+
80+
```shell
81+
sudo yum -y install wget
82+
wget https://github.com/bazelbuild/bazel/releases/download/0.3.2/bazel-0.3.2-installer-linux-x86_64.sh
83+
sh bazel-0.3.2-installer-linux-x86_64.sh
84+
```
85+
4. [Clone or download *DeepMind Lab*](https://github.com/deepmind/lab).
86+
5. Edit `lua.BUILD` to reflect how Lua is installed on your system:
87+
88+
```python
89+
cc_library(
90+
name = "lua",
91+
linkopts = ["-llua"],
92+
visibility = ["//visibility:public"],
93+
)
94+
```
95+
The output of `pkg-config lua --libs --cflags` might be helpful to find the
96+
right include folders and linker options.
97+
6. Build *DeepMind Lab* using Bazel as above.
98+
99+
### Building on SUSE Linux
100+
101+
Tested on SUSE Linux Enterprise Server 12.
102+
103+
1. Install Bazel's and DeepMind Lab's dependencies
104+
105+
```shell
106+
sudo zypper --non-interactive install java-1_8_0-openjdk \
107+
java-1_8_0-openjdk-devel gcc gcc-c++ lua lua-devel python-devel \
108+
python-numpy-devel libSDL-devel libOSMesa-devel freeglut-devel
109+
```
110+
2. Download and run
111+
a [Bazel binary installer](https://github.com/bazelbuild/bazel/releases),
112+
e.g.
113+
114+
```shell
115+
sudo yum -y install wget
116+
wget https://github.com/bazelbuild/bazel/releases/download/0.3.2/bazel-0.3.2-installer-linux-x86_64.sh
117+
sh bazel-0.3.2-installer-linux-x86_64.sh
118+
```
119+
3. [Clone or download *DeepMind Lab*](https://github.com/deepmind/lab).
120+
4. Edit `lua.BUILD` to reflect how Lua is installed on your system:
121+
122+
```python
123+
cc_library(
124+
name = "lua",
125+
linkopts = ["-llua"],
126+
visibility = ["//visibility:public"],
127+
)
128+
```
129+
The output of `pkg-config lua --libs --cflags` might be helpful to find the
130+
right include folders and linker options.
131+
5. Edit `python.BUILD` to reflect how Python is installed on your system:
132+
133+
```python
134+
cc_library(
135+
name = "python",
136+
hdrs = glob([
137+
"include/python2.7/*.h",
138+
"lib64/python2.7/site-packages/numpy/core/include/**/*.h",
139+
]),
140+
includes = [
141+
"include/python2.7",
142+
"lib64/python2.7/site-packages/numpy/core/include",
143+
],
144+
visibility = ["//visibility:public"],
145+
)
146+
```
147+
The outputs of `rpm -ql python` and `rpm -ql python-numpy-devel` might be
148+
helpful to find the rihgt include folders.
149+
6. Build *DeepMind Lab* using Bazel as above.

Diff for: ‎docs/issues.md

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
(Switch to: [Lua](lua_api.md) &middot; [Python](python_api.md) &middot;
2+
[Level Generation](level_generation.md) &middot;
3+
[Tensor](tensor.md) &middot; [Text Levels](text_level.md) &middot;
4+
[Build](build.md) &middot;
5+
Known Issues)
6+
7+
# Known Issues
8+
9+
Please take note of the following subtleties when modifying *DeepMind Lab* or
10+
adapting it to different platforms.
11+
12+
## Scripting
13+
14+
* Server and client run at different frame rates. This causes a mismatch when
15+
rewards that are given by scripts are eventually received by players.
16+
* The script supports fractional rewards, but the engine does not. This means
17+
that only integer changes in reward are consumed by the agent.
18+
* The script API is currently designed to work with single-player levels.
19+
20+
## Compiling
21+
22+
* The LCC bytecode compiler has its own pointer representation (32 bits), which
23+
may differ from the host's pointer representation. Arguments of trap calls
24+
need to be translated properly at the VM's syscall boundary.
25+
* The order in which `.asm` files are linked into `.qvm` bytecode libraries is
26+
important. The current order is taken from ioq3's original `Makefile`.
27+
* OSMesa must be compiled without thread-local storage (TLS) if the environment
28+
is to be loaded from a shared library repeatedly (e.g. via `dlopen`).
29+
* Loading *DeepMind Lab* repeatedly from a shared library may be the only way to
30+
reliably instantiate multiple copies of the environment in the same process,
31+
since the original ioq3 game engine was not designed as a library and is
32+
effectively not reentrant (e.g. it has a lot of global state and global
33+
initialization).
34+
* The SDL library cannot be linked statically, since its sound subsystem does
35+
not shut down cleanly. Linking SDL from a shared object works (as we do for
36+
the freestanding game binary), as does disabling sound altogether (as we do
37+
for the library version).
38+
39+
## Threading
40+
41+
The environments are thread compatible but not thread safe. A call to one
42+
environment will not interfere with a call to another but calls to the same
43+
environment from different threads at the same time may interfere.
44+
45+
Individual render modes have their own special exceptions:
46+
47+
* Software rendering - The environment is fully thread compatible.
48+
* Hardware rendering - The environment can be only called from the *same*
49+
thread in which it was constructed.
50+
* SDL rendering - The environment can only be called from the main thread.

Diff for: ‎docs/level_generation.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
(Switch to: [Lua](lua_api.md) &middot; [Python](python_api.md) &middot;
2+
Level Generation &middot;
3+
[Tensor](tensor.md) &middot; [Text Levels](text_level.md) &middot;
4+
[Build](build.md) &middot;
5+
[Known Issues](issues.md))
6+
7+
# Level generation
8+
9+
Levels for DeepMind Lab are _Quake III Arena_ levels. They are packaged into `.pk3`
10+
files (which are ZIP files) and consist of a number of components, including the
11+
following:
12+
13+
* One `.bsp` file per level ("binary space partitioning"). This contains the
14+
level geometry (the "map").
15+
* Optionally an accompanying `.aas` file per level ("area awareness system").
16+
This contains navigation information for the in-game bots of _Quake III
17+
Arena_.
18+
* Textures. Textures are referenced by maps. DeepMind Lab ships with a number
19+
of default textures.
20+
21+
You can use your own maps, zipped up as a `.pk3` file, by placing the `.pk3`
22+
file(s) into your base directory (e.g. `$HOME/.deepmind_lab/baselab`).
23+
24+
DeepMind Lab includes tools to generate maps: The `q3map2` tool converts a
25+
`.map` file into a `.bsp` file, and the `bspc` tool generates an `.aas` file
26+
from a `.bsp` file. The `.map` format is a human-readable text format that
27+
describes a map as a sequence of _entities_. Map files are cumbersome to edit by
28+
hand, but a variety of level editors are freely available
29+
(e.g. [GtkRadiant](https://github.com/TTimo/GtkRadiant)).
30+
31+
In addition to built-in and user-provided levels, DeepMind Lab offers additional
32+
sources of levels:
33+
34+
* Procedurally generated levels, which are created on the fly.
35+
* [Text levels](text_level.md), which are simple, human-readable text files
36+
that can be compiled into `.map` files. This can either be done offline,
37+
or programmatically inside DeepMind Lab using Lua extensions.

Diff for: ‎docs/logo.png

32 KB
Loading

0 commit comments

Comments
 (0)