Add documentation surrounding development (FAForever#6326)

docs/development/batch-processing.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: Batch processing of blueprints
+parent: Development
+permalink: development/batch-processing
+published: false
+---
+
+test

docs/development/engine-debugger.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: Engine debugger
+parent: Development
+permalink: development/engine-debugger
+published: false
+---
+
+test

docs/development/lua-debugger.md

@@ -0,0 +1,66 @@
+---
+layout: page
+nav_order: 2
+title: 02. Lua debugger
+parent: Development
+permalink: development/lua-debugger
+---
+
+# Lua debugger
+
+A debugger allows you to set breakpoints and review the program state when the breakpoint is hit. The game ships with a debugger for Lua. And with thanks to [#3938](https://github.com/FAForever/fa/pull/3938) that debugger is now functional for everyone who has a local development environment. The debugger is not functional in any of the game types of the FAF Client.
+
+There are various approaches to enabling the debugger:
+
+- Keybinding: <kbd>Alt</kbd> + <kbd>F9</kbd>, this keybinding can be overwritten in the keybindings menu. If unassigned, search for 'debugging window' in the keybindings menu.
+- Console command: `SC_LuaDebugger`
+- Program argument: `/debug`
+
+## Overview
+
+![Screenshot of the debugger where it hit a breakpoint](/assets/development/lua-debugger-01.png)
+
+In general there are three distinct panels:
+
+- File explorer: allows you to search for a source file to set a breakpoint. Double click a source file to add it to the source panel.
+- Source panel: allows you to navigate between source files the source code of the selected source file.
+- Details panel: represents the program state at a given moment when a breakpoint is hit.
+
+There are various additional buttons to interact with the debugger:
+
+- `1`: Resume execution (hotkey: F5)
+- `2`: Step into (hotkey: F10)
+- `3`: Enable all breakpoints
+- `4`: Disable all breakpoints
+- `5`: Clear all breakpoints
+- `6`: Find (in a source file)
+- `7`: Find next (in a source file)
+- `8`: Find previous (in a source file)
+
+### Stack tab
+
+Represents the [stacktrace](https://en.wikipedia.org/wiki/Stack_trace). You can click on each element. The source panel will jump to the relevant file and line. The locals and globals tab are updated with the locals and globals that are available at that moment in time.
+
+### Locals tab
+
+Represents all variables that are available at the local and upvalue scope. You can double-click table variables to show of its all key value pairs.
+
+### Globals tab
+
+Similar to the locals tab, except that it represents the values that are accessible in the global scope.
+
+## Controls
+
+- <kbd>double</kbd> <kbd>click</kbd> on a line of source code to set a breakpoint
+- <kbd>F5</kbd> resume execution
+- <kbd>F10</kbd> step-in (can't find any way how to do step-over)
+- <kbd>Ctrl</kbd> + <kbd>G</kbd> goto line
+- <kbd>Ctrl</kbd> + <kbd>R</kbd> reloads the file
+
+## Tips and tricks
+
+- The moment you set a breakpoint the game becomes effectively unplayable, regardless of whether your breakpoint is hit. It is best to remove all breakpoints until you're certain that you're ready to reproduce the situation that you are investigating.
+- The debugger can be 'hidden' behind the game. To fix this you can run the game in windowed mode.
+- The debugger can be 'offscreen', if that is the case then you can reset its coordinates in the preference file. Backup your preference file before editing it manually. Removing the `Windows` entry is sufficient.
+
+We highly suggest reading [The implementation of Lua 5.0](https://www.lua.org/doc/jucs05.pdf) for a deeper understanding. In particular chapter 5 is useful to read to better understand the debugger window.

docs/development/setup.md

@@ -0,0 +1,79 @@
+---
+layout: page
+nav_order: 1
+title: 01. Setup
+parent: Development
+permalink: development/setup
+---
+
+# Setup of a development environment
+
+Development can be difficult when your development environment is not flexible enough. In this section we explain what we think works best. We do not provide details on how to use the tooling outside of specifics that are related to Supreme Commander.
+
+In general we assume that you made a [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) of the [fa repository](https://github.com/FAForever/fa) and that you have [cloned](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop) your fork to the device that you intend to use to develop on.
+
+## Tooling
+
+Everything works and breaks with your tooling. We recommend the following tooling:
+
+- [Visual Studio Code](https://code.visualstudio.com/) as your interactive development environment (IDE).
+- [Github Desktop](https://github.com/apps/desktop) or [Github CLI](https://git-scm.com/) as your tool to interact with Git.
+
+For Visual Studio Code we recommend the following extensions:
+
+- [FA Lua extension](https://github.com/FAForever/fa-lua-vscode-extension/releases): introduces intellisense - absolutely vital to development.
+- [Gitlens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens): useful for seeing who made what change.
+- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode): useful for formatting.
+- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker): useful to prevent common spelling mistakes.
+
+## Running the game with your changes
+
+Open up two explorers. Navigate to where you cloned the repository in one. Navigate to the bin folder of the FAForever client in another. Usually the bin folder of the client is located in:
+
+- `C:\ProgramData\FAForever\bin`
+
+Copy the `init_local_development.lua` file your fork to the the bin folder. The game uses an initialisation file to understand where it should (not) search for game files. The initialisation file you just copied is an adjusted initialisation file that tells the game to also look at your local repository. We still need to tell it where that is. Open up the file that you copied. At the top you'll find:
+
+```lua
+-- change this to the location of the repository on your disk. Note that `\` is used
+-- for escaping characters and you can just use `/` in your path instead.
+local locationOfRepository = 'your-fa-repository-location'
+```
+
+Update the path to where your local repository is. Make sure that it is still valid Lua. And make sure that you use `/` instead of `\`.
+
+Now we need to tell the game to launch with the adjusted initialisation file. We can do this through program arguments. We recommend you to create a small batch script file in the bin folder called `dev_windows`. The content should be roughly similar to:
+
+```batch
+ForgedAlliance.exe /init "init_local_development.lua" /EnableDiskWatch /showlog /log "local-development.log" /nomovie
+
+REM /init               Defines what initialisation file to use
+REM /EnableDiskWatch    Allows the game to reload files when it sees they're changed on disk
+REM /showlog            Opens the moho log by default
+REM /log                Defines where to store the log file
+REM /nomovie            Removes potentially lagging starting/launching movies (will require you to hit escape on startup)
+REM
+REM Other interesting program arguments:
+REM /debug              Start the game with the Lua debugger enabled
+```
+
+For Linux users you can use the following bash script file instead:
+
+```bash
+#! /bin/sh
+
+# Change this to the location of your run proton run script (you will have copied this into your client folder https://wiki.faforever.com/en/FAQ/Client-Setup)
+RunProton="$HOME/Applications/FAF/downlords-faf-client-1.6.0/run"
+$RunProton $HOME/.faforever/bin/ForgedAlliance.exe /init init_dev.lua /showlog /log "dev.log" /EnableDiskWatch /nomovie
+
+# /init               Define what initialisation file to use
+# /EnableDiskWatch    Allows the game to reload files when it sees they're changed on disk
+# /showlog            Opens the moho log by default
+# /log                Informs the game where to store the log
+# /nomovie            Removes potentially lagging starting/launching movies (will require you to hit escape on startup)
+#
+# Other interesting program arguments:
+# /debug              Start the game with the Lua debugger enabled
+```
+
+Now you can start the game by executing the batch/bash script file. If all is good then the game starts as usual and you'll be in the main menu. If something is off then the game usually does not start. In that case you likely made a typo.

docs/development/start-here.md

@@ -0,0 +1,12 @@
+---
+layout: page
+nav_order: 1
+title: Start here
+parent: Development
+has_children: true
+permalink: development/start-here
+---
+
+# Start of a development journey
+
+{: .no_toc}

setup/bin/dev_linux.sh

@@ -2,11 +2,10 @@
 
 # Change this to the location of your run proton run script (you will have copied this into your client folder https://wiki.faforever.com/en/FAQ/Client-Setup)
 RunProton="$HOME/Applications/FAF/downlords-faf-client-1.6.0/run"
-$RunProton $HOME/.faforever/bin/ForgedAlliance.exe /init init_dev.lua /showlog /log "dev.log" /RunWithTheWind /EnableDiskWatch /nomovie
+$RunProton $HOME/.faforever/bin/ForgedAlliance.exe /init init_dev.lua /showlog /log "dev.log" /EnableDiskWatch /nomovie
 
 # /init               Define what initialisation file to use
 # /EnableDiskWatch    Allows the game to reload files when it sees they're changed on disk
 # /showlog            Opens the moho log by default
 # /log                Informs the game where to store the log
-# /RunWithTheWind     Ensures single player games are compatible with the console commander `wld_RunWithTheWind` 
 # /nomovie            Removes super laggy starting/launching movies (will require you to hit escape on startup)

setup/bin/dev_windows.bat

@@ -1,7 +1,6 @@
-ForgedAlliance.exe /init "init_dev.lua" /EnableDiskWatch /showlog /log "dev.log" /RunWithTheWind /nomovie
+ForgedAlliance.exe /init "init_local_development.lua" /EnableDiskWatch /showlog /log "local-development.log" /nomovie
 
 REM /init               Define what initialisation file to use
 REM /EnableDiskWatch    Allows the game to reload files when it sees they're changed on disk
 REM /showlog            Opens the moho log by default
 REM /log                Informs the game where to store the log
-REM /RunWithTheWind     Ensures single player games are compatible with the console commander `wld_RunWithTheWind`