diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/debugging_desyncs.md | 56 | ||||
| -rw-r--r-- | docs/directory_structure.md | 130 | ||||
| -rw-r--r-- | docs/logging_and_performance_metrics.md | 101 |
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. + |