From f7bd08001546a078ec6df014ccb77610bf8bc7eb Mon Sep 17 00:00:00 2001
From: Patric Stout <truebrain@openttd.org>
Date: Wed, 17 Apr 2024 22:36:08 +0200
Subject: [PATCH] Codechange: improve desync documentation (#12521)

---
 docs/desync.md             | 31 +++++++++++++++----------------
 src/network/network.cpp    |  2 +-
 src/network/network_func.h |  2 +-
 3 files changed, 17 insertions(+), 18 deletions(-)

diff --git a/docs/desync.md b/docs/desync.md
index 20003c9810..afbebb11c5 100644
--- a/docs/desync.md
+++ b/docs/desync.md
@@ -195,10 +195,11 @@ Last updated: 2014-02-23
      'src/network/network_func.h'.
      (DEBUG_FAILED_DUMP_COMMANDS is explained later)
    - Put the 'commands-out.log' into the root save folder, and rename
-      it to 'commands.log'.
-   - Run 'openttd -D -d desync=3 -g startsavegame.sav'.
-     This replays the server log and creates new 'commands-out.log'
-     and 'dmp_cmds_*.sav' in your autosave folder.
+      it to 'commands.log'. Strip everything and including the "newgame"
+      entry from the log.
+   - Run 'openttd -D -d desync=0 -g startsavegame.sav'.
+     This replays the server log. Use "-d desync=3" to also create a
+     new 'commands-out.log' and 'dmp_cmds_*.sav' in your autosave folder.
 
 ## 3.2) Evaluation of the replay
 
@@ -226,7 +227,7 @@ Last updated: 2014-02-23
   savegames with your own ones from the replay. You can also comment/disable
   the 'NOT_REACHED' mentioned above, to get another 'dmp_cmds_*.sav' from
   the replay after the mismatch has already been detected.
-  See Section 3.2 on how to compare savegames.
+  See Section 3.3 on how to compare savegames.
   If the saves differ you have located the Desync between the last dmp_cmds
   that match and the first one that does not. The difference of the saves
   may point you in the direction of what causes it.
@@ -252,16 +253,14 @@ Last updated: 2014-02-23
      are replayed. Their internal state will thus not change in the
      replay and will differ.
 
-  To compare savegame more semantically, there exist some ugly hackish
-  tools at:
-     http://devs.openttd.org/~frosch/texts/zpipe.c
-     http://devs.openttd.org/~frosch/texts/printhunk.c
+  To compare savegame more semantically, easiest is to first export them
+  to a JSON format with for example:
 
-  The first one decompresses OpenTTD savegames. The second one creates
-  a textual representation of an uncompressed savegame, by parsing hunks
-  and arrays and such. With both tools you need to be a bit careful
-  since they work on stdin and stdout, which may not deal well with
-  binary data.
+  https://github.com/TrueBrain/OpenTTD-savegame-reader
 
-  If you have the textual representation of the savegames, you can
-  compare them with regular diff tools.
+  By running:
+
+  python -m savegame_reader --export-json dmp_cmds_NNN.sav | jq . > NNN.json
+
+  Now you can use any (JSON) diff tool to compare the two savegames in a
+  somewhat human readable way.
diff --git a/src/network/network.cpp b/src/network/network.cpp
index 3cd1529bdb..5eb64da827 100644
--- a/src/network/network.cpp
+++ b/src/network/network.cpp
@@ -51,7 +51,7 @@
  * Used to load the desync debug logs, i.e. for reproducing a desync.
  * There's basically no need to ever enable this, unless you really know what
  * you are doing, i.e. debugging a desync.
- * See docs/desync.txt for details. */
+ * See docs/desync.md for details. */
 bool _ddc_fastforward = true;
 #endif /* DEBUG_DUMP_COMMANDS */
 
diff --git a/src/network/network_func.h b/src/network/network_func.h
index 66b4660169..4a31943e63 100644
--- a/src/network/network_func.h
+++ b/src/network/network_func.h
@@ -12,7 +12,7 @@
 
 /**
  * Uncomment the following define to enable command replaying.
- * See docs/desync.txt for details.
+ * See docs/desync.md for details.
  */
 // #define DEBUG_DUMP_COMMANDS
 // #define DEBUG_FAILED_DUMP_COMMANDS