Doc: revised README to be more helpful to casual GitHub visitors
Andy
5 years ago
committed by
Michael Lutz
parent
b8abd54181
commit
cfc4568ddc
@ -0,0 +1,60 @@
|
||||
### The OpenTTD team (in alphabetical order):
|
||||
|
||||
- Grzegorz Duczyński (adf88) - General coding (since 1.7.2)
|
||||
- Albert Hofkamp (Alberth) - GUI expert (since 0.7)
|
||||
- Matthijs Kooijman (blathijs) - Pathfinder-guru, Debian port (since 0.3)
|
||||
- Ulf Hermann (fonsinchen) - Cargo Distribution (since 1.3)
|
||||
- Christoph Elsenhans (frosch) - General coding (since 0.6)
|
||||
- Loïc Guilloux (glx) - Windows Expert (since 0.4.5)
|
||||
- Charles Pigott (LordAro) - General / Correctness police (since 1.9)
|
||||
- Michael Lutz (michi_cc) - Path based signals (since 0.7)
|
||||
- Niels Martin Hansen (nielsm) - Music system, general coding (since 1.9)
|
||||
- Owen Rudge (orudge) - Forum host, OS/2 port (since 0.1)
|
||||
- Peter Nelson (peter1138) - Spiritual descendant from newGRF gods (since 0.4.5)
|
||||
- Ingo von Borstel (planetmaker) - General coding, Support (since 1.1)
|
||||
- Remko Bijker (Rubidium) - Lead coder and way more (since 0.4.5)
|
||||
- José Soler (Terkhen) - General coding (since 1.0)
|
||||
- Leif Linse (Zuu) - AI/Game Script (since 1.2)
|
||||
|
||||
### Inactive Developers:
|
||||
|
||||
- Jean-François Claeys (Belugas) - GUI, newindustries and more (0.4.5 - 1.0)
|
||||
- Bjarni Corfitzen (Bjarni) - macOS port, coder and vehicles (0.3 - 0.7)
|
||||
- Victor Fischer (Celestar) - Programming everywhere you need him to (0.3 - 0.6)
|
||||
- Jaroslav Mazanec (KUDr) - YAPG (Yet Another Pathfinder God) ;) (0.4.5 - 0.6)
|
||||
- Jonathan Coome (Maedhros) - High priest of the NewGRF Temple (0.5 - 0.6)
|
||||
- Attila Bán (MiHaMiX) - WebTranslator 1 and 2 (0.3 - 0.5)
|
||||
- Zdeněk Sojka (SmatZ) - Bug finder and fixer (0.6 - 1.3)
|
||||
- Christoph Mallon (Tron) - Programmer, code correctness police (0.3 - 0.5)
|
||||
- Patric Stout (TrueBrain) - NoProgrammer (0.3 - 1.2), sys op (active)
|
||||
- Thijs Marinussen (Yexo) - AI Framework, General (0.6 - 1.3)
|
||||
|
||||
### Retired Developers:
|
||||
|
||||
- Tamás Faragó (Darkvater) - Ex-Lead coder (0.3 - 0.5)
|
||||
- Dominik Scherer (dominik81) - Lead programmer, GUI expert (0.3 - 0.3)
|
||||
- Emil Djupfeld (egladil) - macOS port (0.4 - 0.6)
|
||||
- Simon Sasburg (HackyKid) - Bug fixer (0.4 - 0.4.5)
|
||||
- Ludvig Strigeus (ludde) - Original author of OpenTTD, main coder (0.1 - 0.3)
|
||||
- Cian Duffy (MYOB) - BeOS port / manual writing (0.1 - 0.3)
|
||||
- Petr Baudiš (pasky) - Many patches, newgrf support, etc. (0.3 - 0.3)
|
||||
- Benedikt Brüggemeier (skidd13) - Bug fixer and code reworker (0.6 - 0.7)
|
||||
- Serge Paquet (vurlix) - 2nd contributor after ludde (0.1 - 0.3)
|
||||
|
||||
### Thanks to:
|
||||
|
||||
- Josef Drexler - For his great work on TTDPatch.
|
||||
- Marcin Grzegorczyk - For his TTDPatch work and documentation of Transport Tycoon Deluxe internals and track foundations
|
||||
- Stefan Meißner (sign_de) - For his work on the console
|
||||
- Mike Ragsdale - OpenTTD installer
|
||||
- Christian Rosentreter (tokai) - MorphOS / AmigaOS port
|
||||
- Richard Kempton (RichK67) - Additional airports, initial TGP implementation
|
||||
- Alberto Demichelis - Squirrel scripting language
|
||||
- L. Peter Deutsch - MD5 implementation
|
||||
- Michael Blunck - For revolutionizing TTD with awesome graphics
|
||||
- George - Canal graphics
|
||||
- Andrew Parkhouse (andythenorth) - River graphics
|
||||
- David Dallaston (Pikka) - Tram tracks
|
||||
- All Translators - For their support to make OpenTTD a truly international game
|
||||
- Bug Reporters - Thanks for all bug reports
|
||||
- Chris Sawyer - For an amazing game!
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue