add desync handler sample and docs

Author: lucasteles

docfx/docs/developer_guide.md

@@ -34,7 +34,7 @@ state as well.
 Each player in a [Backdash](https://github.com/lucasteles/Backdash) networked game has a complete copy of your game
 running. [Backdash](https://github.com/lucasteles/Backdash) needs to keep both copies of the
 game state in sync to ensure that both players are experiencing the same game. It would be much too expensive to send an
-entire copy of the game state between players every frame. Instead [Backdash](https://github.com/lucasteles/Backdash)
+entire copy of the game state between players every frame. Instead, [Backdash](https://github.com/lucasteles/Backdash)
 sends the players' inputs to each other and has
 each player step the game forward. In order for this to work, your game engine must meet three criteria:
 
@@ -98,14 +98,14 @@ var session = RollbackNetcode
 ```
 
 > [!TIP]
-> If you want to use a integer type as your input type:
+> If you want to use an integer type as your input type:
 >
 > `RollbackNetcode.WithInputType(t => t.Integer<uint>())`
 
 The session builder can be used to configure the session by setting [`NetcodeOptions`](https://lucasteles.github.io/Backdash/api/Backdash.NetcodeOptions.html):
 - passing an instance to `.WithOptions(..)`
-- using the a delegate function on `.Configure(options => {})`
-- using the a fluent api
+- using a delegate function on `.Configure(options => {})`
+- using the fluent api
 
 
 ```csharp

docfx/docs/troubleshooting.md

@@ -7,7 +7,8 @@ not starting a game from scratch. Most applications will already conform to most
 ## Isolate **Game State** from **Non-Game State**
 
 [Backdash](https://github.com/lucasteles/Backdash) will periodically request that you save and load the entire state of
-your game. For most games, the state that needs to be saved is a tiny fraction of the entire game. Usually, the video and
+your game. For most games, the state that needs to be saved is a tiny fraction of the entire game. Usually, the video
+and
 audio renderers, look-up tables, textures, sound data, and your code segments are either constant from frame to frame or
 not involved in the calculation of the game state. These do not need to be saved or restored.
 
@@ -63,7 +64,8 @@ times [Backdash](https://github.com/lucasteles/Backdash) needs to rollback to th
 ### Beware of External Time Sources (eg. random, clock time)
 
 Be careful if you use the current time of day in your game state calculation. This may be used for an effect on the game
-or to derive another game state (e.g. using the timer as a seed to the random number generator). The time on two computers
+or to derive another game state (e.g. using the timer as a seed to the random number generator). The time on two
+computers
 or game consoles is almost never in sync and using time in your game state calculations can lead to synchronization
 issues. You should either eliminate the use of time in your game state or include the current time for one of the
 players as part of the input to a frame and always use that time in your calculations.
@@ -72,8 +74,11 @@ The use of external time sources in **non-game state** calculations is fine (_e.
 screen, or the attenuation of audio samples_).
 
 > [!INFORMATION]
-> We provide an implementation of a _[Deterministic Random](https://lucasteles.github.io/Backdash/api/Backdash.Synchronizing.Random.IDeterministicRandom.html)_  out of the box
-> which can be accessed directly from the _[Rollback Session](https://lucasteles.github.io/Backdash/api/Backdash.INetcodeSession-1.html#Backdash_INetcodeSession_1_Random)_
+> We provide an implementation of a
+_[Deterministic Random](https://lucasteles.github.io/Backdash/api/Backdash.Synchronizing.Random.IDeterministicRandom.html)_
+> out of the box
+> which can be accessed directly from the
+_[Rollback Session](https://lucasteles.github.io/Backdash/api/Backdash.INetcodeSession-1.html#Backdash_INetcodeSession_1_Random)_
 
 ## Beware of Dangling References
 
@@ -85,7 +90,8 @@ reference instead of the values.
 
 The language your game is written in may have features that make it difficult to track down all your state. [Static
 automatic variables in `C`](https://www.javatpoint.com/auto-and-static-variable-in-c)
-or [static members in `C#`](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members)
+or [static members in
+`C#`](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members)
 are examples of this behavior. You need to track down all these locations and convert them to
 a form that can be saved. For example, compare:
 
@@ -129,14 +135,34 @@ public class MySessionHandler : INetcodeSessionHandler
 }
 ```
 
-## Use the [Backdash](https://github.com/lucasteles/Backdash) Sync Test Feature. A Lot.
+## Use the [Backdash](https://github.com/lucasteles/Backdash) SyncTest Feature. A Lot.
 
-Once you've ported your application to [Backdash](https://github.com/lucasteles/Backdash), you can use
-the [`CreateSyncTestSession`](https://lucasteles.github.io/Backdash/api/Backdash.RollbackNetcode.html#Backdash_RollbackNetcode_CreateSyncTestSession__2_System_Nullable_Backdash_Data_FrameSpan__Backdash_NetcodeOptions_Backdash_SessionServices___0___1__System_Boolean_)
-function to help track down synchronization issues which may be the result of a leaky game state.
+Once you've ported your application to [Backdash](https://github.com/lucasteles/Backdash),
+you can use tool called `SyncTest` to help track down synchronization issues which may be the result of a leaky game
+state.
 
-The sync test session is a special, single player session which is designed to find errors in your simulation's
-determinism. When running in a **sync-test session**, [Backdash](https://github.com/lucasteles/Backdash) by default will
+To create a sync test session use:
+
+```csharp
+using Backdash;
+
+var session = RollbackNetcode
+    .WithInputType<MyGameInput>()
+    .Configure(options =>
+    {
+        // ...
+    })
+    .ForSyncTest(options => options
+    {
+        // ...
+    })
+    .Build();
+```
+
+The sync test session is a special session which is designed to find errors in your simulation's
+determinism.
+
+When running in a **sync-test session**, [Backdash](https://github.com/lucasteles/Backdash) by default will
 execute a 1 frame rollback for every frame of your game. It compares the state of the frame when it was executed the
 first time to the state executed during the rollback, and raises an error if they differ during your game's execution.
 If you set the [`LogLevel`](https://lucasteles.github.io/Backdash/api/Backdash.Core.LogLevel.html) to at
@@ -146,56 +172,76 @@ the rollback frame to track down errors.
 By running **sync-test** on developer systems continuously when writing game code, you can identify **de-sync** causing
 bugs immediately after they're introduced.
 
-You can also set the **sync-test session** to auto-generate random inputs to help find de-syncs:
+### Configuring
 
-```csharp
-using Backdash;
-using Backdash.Sync.Input;
+You can configure a wide range of options to help debug you state, like:
 
-var session = RollbackNetcode.CreateSyncTestSession<MyGameInput>(
-    options: new()
-    {
-        Log = new()
-        {
-            EnabledLevel = LogLevel.Debug,
-        },
-    },
-    services: new()
-    {
-        InputGenerator = new RandomInputGenerator<MyGameInput>(),
-    }
-);
+```csharp
+.ForSyncTest(options => options
+    .UseJsonStateParser() // tries to display you state as json on desync
+    .UseDesyncHandler<YourDesyncHandler>() // custom handler to deal wih a desync
+    .UseRandomInputProvider() // generate random inputs
+    .CheckDistance(4) // the forced rollback check distance in frames
+)
 ```
 
-If you want a meaningful string representation of your state in the sync-test, you need to implement
- the method `GetStateString` in your handler.
+If you need better meaningful string representation of your state in the sync-test, it is recommended to implement
+the optional method `INetcodeSessionHandler.CreateState`. This will be used to materialize previous saved states
+before passing them to the `DesyncHandler`.
 
-```csharp
-// print the state as json
-public string GetStateString(in Frame frame, ref readonly BinaryBufferReader reader)
-{
-    GameState state = new();
+> [!NOTE]
+> The `.UseJsonStateParser()` will only work if `INetcodeSessionHandler.CreateState` returns a JSON serializable object.
 
-    state.LoadState(in reader); // read and fill the state properties
+#### Implement a DesyncHandler
 
-    return JsonSerializer.Serialize(state, jsonOptions);
-}
+a `DesyncHandler` will help you to handle whenever a desync happens in a `SyncTest` session.
 
-static readonly JsonSerializerOptions jsonOptions = new()
-{
-    WriteIndented = true,
-    IncludeFields = true,
-};
+As example, a `DesyncHandler` that uses [DiffPlex](https://github.com/mmanela/diffplex) to print on the console
+the state diff when a desync occurs:
 
-```
+```csharp
+using Backdash;
+using Backdash.Synchronizing.State;
+using DiffPlex.DiffBuilder;
+using DiffPlex.DiffBuilder.Model;
 
-> [!NOTE]
-> For better debugging the `RollbackNetcode.WithInputType<>().ForSyncTest(...)` accepts an implementation of the `IStateDesyncHandler`
-> which is called whenever a state desync happens in the test.
->
-> You can use it for enhanced state logging or showing semantic diffs.
+sealed class DiffPlexDesyncHandler : IStateDesyncHandler
+{
+    public void Handle(INetcodeSession session, in StateSnapshot previous, in StateSnapshot current)
+    {
+        var diff = InlineDiffBuilder.Diff(previous.Value, current.Value);
+
+        var savedColor = Console.ForegroundColor;
 
+        foreach (var line in diff.Lines)
+        {
+            switch (line.Type)
+            {
+                case ChangeType.Inserted:
+                    Console.ForegroundColor = ConsoleColor.Green;
+                    Console.Write("+ ");
+                    break;
+                case ChangeType.Deleted:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Write("- ");
+                    break;
+                default:
+                    Console.ForegroundColor = ConsoleColor.Gray;
+                    Console.Write("  ");
+                    break;
+            }
+
+            Console.WriteLine(line.Text);
+        }
+
+        Console.ForegroundColor = savedColor;
+    }
+}
+```
 
+> [!TIP]
+> You can see this implementation working with JSON in
+> the [SpaceWar](https://github.com/lucasteles/Backdash/tree/master/samples/SpaceWar) sample.
 
 ## Where to Go from Here
 

samples/SpaceWar.Shared/GameSession.cs

@@ -71,6 +71,30 @@ void Log(string message)
         Console.WriteLine(message);
     }
 
+    public void SaveState(in Frame frame, ref readonly BinaryBufferWriter writer)
+    {
+        // UNCOMMENT TO FORCE DESYNC ON FRAME 200
+#pragma warning disable S125
+        // if (frame.Number is 200)
+        //     gameState.FrameNumber = Random.Shared.Next(1000, 2000);
+#pragma warning restore S125
+
+        gameState.SaveState(in writer);
+    }
+
+    public void LoadState(in Frame frame, ref readonly BinaryBufferReader reader)
+    {
+        Log($"=> LOADING STATE {frame}...");
+        gameState.LoadState(in reader);
+    }
+
+    public void AdvanceFrame()
+    {
+        session.SynchronizeInputs();
+        gameState.Update(session.CurrentSynchronizedInputs);
+        session.AdvanceFrame();
+    }
+
     public void OnSessionStart()
     {
         Log("=> GAME STARTED");
@@ -93,18 +117,9 @@ public void TimeSync(FrameSpan framesAhead)
     void UpdateStats()
     {
         nonGameState.RollbackFrames = session.RollbackFrames;
-
         var saved = session.GetCurrentSavedFrame();
         nonGameState.StateChecksum = saved.Checksum;
         nonGameState.StateSize = saved.Size;
-
-        for (var i = 0; i < nonGameState.Players.Length; i++)
-        {
-            ref var info = ref nonGameState.Players[i];
-            if (!info.PlayerHandle.IsRemote())
-                continue;
-            session.UpdateNetworkStats(info.PlayerHandle);
-        }
     }
 
     public void OnPeerEvent(NetcodePlayer player, PeerEventInfo evt)
@@ -143,23 +158,8 @@ public void OnPeerEvent(NetcodePlayer player, PeerEventInfo evt)
         }
     }
 
-    public void SaveState(in Frame frame, ref readonly BinaryBufferWriter writer) =>
-        gameState.SaveState(in writer);
-
-    public void LoadState(in Frame frame, ref readonly BinaryBufferReader reader)
-    {
-        Log($"=> LOADING STATE {frame}...");
-        gameState.LoadState(in reader);
-    }
-
-    public void AdvanceFrame()
-    {
-        session.SynchronizeInputs();
-        gameState.Update(session.CurrentSynchronizedInputs);
-        session.AdvanceFrame();
-    }
-
-    object INetcodeSessionHandler.ParseState(in Frame frame, ref readonly BinaryBufferReader reader)
+    // used by SyncTest, the return value is used on the state desync handler call
+    object INetcodeSessionHandler.CreateState(in Frame frame, ref readonly BinaryBufferReader reader)
     {
         GameState state = new();
         state.LoadState(in reader);

samples/SpaceWar/Program.cs

@@ -61,14 +61,18 @@ static INetcodeSession<PlayerInputs> ParseSessionArgs(string[] args)
         case ["sync-test-auto", ..]:
             return builder
                 .ForSyncTest(options => options
-                    .UseJsonStateViewer()
+                    .UseJsonStateParser()
+                    .UseDesyncHandler<DiffPlexDesyncHandler>()
                     .UseRandomInputProvider()
                 )
                 .Build();
 
         case ["sync-test", ..]:
             return builder
-                .ForSyncTest(options => options.UseJsonStateViewer())
+                .ForSyncTest(options => options
+                    .UseJsonStateParser()
+                    .UseDesyncHandler<DiffPlexDesyncHandler>()
+                )
                 .Build();
 
         default:

samples/SpaceWar/SpaceWar.csproj

@@ -24,4 +24,7 @@
     <ItemGroup>
         <ProjectReference Include="..\SpaceWar.Shared\SpaceWar.Shared.csproj"/>
     </ItemGroup>
+    <ItemGroup>
+      <PackageReference Include="DiffPlex" Version="1.7.2" />
+    </ItemGroup>
 </Project>

samples/SpaceWar/Utils/DesyncHandler.cs

@@ -0,0 +1,42 @@
+using Backdash;
+using Backdash.Synchronizing.State;
+using DiffPlex.DiffBuilder;
+using DiffPlex.DiffBuilder.Model;
+
+namespace SpaceWar;
+
+/// <summary>
+/// This prints the text diff of a state when a desync happens over a SyncTest session.
+/// </summary>
+sealed class DiffPlexDesyncHandler : IStateDesyncHandler
+{
+    public void Handle(INetcodeSession session, in StateSnapshot previous, in StateSnapshot current)
+    {
+        var diff = InlineDiffBuilder.Diff(previous.Value, current.Value);
+
+        var savedColor = Console.ForegroundColor;
+
+        foreach (var line in diff.Lines)
+        {
+            switch (line.Type)
+            {
+                case ChangeType.Inserted:
+                    Console.ForegroundColor = ConsoleColor.Green;
+                    Console.Write("+ ");
+                    break;
+                case ChangeType.Deleted:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Write("- ");
+                    break;
+                default:
+                    Console.ForegroundColor = ConsoleColor.Gray;
+                    Console.Write("  ");
+                    break;
+            }
+
+            Console.WriteLine(line.Text);
+        }
+
+        Console.ForegroundColor = savedColor;
+    }
+}