docs/debugging_desyncs.md

   1 # Debugging / reporting desyncs
   2
   3 As desyncs are hard to make reproducible OpenTTD has the ability to log all
   4 actions done by clients so we can replay the whole game in an effort to make
   5 desyncs better reproducible. You need to turn this ability on. When turned
   6 on an automatic savegame will be made once the map has been constructed in
   7 the 'save/autosave' directory, see OpenTTD directories to know where to find
   8 this directory. Furthermore the log file 'commands-out.log' will be created
   9 and all actions will be written to there.
  10
  11 To enable the desync debugging you need to set the debug level for 'desync'
  12 to at least 1. You do this by starting OpenTTD with '`-d desync=<level>`' as
  13 parameter or by typing '`debug_level desync=<level>`' in OpenTTD's internal
  14 console.
  15 The desync debug levels are:
  16
  17 - 0: nothing.
  18 - 1: dumping of commands to 'commands-out.log'.
  19 - 2: same as 1 plus checking vehicle caches and dumping that too.
  20 - 3: same as 2 plus monthly saves in autosave.
  21 - 4 and higher: same as 3
  22
  23 Restarting OpenTTD will overwrite 'commands-out.log'. OpenTTD will not remove
  24 the savegames (dmp_cmds_*.sav) made by the desync debugging system, so you
  25 have to occasionally remove them yourself!
  26
  27 The naming format of the desync savegames is as follows:
  28 dmp_cmds_XXXXXXXX_YYYYYYYY.sav. The XXXXXXXX is the hexadecimal representation
  29 of the generation seed of the game and YYYYYYYY is the hexadecimal
  30 representation of the date of the game. This sorts the savegames by game and
  31 then by date making it easier to find the right savegames.
  32
  33 When a desync has occurred with the desync debugging turned on you should file
  34 a bug report with the following files attached:
  35
  36 - commands-out.log as it contains all the commands that were done
  37 - the last saved savegame (search for the last line beginning with
  38    'save: dmp_cmds_' in commands-out.log). We use this savegame to check
  39    whether we can quickly reproduce the desync. Otherwise we will need …
  40 - the first saved savegame (search for the first line beginning with 'save'
  41    where the first part, up to the last underscore '_', is the same). We need
  42    this savegame to be able to reproduce the bug when the last savegame is not
  43    old enough. If you loaded a scenario or savegame you need to attach that.
  44 - optionally you can attach the savegames from around 50%, 75%, 85%, 90% and
  45    95% of the game's progression. We can use these savegames to speed up the
  46    reproduction of the desync, but we should be able to reproduce these
  47    savegames based on the first savegame and commands-out.log.
  48 - in case you use any NewGRFs you should attach the ones you used unless
  49    we can easily find them ourselves via bananas or when they are in the
  50    #openttdcoop pack.
  51
  52 Do NOT remove the dmp_cmds savegames of a desync you have reported until the
  53 desync has been fixed; if you, by accident, send us the wrong savegames we
  54 will not be able to reproduce the desync and thus will be unable to fix it.
  55
  56 ## More information
  57
  58 You can find more theory on the causes and debugging of desyncs in the
  59 [desync documentation](./desync.md).