Updated the documentation

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.

debian/control

@@ -2,7 +2,7 @@ Source: v-gears
 Section: games
 Priority: extra
 Maintainer: Iñigo Valentin <i@inigovalentin.com>
-Build-Depends: debhelper(>= 7.0.50~),libogre-1.12-dev, libtinyxml-dev, cmake, cdbs, libois-dev, libboost-program-options-dev, libboost-filesystem-dev, libvorbis-dev, libopenal-dev, libboost-test-dev, zlib1g-dev, libarchive-dev, libqt5core5a, libqt5widgets5, libluajit-5.1-dev
+Build-Depends: debhelper(>= 7.0.50~),libogre-1.12-dev, libtinyxml-dev, cmake, cdbs, libois-dev, libboost-program-options-dev, libboost-filesystem-dev, libvorbis-dev, libopenal-dev, libboost-test-dev, zlib1g-dev, libarchive-dev, libqt5core5a, libqt5widgets5, qtbase5-dev, libboost-dev, libboost-thread-dev, libluajit-5.1-dev
 Standards-Version: 3.9.5
 Homepage: https://v-gears.inigovalentin.com
 Vcs-Git: https://github.com/InigoValentin/V-Gears.git
@@ -11,5 +11,6 @@ Vcs-Git: https://github.com/InigoValentin/V-Gears.git
 Package: v-gears
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}
+Recommends: ffmpeg, timidity
 Description: A Free Final Fantasy VII Engine
  A Free Replacement for the Final Fantasy VII Engine.

doc/BUILD.md

@@ -1,32 +1,12 @@
 # <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
+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 ffmpeg timidity
 ```
 
-## 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 (recommended for CI and packaging).
-
-Disable fallbacks example:
-
-```bash
-cmake .. -DUSE_DETERMINISTIC_FALLBACKS=OFF -DCMAKE_BUILD_TYPE=Release
-```
-
-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`.
-
-
 ## Build using CMake
 
 From the project directory, run these commands:
@@ -38,9 +18,9 @@ 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.
@@ -49,7 +29,7 @@ The engine must be launched from the installation directory (the installer start
 
 ## 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 and the tool finder, the movie camera data), which don't need the rest of the engine:
 
 ```bash
 mkdir build-tests;
@@ -59,9 +39,37 @@ 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. -->
+
+## 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, or if you are packaging V-Gears.
+
+
+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 (recommended for CI and packaging).
+
+Disable fallbacks example:
+
+```bash
+cmake .. -DUSE_DETERMINISTIC_FALLBACKS=OFF -DCMAKE_BUILD_TYPE=Release
+```
+
+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. 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_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*).
@@ -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,10 +1,10 @@
-# <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).
 
-On a terminal, do into the game data folder, and from there, run the engine
+On a terminal, go into the game data folder, and from there, run the engine
 
 ```Bash
 cd ~/.v-gears/;
@@ -14,21 +14,32 @@ cd ~/.v-gears/;
 
 The data installer also has a **Launch game** button, which starts the engine from 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.