petern/OpenTTD
1
0
Fork 0
forked from mirror/OpenTTD
Code Pull Requests Activity

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

Browse Source
This commit is contained in:
Andy
2019-10-18 21:44:18 +01:00
committed by Michael Lutz
parent b8abd54181
commit cfc4568ddc
5 changed files with 499 additions and 644 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/debugging_desyncs.md Normal file
View File

@@ -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.

130
docs/directory_structure.md Normal file
View File

@@ -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.

101
docs/logging_and_performance_metrics.md Normal file
View File

@@ -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.