NativeWebSocket

The benchmark server is a Node.js application that acts as a WebSocket echo and flood server. It listens on ws://localhost:3000 by default. You can change the port by setting the PORT environment variable.

To start the server:

1. Navigate to the server directory.
2. Install dependencies.
3. Run the server.

cd benchmarks/server
npm install
node index.js

The console harness allows you to run comparisons between the old and new WebSocket implementations without opening the Unity editor. This is useful for rapid iteration on the benchmark logic itself.

cd benchmarks/ConsoleRunner
dotnet run -c Release

NativeWebSocket requires Unity 2019.1+ with .NET 4.x+ Runtime.

Important: Do not copy raw source files directly into your project, as the core WebSocket.cs requires build-time transformations for WebGL support. Use one of the following methods:

Via UPM (Unity Package Manager)

1. Open Unity and the Package Manager Window.
2. Click Add Package From Git URL.
3. Enter: https://github.com/endel/NativeWebSocket.git#upm-2

Note: For the legacy 1.x version, use https://github.com/endel/NativeWebSocket.git#upm.

Via .unitypackage

1. Download NativeWebSocket.unitypackage from the Releases page.
2. In Unity, go to Assets > Import Package > Custom Package and select the file.

Use the .NET CLI to add the necessary packages:

For MonoGame:

dotnet add package Colyseus.NativeWebSocket
dotnet add package Colyseus.NativeWebSocket.MonoGame

For Godot (C#):

dotnet add package Colyseus.NativeWebSocket

To test the new universal implementation:

1. Create a new Unity project (version 2019.4+).
2. Copy the contents of BenchmarkNew/Assets/ into your project's Assets/ folder.
3. Create an empty scene and add an empty GameObject with the BenchmarkRunner component.
4. In the Inspector, ensure implementationName is set to "new".
5. Press Play.

To test the legacy implementation:

1. Create a new Unity project (version 2019.4+).
2. Copy the contents of BenchmarkOld/Assets/ into your project's Assets/ folder.
3. Create an empty scene and add an empty GameObject with the BenchmarkRunner component.
4. In the Inspector, ensure implementationName is set to "old".
5. Press Play.

Use the provided Python script to aggregate multiple CSV runs and compare the performance of the old baseline against the new candidate implementation.

Available Filters:

• --benchmarks: Filter by benchmark name (e.g., Throughput_Recv, FrameTime_Dispatch, Burst).
• --metrics: Filter by specific metrics (e.g., msgs_per_sec, avg_ms, p95_ms, p99_ms, total_time_ms).
• --payloads: Filter by payload sizes (e.g., 32 256 1024).

python3 benchmarks/compare_results.py \
  /path/to/benchmark_old_sync.csv \
  /path/to/benchmark_old_sync_2.csv \
  /path/to/benchmark_new_sync.csv \
  /path/to/benchmark_new_sync_2.csv \
  --baseline old \
  --candidate new

You can run targeted Unity benchmarks (receive throughput, frame time, and burst tests) using the BenchmarkBatchRunner.RunSyncContextBenchmarks asset. This runs in Unity batchmode, writes results to a CSV, and exits.

Use the following command-line arguments to configure the run:

• -benchmarkImplementation <old|new>: Select the implementation to test.
• -benchmarkOutput <path>: Specify the output CSV file path.
• -benchmarkThroughputDuration <seconds>: Duration of the throughput test.
• -benchmarkPayloadSizes <comma_separated_sizes>: e.g., 32,256,1024,8192,65536.

In environments without a SynchronizationContext (like a standard Console application), you must manually call DispatchMessageQueue() from your main loop to process queued events.

var ws = new WebSocket("ws://localhost:3000");
ws.OnMessage += (bytes) => Console.WriteLine("Received " + bytes.Length + " bytes");
_ = ws.Connect();

while (true)
{
    ws.DispatchMessageQueue();
    Thread.Sleep(16);
}