Merge branch 'feature/doc' into develop

# Conflicts:
#	debian/control
#	doc/BUILD.md
#	doc/RUN.md

README.md

@@ -23,6 +23,7 @@ Note that, while these are actual screenshots of V-Gears, none of the images, sp
 |[<img src="https://v-gears.inigovalentin.com/img/screenshot/transparent_dialogs.png" alt="Transparency" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/transparent_dialogs.png "Transparency")|[<img src="https://v-gears.inigovalentin.com/img/screenshot/timers.png" alt="Timers" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/timers.png "Timers")|[<img src="https://v-gears.inigovalentin.com/img/screenshot/choices.png" alt="Choices" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/choices.png "Choices")|
 
 ### Battle:
+<!-- TODO(review): update the battle screenshots and the GIF: new battle UI, floating damage numbers and the spell effects (Fire, Ice, Bolt, Cure) from v0.3.0. -->
 |**Battle UI**|**Battle Flow**|
 |--|--|
 |[<img src="https://v-gears.inigovalentin.com/img/screenshot/battle.png" alt="Battle UI" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/battle.png "Battle UI")|[<img src="https://v-gears.inigovalentin.com/img/screenshot/battle.gif" alt="Battle Flow" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/battle.gif "Battle Flow")|
@@ -36,7 +37,10 @@ Note that, while these are actual screenshots of V-Gears, none of the images, sp
 |**Materia**|||
 |[<img src="https://v-gears.inigovalentin.com/img/screenshot/materia_menu.png" alt="Materia Menu" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/materia_menu.png "Materia Menu")|[<img src="https://v-gears.inigovalentin.com/img/screenshot/save_menu.png" alt="Save Menu" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/save_menu.png "Save Menu")||
 
+<!-- TODO(review): add screenshots of the new menus: Status, Magic, Limit, PHS, Config and Quit. The Save menu image sits in the Materia row; check the layout. -->
+
 ### Installer:
+<!-- TODO(review): the installer has changed (presets, audio tool detection, Verify install, Launch game, battle options). Update both screenshots. -->
 |**Installer**|**Advanced**|
 |--|--|
 |[<img src="https://v-gears.inigovalentin.com/img/screenshot/installer.png" alt="Installer" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/installer.png "Installer")|[<img src="https://v-gears.inigovalentin.com/img/screenshot/installer_advanced.png" alt="Advanced options" width="250"/>](https://v-gears.inigovalentin.com/img/screenshot/installer_advanced.png "Advanced options")|
@@ -53,18 +57,21 @@ Well, let's call it a work in progress... of a work in progress.
 |**<span style='color:#22aa22;'>Things that work</span>**|**<span style='color:#aa2222;'>Things that don't</span>**|
 |:--:|:--:|
 |A few field maps|Most field maps|
-|Some menus|Some other menus|
-|Sound (mostly)|Battle mechanics.|
-|Saving / Loading|The world map, also in general|
-|Timers|Minigames|
-| |Party switching|
-| |Shops|
+|Most menus (main, items, equip, materia, status, magic, limit, PHS, config, save, quit)|Some other menus|
+|Sound (mostly)|Battle mechanics (they are only partly implemented)|
+|Videos|The world map, also in general|
+|Saving / Loading, and settings|Minigames|
+|Timers|Party switching|
+|Battles, with the original data, models, animations and some spell effects|Shops|
 | |Alternate controllable characters|
 | |Many other things|
 
+<!-- TODO(review): this table is my reading of the commits up to v0.3.0 (menus overhaul, video playback, battle data and effects). Check each row against the actual state of the game. -->
+
 
 If the question was "How deep into the game can I play?", then the answer is
 
+<!-- TODO(review): check whether the furthest point you can reach has changed with the latest versions, and update this screenshot and the text below it. -->
 [<img src="https://v-gears.inigovalentin.com/img/screenshot/max_progress.png" alt="Max progress" width="450"/>](https://v-gears.inigovalentin.com/img/screenshot/max_progress.png "Max progress")
 
 Until there. Whitout cheats, and without using the developer console, it's not possible to get to the next wagon. The dialogs start looping there.

doc/BUILD.md

@@ -1,28 +1,17 @@
 # <img src="../v-gears.png" alt="V-Gears" width="50"/> V-Gears Building Guide
 
 ## Install dependencies
-If you are runind Debian (or derivates), you can install the required dependencies by running as root
+If you are running Debian (or derivates), you can install the required dependencies by running as root
 
 ```bash
 apt install g++ cmake libqt5widgets5 qtbase5-dev zlib1g-dev libarchive-dev libogre-1.12-dev libois-dev libvorbis-dev libboost-dev libboost-program-options-dev libboost-test-dev libboost-filesystem-dev libboost-thread-dev libopenal-dev libtinyxml-dev libluajit-5.1-dev
 ```
 
-## Deterministic fallbacks
-
-The CMake scripts include an option `USE_DETERMINISTIC_FALLBACKS` (default `ON`).
-- When `ON`, CMake will attempt pragmatic fallbacks to find libraries when
-	`find_package`/pkg-config do not succeed (SONAME `find_library` passes,
-	appending common `/usr/lib` paths, or injecting generic `-lboost_*` flags).
-- When `OFF`, CMake will not perform these fallbacks; instead require proper
-	dev packages or explicit hints.
-
-**Leave it `ON` for now.** On Linux, the regular library detection in `src/CMakeLists.txt` is skipped because of a
-known bug in the script, so with the fallbacks `OFF` the build fails to link Boost and OgreBites.
-
-If you see warnings about missing Boost or OgreBites, prefer installing the
-appropriate `-dev` packages listed above, or point CMake at your OGRE/Boost
-installation with `-DOGRE_ROOT=...` and `-DBoost_DIR=...`/`-DBoost_LIBRARY_DIRS`.
+The data installer also needs FFmpeg and TiMidity (see [Optional programs](#optional-programs)).
 
+```bash
+apt install ffmpeg timidity
+```
 
 ## Build using CMake
 
@@ -35,18 +24,20 @@ cmake ../;
 make;
 ```
 
-If you want to speed it up a bit (it can take several minutes, depending on your system), you can add the parameter `-j` to make to use multiple threads. For instance, `make -j3` will use three cores for the compilation.
+If you want to speed it up a bit (it can take several minutes, depending on your system), you can add the parameter `-j` to make to use multiple threads. For instance, `make -j3` will use three cores for the compilation. The build uses a lot of memory, so on machines with little RAM, use a low number (`-j2`).
 
-Once the build process finishes, you u sholh have the following files (from the project directory):
+Once the build process finishes, you should have the following files (from the project directory):
 
 - `build/bin/v-gears`, the engine executable.
 - `build/bin/v-gears-installer`, the data installer.
 
+If you build with `-DCMAKE_BUILD_TYPE=Debug`, they are in `build/bin_debug/` instead.
+
 The engine can be launched from anywhere: it finds its data directory (`~/.v-gears/` by default) and fills it from the `data/` folder of the repository the first time. See the [run guide](RUN.md "Run V-Gears") for details.
 
 ## Run the tests (optional)
 
-The tests are not built by default. To build and run the tests of the installer logic (the option rules, the installation layout, the verifier, the log and the tool finder), which don't need the rest of the engine:
+The tests are not built by default. To build and run the tests of the installer logic (the option rules, the installation layout, the verifier, the log, the tool finder and the movie camera data) and of the data directory and Ogre plugin lookup, which don't need the rest of the engine:
 
 ```bash
 mkdir build-tests;
@@ -56,6 +47,10 @@ make v-gears-installer-tests;
 ./bin/v-gears-installer-tests
 ```
 
+The engine tests (for example the movie state and camera frames) are in the `v-gears-tests` target, built the same way.
+
+<!-- TODO(review): check that `make v-gears-tests` builds on its own and whether more build dependencies (video, audio) are required now. -->
+
 ## Make packages (optional)
 
 V-Gears can be packaged for Linux as a `.deb` package and as a `.tar.gz` archive. None of them includes data from the original game: the player still needs the data installer and their own copy of the game.
@@ -72,7 +67,7 @@ make -j4 v-gears v-gears-installer;
 cpack;
 ```
 
-The first build takes a while. Adjust `-j` to the number of cores and the memory of your system: each compiler process can use a lot of memory, so don't go as high as the number of cores if memory is short.
+The first build takes a while. Adjust `-j` as explained in [Build using CMake](#build-using-cmake).
 
 When `cpack` finishes, `build-release/` contains:
 
@@ -89,15 +84,15 @@ Both have the same files:
 - `bin/v-gears` and `bin/v-gears-installer`, the engine and the data installer.
 - `share/v-gears/`, the V-Gears data files (configuration, scripts, screens, fonts...). The engine copies them to the user's data directory (`~/.v-gears/`) the first time it runs, and the data installer adds the game data there.
 - `share/doc/v-gears/`, the documentation and the license.
-- The desktop files and the icons, so both programs show in the applications menu.
+- `share/applications/` and `share/icons/`, the desktop files and the icons.
 
-The `.deb` installs them under `/usr`. Install it with `apt`, so it installs the dependencies too:
+The `.deb` installs them under `/usr`, so both programs show in the applications menu. Install it with `apt`, so it installs the dependencies too:
 
 ```bash
-sudo apt install ./v-gears_0.3.0_amd64.deb
+sudo apt install ./v-gears_<version>_amd64.deb
 ```
 
-The `.tar.gz` has the same layout in a single folder. It can be extracted anywhere and run from there (`bin/v-gears`, `bin/v-gears-installer`), without root.
+The `.tar.gz` has the same layout in a single folder. It can be extracted anywhere and run from there (`bin/v-gears`, `bin/v-gears-installer`), without root. It doesn't add anything to the applications menu.
 
 The Ogre plugins (`RenderSystem_GL`, `Codec_STBI`) are not in the packages: the engine loads the ones of the system's Ogre.
 
@@ -107,27 +102,52 @@ The packages don't include any library: they use the ones installed in the syste
 
 To make packages for a given distribution, build them in that distribution, for example in a container or a virtual machine. The `.tar.gz` has the same limits, but it gives no warning: if a library is missing, the programs don't start.
 
-### Build options
+### Packaging options
 
 These can be set when running `cmake` (`-D<option>=<value>`):
 
 |Option|Default|Description|
 |--|--|--|
-|`CMAKE_BUILD_TYPE`|`Release`|Use `Release` for packages. A `Debug` build makes much larger programs, and its archive name ends in `-debug`.|
+|`CMAKE_BUILD_TYPE`|`Release`|Use `Release` for packages. With `Debug`, the programs are slower and the archive name ends in `-debug`.|
 |`VGEARS_OGRE_PLUGIN_DIR`|Found at build time|Directory of the system's Ogre plugins. The engine looks for the plugins there after its data directory and its own directory. Set it if the plugins of the target system are in another place.|
 |`VGEARS_PACKAGE_MAINTAINER`|The project maintainer|Name and email of the maintainer in the `.deb`.|
 
 ### Install without a package
 
-To install V-Gears directly in the system, with the same files and layout as the packages:
+To install V-Gears directly in the system, with the same files and layout as the packages, run this from the build directory:
 
 ```bash
 sudo cmake --install . --prefix /usr/local
 ```
 
+## Advanced build options
+
+### Deterministic fallbacks
+
+You don't need this for a normal build. It only matters if CMake can't find a library that is installed.
+
+The CMake scripts include an option `USE_DETERMINISTIC_FALLBACKS` (default `ON`).
+- When `ON`, CMake will attempt pragmatic fallbacks to find libraries when
+	`find_package`/pkg-config do not succeed (SONAME `find_library` passes,
+	appending common `/usr/lib` paths, or injecting generic `-lboost_*` flags).
+- When `OFF`, CMake will not perform these fallbacks; instead require proper
+	dev packages or explicit hints.
+
+**Leave it `ON` for now, also for packages.** On Linux, the regular library detection in `src/CMakeLists.txt` is skipped because of a known bug in the script, so with the fallbacks `OFF` the build fails to link Boost and OgreBites.
+
+If you see warnings about missing Boost or OgreBites, prefer installing the
+appropriate `-dev` packages listed above, or point CMake at your OGRE/Boost
+installation with `-DOGRE_ROOT=...` and `-DBoost_DIR=...`/`-DBoost_LIBRARY_DIRS`.
+
 ## Optional programs
 
-To convert the sound effects and the music, the installer uses FFmpeg and TiMidity. They are not needed to build V-Gears, only to install the data. See the [data installation guide](INSTALL_DATA.md "Install Data").
+To convert the sound effects, the music and the videos, the installer uses FFmpeg and TiMidity. They are not needed to build V-Gears, only to install the data. In Debian (or derivates):
+
+```bash
+apt install ffmpeg timidity
+```
+
+See the [data installation guide](INSTALL_DATA.md "Install Data").
 
 ## Next steps
 

doc/HISTORY.md

@@ -32,7 +32,7 @@ A couple of months later, Halkun resigned as project leader<sup>[5](#####[5]])</
 
 ---
 
-##2007 - 2012 The Project Continues.
+## 2007 - 2012 The Project Continues.
 
 Still, the project kept on growing and advancing. Akari was still doing most of the contributions, and took an unofficial role of project leader. Over the years, the engine was playable, and Final Fantasy VII could, to an extent, actually be played on Q-Gears. Work was getting done, new things were being implemented, corners were being polished.
 
@@ -42,7 +42,7 @@ Eventually, it seems Akari himself started loosing interest in the project. The
 
 ---
 
-##2015 - A New Hope.
+## 2015 - A New Hope.
 
 The project, seemingly dead, received a new impulse in 2015, thanks to paulsapps<sup>[6](#####[6]])</sup>. He was not, as far as I'm aware, a member of Qhimm Forums, but he took an interest on the project. He modernized the codebase, fixed many errors, and more importantly, developed a series of very usefull tools, the most remarkable one being SUDM<sup>[7](#####[7]])</sup>, which allowed to easily import data to Q-Gears and to reimplement field scripts.
 
@@ -50,7 +50,7 @@ That same year, apparently paulsapps started it's own fork of Q-Gears: 7-Gears<s
 
 ---
 
-##2022 - V-Gears.
+## 2022 - V-Gears.
 
 2022 is when I<sup>[9](#####[8]])</sup> found out about Q-Gears. I really loved the idea, and it made me sad that the project had died. So I started reading, trying to understand the code base and the ins and outs of the game. 
 
@@ -60,7 +60,9 @@ The next step was to modernize the code base. I made some fixes here and there,
 
 Then, I set out to do what I thougth was the number one priority, and fix what I personally thing was one of the main reasons the project had died: The lack of documentation. Slowly but steadly, I went through the entire code base, documenting every class, every function, every piece of code. I added whatever documents I had about the game formats and files. I added a project history, a usefull README, building instructions...
 
-As of yet, I have added no new functionalities to the engine itself.
+For a while, I added no new functionalities to the engine itself. That changed after the cleanup was done. Since then V-Gears has gained, among other things, a rewritten data installer (with ISO reading, verification, and FFmpeg / TiMidity detection), playback of the original videos, a shared menu library with most of the game menus, saving and loading of games and settings, and a battle system with the original battle data, models, animations and spell effects.
+
+<!-- TODO(review): the history above is a short summary of versions 0.1 to 0.3.0; expand or reword it in your own voice. -->
 
 ---
 
@@ -76,13 +78,13 @@ And maybe, one day we can play our favourite game over an engine called Somethin
 
 ### References:
 
-#####[1] Halkun profile on Qhimm Forums: [https://forums.qhimm.com/index.php?action=profile;u=109](https://forums.qhimm.com/index.php?action=profile;u=109)
-#####[2] Q-Gears presentation post on Qhimm Forums: [https://forums.qhimm.com/index.php?topic=5556.0](https://forums.qhimm.com/index.php?topic=5556.0)
-#####[3] Akari profile on Qhimm Forums: [https://forums.qhimm.com/index.php?action=profile;u=1266](https://forums.qhimm.com/index.php?action=profile;u=1266)
-#####[4] Akari's fork announcement on Qhimm Forums: [https://forums.qhimm.com/index.php?topic=6829.0](https://forums.qhimm.com/index.php?topic=6829.0)
-#####[5] Halkun's resignation: [https://forums.qhimm.com/index.php?topic=6963.0](https://forums.qhimm.com/index.php?topic=6963.0)
-#####[6] paulsapps's profile on GitHub: [https://github.com/paulsapps](https://github.com/paulsapps)
-#####[7] SUDM repository on GitHub: [https://github.com/paulsapps/SUDM/](https://github.com/paulsapps/SUDM/)
-#####[8] 7-Gears repository on GitHub: [https://github.com/paulsapps/7-Gears](https://github.com/paulsapps/7-Gears)
-#####[9] Iñigo Valentin's profile on GitHub: [https://github.com/InigoValentin](https://github.com/InigoValentin)
-#####[9] V-Gears repository on GitHub: [https://github.com/InigoValentin/V-Gears](https://github.com/InigoValentin/V-Gears)
+##### [1] Halkun profile on Qhimm Forums: [https://forums.qhimm.com/index.php?action=profile;u=109](https://forums.qhimm.com/index.php?action=profile;u=109)
+##### [2] Q-Gears presentation post on Qhimm Forums: [https://forums.qhimm.com/index.php?topic=5556.0](https://forums.qhimm.com/index.php?topic=5556.0)
+##### [3] Akari profile on Qhimm Forums: [https://forums.qhimm.com/index.php?action=profile;u=1266](https://forums.qhimm.com/index.php?action=profile;u=1266)
+##### [4] Akari's fork announcement on Qhimm Forums: [https://forums.qhimm.com/index.php?topic=6829.0](https://forums.qhimm.com/index.php?topic=6829.0)
+##### [5] Halkun's resignation: [https://forums.qhimm.com/index.php?topic=6963.0](https://forums.qhimm.com/index.php?topic=6963.0)
+##### [6] paulsapps's profile on GitHub: [https://github.com/paulsapps](https://github.com/paulsapps)
+##### [7] SUDM repository on GitHub: [https://github.com/paulsapps/SUDM/](https://github.com/paulsapps/SUDM/)
+##### [8] 7-Gears repository on GitHub: [https://github.com/paulsapps/7-Gears](https://github.com/paulsapps/7-Gears)
+##### [9] Iñigo Valentin's profile on GitHub: [https://github.com/InigoValentin](https://github.com/InigoValentin)
+##### [10] V-Gears repository on GitHub: [https://github.com/InigoValentin/V-Gears](https://github.com/InigoValentin/V-Gears)

doc/INSTALL.md

@@ -2,7 +2,7 @@
 
 ## Manual installation
 
-The data installer can do this for you: enable "Copy V-Gears data files" in its advanced options and it copies the `data/` folder of the repository to the installation directory. To do it by hand:
+The data installer can do this for you: enable "Copy V-Gears data files" in its advanced options and it copies the `data/` folder of the repository (`share/v-gears/` in an installed package) to the installation directory. To do it by hand:
 
 1. Create a folder for V-Gears data, outside the project. In Linux-based systems, it's recommended to use `~/.v-gears/`.
 2. Copy all the contents of the `data/` folder of the repository to the newly created directory. It should end up like this:

doc/INSTALL_DATA.md

@@ -8,9 +8,9 @@ If you also want the videos, you need the ISO images of the PC game disks 1, 2 a
 
 ## FFmpeg and TiMidity
 
-The installer converts the sound effects and the music to `.ogg` files with two external programs:
+The installer converts the sound effects, the music and the videos with two external programs (the videos only need FFmpeg):
 
-- [FFmpeg](https://ffmpeg.org/download.html "FFmpeg") converts the sound effects and encodes the music.
+- [FFmpeg](https://ffmpeg.org/download.html "FFmpeg") converts the sound effects, encodes the music and converts the videos.
 - [TiMidity](https://timidity.sourceforge.net/#download "TiMidity") plays the original MIDI music so FFmpeg can encode it. Only the music needs it.
 
 You don't have to configure anything if they are installed. The installer looks for them, in this order:
@@ -26,7 +26,7 @@ If a program that the installation needs is missing, the installer tells you bef
 - **Locate…** the program in your system.
 - **Get it…**: open its download page.
 - **Check again**, for when you have just installed it.
-- **Continue without** it. The rest is installed normally, and the sound effects, the music, or both are left out. The extracted `.wav` and `.mid` files stay in `~/.v-gears/data/audio/`, and the indexes only list the files that exist.
+- **Continue without** it. The rest is installed normally, and the sound effects, the music, the videos, or any of them, are left out. The extracted `.wav` and `.mid` files stay in `~/.v-gears/data/audio/`, and the indexes only list the files that exist.
 - **Cancel** the installation.
 
 To add the missing audio later, install the programs and run the installer again with only the sound effects and the music selected (the *Media only* option, or *Custom*).
@@ -45,7 +45,7 @@ It can be started from any directory. When the installation starts, it works fro
 
 1. In **Import data source**, select the ISO image of the install disk. The installer tells you if the image is valid.
 2. In **VGears installation directory**, select where to install, for example `~/.v-gears/`. It will be created if it doesn't exist. It holds the configuration and the converted data, and it is where the game runs.
-3. (Optional) Select **Show advanced options** to choose what to install (see below). The defaults install everything. If the directory doesn't have the V-Gears files yet (configuration, scripts, screens, fonts...), leave **Copy V-Gears data files** checked, and the installer copies them there from the `data/` folder of the repository.
+3. (Optional) Select **Show advanced options** to choose what to install (see below). The defaults install everything. If the directory doesn't have the V-Gears files yet (configuration, scripts, screens, fonts...), leave **Copy V-Gears data files** checked, and the installer copies them there from the `data/` folder of the repository (`share/v-gears/` in an installed package). The engine also copies them by itself the first time it runs.
 4. Click **Install data**.
 
 Before extracting anything, the installer checks that everything is in place: that the ISO is valid, that the directory is writable and has enough free space (about 3 GB plus the size of the ISO), and that the FFmpeg and TiMidity programs it needs can be used (see below). If something is wrong it tells you and doesn't start.
@@ -63,7 +63,15 @@ When it finishes:
 
 The videos are not on the install disk, but on the PC game disks 1, 2 and 3. To get them, run the installer once for each disk: select the disk's ISO as the data source and the same installation directory, and click 'Install data'. The installer detects a game disk, extracts only its videos to `<installation directory>/data/video/` and doesn't touch anything else. Several disks have the same videos, so those already installed are skipped. Unlike the full installation, it can be repeated with the same installer window.
 
-The videos are copied as they are (AVI files with the Duck TrueMotion 2 codec, which FFmpeg can decode). V-Gears doesn't play them yet.
+The engine can't decode the original AVI files (Duck TrueMotion 2 codec), so the installer uses FFmpeg to convert each video to a folder of JPEG frames, an `.ogg` sound track (if the video has sound) and a `movie.xml` with the frame count and frame rate. Movies that carry camera data for the field background also get a `camera.cam` file. They are played by the engine's movie player, which draws the frames and plays the sound. FFmpeg is therefore needed to install the videos.
+
+<!-- TODO(review): confirm the exact output layout under data/video/ (folder per movie, file names) after a fresh install, and which movies play in game. -->
+
+## Battle data
+
+The battle installation extracts the battle scenes, enemy and formation data, the attacks, the field and world map encounter tables, and the battle models and animations. It also extracts the visual assets of the spell effects (`magic.lgp`): the meshes and textures of the effects and the sprite lists, which the battle scripts use to recreate the original spell effects. If you installed before these were added, run the installer again with the battle options selected (*Battle* preset or *Custom*) to get them.
+
+<!-- TODO(review): list of spells with effects (currently the Fire, Ice, Bolt and Cure families) and the reinstall requirement should be re-checked against the current state of battle_fx.lua. -->
 
 ## Advanced options
 

doc/RUN.md

@@ -1,8 +1,8 @@
-# <img src="../v-gears.png" alt="V-Gears" width="50"/> V-Gears Data Run Guide
+# <img src="../v-gears.png" alt="V-Gears" width="50"/> V-Gears Run Guide
 
 ## Run the engine
 
-If you have followed the [build](BUILD.md "Building guide") and [installaton](INSTALL.md "Installation guide") guides, you'll have the game data installed to `~/.v-gears/`, and the binaries compilled somewhere (we'll assum they are in `~/V-Gears/build/bin`, change the directories according to your system).
+If you have followed the [build](BUILD.md "Building guide") and [installation](INSTALL.md "Installation guide") guides, you'll have the game data installed to `~/.v-gears/`, and the binaries compiled somewhere (we'll assume they are in `~/V-Gears/build/bin`, change the directories according to your system).
 
 Run the engine from any directory:
 
@@ -10,6 +10,8 @@ Run the engine from any directory:
 ~/V-Gears/build/bin/v-gears
 ```
 
+If you installed V-Gears from a package, run `v-gears`, or start it from the applications menu.
+
 The engine looks for its data directory in this order, and changes into it:
 
 1. The directory given with `--data-dir`, for example `v-gears --data-dir ~/games/v-gears`.
@@ -21,21 +23,32 @@ If the chosen directory doesn't have the V-Gears files yet, the engine copies th
 
 The data installer also has a **Launch game** button, which starts the engine with the installation directory.
 
-## Key Mappings
-
-Here is a list of key mappings, adapted from the PSX version of the game:
-
-- &#129033;: Up
-- &#129034;: Right
-- &#129035;: Down
-- &#129032;: Left
-- &#10799;: ?
-- &#9633;: ?
-- &#9675;: Space bar
-- &#9651;: Esc
-- &#11207;: Enter
-- &#9644;: ?
-- **R1**: ?
-- **L1**: ?
-- **R2**: ?
-- **L2**: ?
+## Controls
+
+The default bindings are in `config/config.cfg` of the installation directory, in the `bind_game_event` lines. The game reads them as events, so the menus, the field and the battles share them. They can be changed there.
+
+|Key|Event|Action|
+|--|--|--|
+|Arrow keys|Up, Down, Left, Right|Move, move through menus|
+|Enter, Space|CONFIRM|Confirm, talk, interact|
+|Esc|CANCEL|Cancel, go back|
+|M|MENU|Open the main menu|
+|Backspace|EXTRA|Extra action in some menus|
+|P|START|Start|
+|V|SELECT|Select|
+|Page Up / Page Down|L1 / R1|Switch tab or character in menus|
+|Left Ctrl|run|Run in the field|
+
+The settings made in the in-game config menu (controls, sound, etc.) are saved with the game settings and loaded on start.
+
+<!-- TODO(review): verify the table against the in-game config menu (control remapping), and check the gamepad status. -->
+
+## Debug keys
+
+These are also defined in `config.cfg`:
+
+- **F11**: pause / resume the game timer. **Num +** / **Num -**: change the game speed.
+- **F12**: take a screenshot.
+- **Left Ctrl + Left Alt** plus **S, F, E, T, W, G, A, B, U, M**: toggle the debug displays (script, FPS, entities, triggers, walkmesh, grid, axis, background, UI, messages).
+- **F8** / **F9**: show / hide the begin menu.
+- **Alt + F4**: quit.