rearrange docs

README.md

@@ -30,29 +30,106 @@ See [LICENSES.md](LICENSES.md) for information on the licenses of the individual
 
 Gym Retro requires Python 3.5 or 3.6. Please make sure to install the appropriate distribution for your OS beforehand. Please note that due to compatibility issues with some of the cores 32-bit operating systems are not supported.
 
-## Extra Prerequesites
+```sh
+pip3 install gym-retro
+```
 
-Building Gym Retro requires at least either gcc 5 or clang 3.4.
+See the section [Install Retro from source](#install-retro-from-source) if you want to build gym-retro yourself (this is generally not necessary).
 
-If you are on macOS, you need 10.11 or newer.
-Also, since LuaJIT does not work properly on macOS you must first install Lua 5.1 from homebrew:
+# Use With Gym
 
-```sh
-brew install pkg-config [email protected]
+```python
+import retro
+env = retro.make(game='AirStriker-Genesis')
 ```
 
-## Install from binary
+# Environments
 
-```sh
-pip3 install gym-retro
+What environments are there?  Note that this will display all defined environments, even ones for which ROMs are missing.
+
+```python
+import retro
+retro.data.list_games()
+```
+
+What initial states are there?
+
+```python
+import retro
+for game in retro.data.list_games():
+    print(game, retro.data.list_states(game))
+```
+
+# Replay files
+
+You can create and view replay files using the UI (Game > Play Movie...).  If you want to manage replay files in a script it looks like this:
+
+## Record
+
+```python
+import retro
+
+env = retro.make(game='AirStriker-Genesis', record='.')
+env.reset()
+while True:
+    _obs, _rew, done, _info = env.step(env.action_space.sample())
+    if done:
+        break
 ```
 
-## Install from source
+## Playback
+
+```python
+import retro
+
+movie = retro.Movie('AirStriker-Genesis-Level1-000000.bk2')
+movie.step()
+
+env = retro.make(game=movie.get_game(), state=None, use_restricted_actions=retro.Actions.ALL)
+env.initial_state = movie.get_state()
+env.reset()
+
+while movie.step():
+    keys = []
+    for p in range(movie.players):
+        for i in range(env.num_buttons):
+            keys.append(movie.get_key(i, p))
+    _obs, _rew, _done, _info = env.step(keys)
+```
+
+## Render to Video
+
+This requires ffmpeg to be installed and writes the output to the directory that the input file is located in.
+
+```python
+python -m retro.scripts.playback_movie AirStriker-Genesis-Level1-000000.bk2
+```
+
+# Integration User Interface
+
+The integration UI helps you easily find variables and see what is going on with the reward function.  Binaries for this are not currently available, so you'll have to build this from source, see [Install Retro UI from source](#install-retro-ui-from-source).
+
+# Development
+
+## Install Retro from source
+
+Building Gym Retro requires at least either gcc 5 or clang 3.4.
+
+### Prerequisites
 
 To build Gym Retro you must first install CMake.
 You can do this either through your package manager, download from the [official site](https://cmake.org/download/) or `pip3 install cmake`.
 If you're using the official installer on Windows, make sure to tell CMake to add itself to the system PATH.
 
+### Mac prerequisites
+
+If you are on macOS, you need 10.11 or newer.
+Also, since LuaJIT does not work properly on macOS you must first install Lua 5.1 from homebrew:
+
+```sh
+brew install pkg-config [email protected]
+```
+
 ### Windows prerequisites
 
 If you are not on Windows, please skip to the next section.
@@ -94,22 +171,9 @@ rm -rf .git/modules
 git submodule update --init
 ```
 
-# Use With Gym
-
-```python
-import retro
-env = retro.make(game='SonicTheHedgehog-Genesis', state='GreenHillZone.Act1')
-```
-
-# Integration User Interface
-
-The integration UI helps you easily find variables and see what is going on with the reward function.
-
-## Install from binary
-
-Binaries will be coming soon
+## Install Retro UI from source
 
-## Install from source
+First make sure you can install Retro from source, after that follow the instructions for your platform:
 
 ### macOS
 
@@ -133,65 +197,6 @@ make -j$(grep -c ^processor /proc/cpuinfo)
 
 Building from source on Windows is currently difficult to configure. Docker containers for cross-compiling are available at [openai/travis-build](https://hub.docker.com/r/openai/travis-build/).
 
-# Replay files
-
-You can create and view replay files using the UI (Game > Play Movie...).  If you want to manage replay files in a script it looks like this:
-
-## Record
-
-```python
-import retro
-
-env = retro.make(game='SonicTheHedgehog-Genesis', state='GreenHillZone.Act1', record='.')
-env.reset()
-while True:
-    _obs, _rew, done, _info = env.step(env.action_space.sample())
-    if done:
-        break
-```
-
-## Playback
-
-```python
-import retro
-
-movie = retro.Movie('SonicTheHedgehog-Genesis-GreenHillZone.Act1-0000.bk2')
-movie.step()
-
-env = retro.make(game=movie.get_game(), None, use_restricted_actions=retro.ACTIONS_ALL)
-env.initial_state = movie.get_state()
-env.reset()
-
-while movie.step():
-    keys = []
-    for i in range(env.NUM_BUTTONS):
-        keys.append(movie.get_key(i))
-    _obs, _rew, _done, _info = env.step(keys)
-```
-
-## Render to Video
-
-```python
-python scripts/playback_movie.py SonicTheHedgehog-Genesis-GreenHillZone.Act1-0000.bk2
-```
-
-# Environments
-
-What environments are there?
-
-```python
-import retro
-retro.data.list_games()
-```
-
-What initial states are there?
-
-```python
-import retro
-for game in retro.data.list_games():
-    print(game, retro.data.list_states(game))
-```
-
 # Changelog
 
 [See CHANGES.md](CHANGES.md)