Doc: revised README to be more helpful to casual GitHub visitors

3 files changed, 287 insertions, 0 deletions

diff --git a/docs/debugging_desyncs.md b/docs/debugging_desyncs.md
new file mode 100644
index 000000000..f5ea06e08
--- /dev/null
+++ b/docs/debugging_desyncs.md
@@ -0,0 +1,56 @@
+# Debugging / reporting desyncs
+
+As desyncs are hard to make reproducible OpenTTD has the ability to log all
+actions done by clients so we can replay the whole game in an effort to make
+desyncs better reproducible. You need to turn this ability on. When turned
+on an automatic savegame will be made once the map has been constructed in
+the 'save/autosave' directory, see OpenTTD directories to know where to find
+this directory. Furthermore the log file 'commands-out.log' will be created
+and all actions will be written to there.
+
+To enable the desync debugging you need to set the debug level for 'desync'
+to at least 1. You do this by starting OpenTTD with '`-d desync=<level>`' as
+parameter or by typing '`debug_level desync=<level>`' in OpenTTD's internal
+console.
+The desync debug levels are:
+
+- 0: nothing.
+- 1: dumping of commands to 'commands-out.log'.
+- 2: same as 1 plus checking vehicle caches and dumping that too.
+- 3: same as 2 plus monthly saves in autosave.
+- 4 and higher: same as 3
+
+Restarting OpenTTD will overwrite 'commands-out.log'. OpenTTD will not remove
+the savegames (dmp_cmds_*.sav) made by the desync debugging system, so you
+have to occasionally remove them yourself!
+
+The naming format of the desync savegames is as follows:
+dmp_cmds_XXXXXXXX_YYYYYYYY.sav. The XXXXXXXX is the hexadecimal representation
+of the generation seed of the game and YYYYYYYY is the hexadecimal
+representation of the date of the game. This sorts the savegames by game and
+then by date making it easier to find the right savegames.
+
+When a desync has occurred with the desync debugging turned on you should file
+a bug report with the following files attached:
+
+- commands-out.log as it contains all the commands that were done
+- the last saved savegame (search for the last line beginning with
+   'save: dmp_cmds_' in commands-out.log). We use this savegame to check
+   whether we can quickly reproduce the desync. Otherwise we will need …
+- the first saved savegame (search for the first line beginning with 'save'
+   where the first part, up to the last underscore '_', is the same). We need
+   this savegame to be able to reproduce the bug when the last savegame is not
+   old enough. If you loaded a scenario or savegame you need to attach that.
+- optionally you can attach the savegames from around 50%, 75%, 85%, 90% and
+   95% of the game's progression. We can use these savegames to speed up the
+   reproduction of the desync, but we should be able to reproduce these
+   savegames based on the first savegame and commands-out.log.
+- in case you use any NewGRFs you should attach the ones you used unless
+   we can easily find them ourselves via bananas or when they are in the
+   #openttdcoop pack.
+
+Do NOT remove the dmp_cmds savegames of a desync you have reported until the
+desync has been fixed; if you, by accident, send us the wrong savegames we
+will not be able to reproduce the desync and thus will be unable to fix it.
+
+
diff --git a/docs/directory_structure.md b/docs/directory_structure.md
new file mode 100644
index 000000000..51ad1c5a3
--- /dev/null
+++ b/docs/directory_structure.md
@@ -0,0 +1,130 @@
+# OpenTTD directory structure
+
+OpenTTD uses its own directory to store its required 3rd party base set files
+(see section 4.1 'Required 3rd party files') and non-compulsory extension and
+configuration files.
+
+See below for their proper place within this OpenTTD main data directory.
+
+The main OpenTTD directories can be found in various locations, depending on
+your operating system:
+
+1. The current working directory (from where you started OpenTTD)
+
+    For non-Windows operating systems OpenTTD will not scan for files in this
+    directory if it is your personal directory, i.e. '~/', or when it is the
+    root directory, i.e. '/'.
+
+2. Your personal directory
+    - Windows:
+        - `C:\My Documents\OpenTTD` (95, 98, ME)
+        - `C:\Documents and Settings\<username>\My Documents\OpenTTD` (2000, XP)
+        - `C:\Users\<username>\Documents\OpenTTD` (Vista, 7, 8.1, 10)
+    - macOS: `~/Documents/OpenTTD`
+    - Linux: `$XDG_DATA_HOME/openttd` which is usually `~/.local/share/openttd`
+       when built with XDG base directory support, otherwise `~/.openttd`
+3. The shared directory
+    - Windows:
+        - `C:\Documents and Settings\All Users\Shared Documents\OpenTTD` (2000, XP)
+        - `C:\Users\Public\Documents\OpenTTD` (Vista, 7, 8.1, 10)
+    - macOS: `/Library/Application Support/OpenTTD`
+    - Linux: not available
+4. The binary directory (where the OpenTTD executable is)
+    - Windows: `C:\Program Files\OpenTTD`
+    - Linux: `/usr/games`
+5. The installation directory (Linux only)
+    - Linux: `/usr/share/games/openttd`
+6. The application bundle (macOS only)
+
+    It includes the OpenTTD files (grf+lng) and it will work as long as they
+    are not touched
+
+Different types of data or extensions go into different subdirectories of the
+chosen main OpenTTD directory:
+
+| data type           | directory         | additional info             |
+| ------------------- | ----------------- | --------------------------- |
+| Config File         | (no subdirectory) |                             |
+| Screenshots         | screenshot        |                             |
+| Base Graphics       | baseset           | (or a subdirectory thereof) |
+| Sound Sets          | baseset           | (or a subdirectory thereof) |
+| NewGRFs             | newgrf            | (or a subdirectory thereof) |
+| 32bpp Sets          | newgrf            | (or a subdirectory thereof) |
+| Music Sets          | baseset           | (or a subdirectory thereof) |
+| AIs                 | ai                | (or a subdirectory thereof) |
+| AI Libraries        | ai/library        | (or a subdirectory thereof) |
+| Game Scripts (GS)   | game              | (or a subdirectory thereof) |
+| GS Libraries        | game/library      | (or a subdirectory thereof) |
+| Savegames           | save              |                             |
+| Automatic Savegames | save/autosave     |                             |
+| Scenarios           | scenario          |                             |
+
+The (automatically created) directory content_download is for OpenTTD's internal
+use and no files should be added to it or its subdirectories manually.
+
+## Notes:
+
+- Linux in the previous list means .deb, but most paths should be similar for
+   others.
+- The previous search order is also used for NewGRFs and openttd.cfg.
+- If openttd.cfg is not found, then it will be created using the 2, 4, 1, 3,
+   5 order. When built with XDG base directory support, openttd.cfg will be
+   created in $XDG_CONFIG_HOME/openttd which is usually ~/.config/openttd.
+- Savegames will be relative to the config file only if there is no save/
+   directory in paths with higher priority than the config file path, but
+   autosaves and screenshots will always be relative to the config file.
+   Unless the configuration file is in $XDG_CONFIG_HOME/openttd, then all
+   other files will be saved under $XDG_DATA_HOME/openttd.
+
+## The preferred setup:
+
+Place 3rd party files in shared directory (or in personal directory if you do
+not have write access on shared directory) and have your openttd.cfg config
+file in personal directory (where the game will then also place savegames and
+screenshots).
+
+## Portable installations (portable media)
+
+You can install OpenTTD on external media so you can take it with you, i.e.
+using a USB key, or a USB HDD, etc.
+Create a directory where you shall store the game in (i.e. OpenTTD/).
+Copy the binary (OpenTTD.exe, OpenTTD.app, openttd, etc), baseset/ and your
+openttd.cfg to this directory.
+You can copy binaries for any operating system into this directory, which will
+allow you to play the game on nearly any computer you can attach the external
+media to.
+As always - additional grf files are stored in the newgrf/ dir (for details,
+again, see section 4.1).
+
+## Files in tar (archives)
+
+OpenTTD can read files that are in an uncompressed tar (archive), which
+makes it easy to bundle files belonging to the same script, NewGRF or base
+set. Music sets are the only exception as they cannot be stored in a tar
+file due to being played by external applications.
+
+OpenTTD sees each tar archive as the 'root' of its search path. This means that
+having a file with the same path in two different tar files means that one
+cannot be opened, after all only one file will be found first. As such it is
+advisable to put an uniquely named folder in the root of the tar and put all the
+content in that folder. For example, all downloaded content has a path that
+concatenates the name of the content and the version, which makes the path
+unique. For custom tar files it is advised to do this as well.
+
+The normal files are also referred to by their relative path from the search
+directory, this means that also normal files could hide files in a tar as
+long as the relative path from the search path of the normal file is the
+same as the path in the tar file. Again it is advised to have an unique path
+to the normal file so they do not collide with the files from other tar
+files.
+
+## Configuration file
+
+The configuration file for OpenTTD (openttd.cfg) is in a simple Windows-like
+.INI format. It is mostly undocumented. Almost all settings can be changed
+ingame by using the 'Advanced Settings' window.
+
+When you cannot find openttd.cfg you should look in the directories as
+described in this document. If you do not have an openttd.cfg OpenTTD will
+create one after closing.
+
diff --git a/docs/logging_and_performance_metrics.md b/docs/logging_and_performance_metrics.md
new file mode 100644
index 000000000..9f0679acd
--- /dev/null
+++ b/docs/logging_and_performance_metrics.md
@@ -0,0 +1,101 @@
+# Logging, frame rate and performance metrics
+
+## 1.0) Logging of potentially dangerous actions
+
+OpenTTD is a complex program, and together with NewGRF, it may show a buggy
+behaviour. But not only bugs in code can cause problems. There are several
+ways to affect game state possibly resulting in program crash or multiplayer
+desyncs.
+
+Easier way would be to forbid all these unsafe actions, but that would affect
+game usability for many players. We certainly do not want that.
+However, we receive bug reports because of this. To reduce time spent with
+solving these problems, these potentially unsafe actions are logged in
+the savegame (including crash.sav). Log is stored in crash logs, too.
+
+Information logged:
+
+- Adding / removing / changing order of NewGRFs
+- Changing NewGRF parameters, loading compatible NewGRF
+- Changing game mode (scenario editor <-> normal game)
+- Loading game saved in a different OpenTTD / TTDPatch / Transport Tycoon Deluxe /
+   original Transport Tycoon version
+- Running a modified OpenTTD build
+- Changing settings affecting NewGRF behaviour (non-network-safe settings)
+- Triggering NewGRF bugs
+
+No personal information is stored.
+
+You can show the game log by typing 'gamelog' in the console or by running
+OpenTTD in debug mode.
+
+## 2.0) Frame rate and performance metrics
+
+The Help menu in-game has a function to open the Frame rate window. This
+window shows various real-time performance statistics, measuring what parts
+of the game require the most processing power currently.
+
+A summary of the statistics can also be retrieved from the console with the
+`fps` command. This is especially useful on dedicated servers, where the
+administrator might want to determine what's limiting performance in a slow
+game.
+
+The frame rate is given as two figures, the simulation rate and the graphics
+frame rate. Usually these are identical, as the screen is rendered exactly
+once per simulated tick, but in the future there might be support for graphics
+and simulation running at different rates. When the game is paused, the
+simulation rate drops to zero.
+
+In addition to the simulation rate, a game speed factor is also calculated.
+This is based on the target simulation speed, which is 30 milliseconds per
+game tick. At that speed, the expected frame rate is 33.33 frames/second, and
+the game speed factor is how close to that target the actual rate is. When
+the game is in fast forward mode, the game speed factor shows how much
+speed up is achieved.
+
+The lower part of the window shows timing statistics for individual parts of
+the game. The times shown are short-term and long-term averages of how long
+it takes to process one tick of game time, all figures are in milliseconds.
+
+Clicking a line in the lower part of the window opens a graph window, giving
+detailed readings on each tick simulated by the game.
+
+The following is an explanation of the different statistics:
+
+- *Game loop* - Total processing time used per simulated "tick" in the game.
+  This includes all pathfinding, world updates, and economy handling.
+- *Cargo handling* - Time spent loading/unloading cargo at stations, and
+  industries and towns sending/retrieving cargo from stations.
+- *Train ticks*, *Road vehicle ticks*, *Ship ticks*, *Aircraft ticks* -
+  Time spent on pathfinding and other processing for each player vehicle type.
+- *World ticks* - Time spent on other world/landscape processing. This
+  includes towns growing, building animations, updates of farmland and trees,
+  and station rating updates.
+- *GS/AI total*, *Game script*, and *AI players* - Time spent running logic
+  for game scripts and AI players. The total may show as less than the current
+  sum of the individual scripts, this is because AI players at lower
+  difficulty settings do not run every game tick, and hence contribute less
+  to the average across all ticks. Keep in mind that the "Current" figure is
+  also an average, just only over short term.
+- *Link graph delay* - Time overruns of the cargo distribution link graph
+  update thread. Usually the link graph is updated in a background thread,
+  but these updates need to synchronise with the main game loop occasionally,
+  if the time spent on link graph updates is longer than the time taken to
+  otherwise simulate the game while it was updating, these delays are counted
+  in this figure.
+- *Graphics rendering* - Total time spent rendering all graphics, including
+  both GUI and world viewports. This typically spikes when panning the view
+  around, and when more things are happening on screen at once.
+- *World viewport rendering* - Isolated time spent rendering just world
+  viewports. If this figure is significantly lower than the total graphics
+  rendering time, most time is spent rendering GUI than rendering world.
+- *Video output* - Speed of copying the rendered graphics to the display
+  adapter. Usually this should be very fast (in the range of 0-3 ms), large
+  values for this can indicate a graphics driver problem.
+- *Sound mixing* - Speed of mixing active audio samples together. Usually
+  this should be very fast (in the range of 0-3 ms), if it is slow, consider
+  switching to the NoSound set.
+
+If the frame rate window is shaded, the title bar will instead show just the
+current simulation rate and the game speed factor.
+