SimNetLab

SimNetLab is a C++23 bachelor research project developed over approximately 14 weeks.

It investigates how snapshot replication techniques affect bandwidth, packet submissions, representation quality, recovery behavior, and processing cost in a server-authoritative ECS simulation.

Techniques

• Selection and scheduling: Radius and field-of-view AOI, every-tick and reduced cadence, and distance-band LOD.
• Representation: Raw records, position quantization, octahedral heading encoding, and 128-bit bit-packed records.
• Update reduction: Whole-record and field-mask Delta encoding.
• Delivery: Reliable and unreliable sequenced delivery with bounded application packetization.
• Compression: No compression, whole-update ordinary Zstd, and per-packet ordinary Zstd.
• Workloads: Authoritative boids and controlled synthetic Delta workloads.

The pipeline describes selection, representation, Delta, AOI, LOD, and encoding. See compression, packetization, transport, and synthetic workloads for details.

Measurements

Server replication CSV v4 records one row per replication attempt. Client replication CSV v4 records one row per received Snapshot-lane application packet. Analysis combines those rows into one result per complete Server and Client run.

The headless builds exclude rendering and Tracy. Whole-process perf stat measurements use separate executions from semantic CSV measurements. See BENCHMARKING.md for details.

Requirements

• Linux
• CMake and Ninja
• Git
• A C++23 compiler with named-module support
• Dependencies supplied through the vcpkg submodule
• Raylib only for optional rendering

The final headless benchmark builds were validated with GNU C++ 16.2.1. Raylib is required only for optional visual builds, which are excluded from benchmark runs.

Setup

Clone with submodules and run the bootstrap script:

git clone --recurse-submodules https://github.com/V4LKdev/SimNetLab.git
cd SimNetLab
./bootstrap.sh

The script initializes the vcpkg submodule, bootstraps vcpkg when needed, configures the Debug preset, and builds it. The following CMake commands are the equivalent manual commands. Run the test preset afterward:

cmake --preset debug
cmake --build --preset debug
ctest --preset debug

Headless builds

cmake --preset evidence
cmake --build --preset evidence

cmake --preset evidence-synthetic
cmake --build --preset evidence-synthetic

Both presets produce headless Release Server and Client executables. Only the synthetic build includes synthetic workload support.

Headless run

Start Server and Client in separate terminals with the same shared profile and run ID.

build/evidence/app/Server \
  --config config/server_default.json \
  --shared-config config/shared_demo_network.json \
  --run-id example-headless \
  --max-ticks 600

build/evidence/app/Client \
  --config config/client_default.json \
  --shared-config config/shared_demo_network.json \
  --run-id example-headless \
  --max-ticks 600

The tick limit only keeps the example bounded. It is not an experiment prescription.

Visual demo

With relWithDebInfo built, start the visual Server and Client in separate terminals:

build/relWithDebInfo/app/Server \
  --config config/server_visual.json \
  --shared-config config/shared_demo_visual.json

build/relWithDebInfo/app/Client \
  --config config/client_visual.json \
  --shared-config config/shared_demo_visual.json

Visual state is for demonstration and diagnosis. See render and configuration for details.

Structure

• app/server and app/client compose and orchestrate the executable runtimes. app/common provides the shared application protocol and delivery state.
• simnet_core defines bytes, identifiers, math, and fixed-step types.
• simnet_runtime plans fixed-step frames and evaluates runtime limits.
• simnet_config loads strict JSON configuration and computes fingerprints.
• simnet_snapshot defines complete snapshots, patches, validation, and reconstruction.
• simnet_pipeline selects, transforms, encodes, and decodes snapshot updates.
• simnet_compression provides bounded Raw and ordinary Zstd envelopes.
• simnet_packetization splits and reassembles bounded application packet groups.
• simnet_transport provides ENet sessions and opaque byte delivery.
• simnet_game_server runs the authoritative Flecs simulation.
• simnet_game_client applies reconstructed state to the Client Flecs sink.
• simnet_spatial provides deterministic sparse-grid queries.
• simnet_synthetic creates controlled deterministic snapshot workloads.
• simnet_telemetry provides logging and versioned CSV persistence.
• simnet_render provides the optional Raylib demonstration.

Scope and limitations

• SimNetLab is Linux-focused.
• ENet is the only transport.
• Reported transport bytes are application payload bytes accepted by ENet. They exclude lower-level protocol overhead and physical network traffic.
• The Client has no prediction.
• Packet-loss recovery requires controlled and documented network impairment.