Skip to main content

Network Simulator

The Network Simulator tool allows you to test your multiplayer game in less-than-ideal network conditions, enabling you to discover issues in simulated real-world scenarios and fix them before they surface in production. It facilitates simulating network events, such as network disconnects, lag spikes, and packet loss.

The tool exposes configurable network parameters, such as packet delay and packet loss, that allow you to control the network conditions. It also bundles common configurations of those parameters together as presets.

You can use the Network Simulator component to test different network conditions and create custom network scenarios. These utilities include:

You can also use the Network Simulator SDK to create custom network scenarios that can automatically trigger network events (such as a lag spike) at specific frequencies and intervals. To help you get started, it includes several example network scenarios.

note

Note: All parameters exposed through the Network Simulator tool work with the Unity Transport Protocol (UTP) simulator pipeline stage.

Requirements#

The only requirement for using Network Simulator is theUnity Editor version 2022.2 and later and the following package dependencies.

Package dependencies#

DependencyVersionPackage name
Unity Transport2.0.0 or latercom.unity.transport >= 2.0.0
Netcode for GameObjects1.1.0 or latercom.unity.netcode.gameobjects >= 1.1.0

Get started#

To get started with the Network Simulator:

  1. Add the following packages:
    1. Tools 1.1.0 or later
    2. Network for GameObjects 1.1.0 or later
    3. Unity Transport 2.0.0 or later
  2. Add the NetworkSimulator Component to any GameObject that persisted across scenes.

Trigger a network disconnect#

You can trigger a network disconnect in the Unity Editor with the Network Simulator component by setting the Connection to Disconnected. See the Disconnect scenario example.

Trigger a lag spike#

You can trigger a simulated lag spike in the Unity Editor with the Network Simulator component by setting the Duration of the lag spike (ms), then selecting Trigger.

tip

Tip: You can trigger lag spikes through code with the NetworkSimulator.TriggerLagSpike API or you can write a Network Scenario that triggers it. See the Lag spike scenario example to learn how.

Use a Network Simulator Preset#

The Network Simulator tool comes packaged with configuration presets that simulate common network conditions, such as a home broadband connection or a mobile 3G connection. To use one of the configuration presets:

  1. Select the NetworkSimulator component from the Hierarchy tab.
  2. Set the Connection Preset field to the configuration you want to use.

Create a Network Simulator Preset#

The Network Simulator tool allows you to create any number of custom network configuration presets. To create a custom network configuration preset:

  1. Right-click on the Assets folder in the Project tab.
  2. Select Create > Multiplayer > NetworkSimulatorPresetAsset.
  3. Select the NetworkSimulatorPreset from the Assets folder.
  4. Edit the parameters in the Inspector tab. The parameters allow you to set the name, description, packet delay, packet jitter, and packet loss (as a percentage and interval).

To use a custom Network Simulator Preset:

  1. In the Inspector tab, set the Connection Preset to Custom.
  2. Set the Custom Preset field to the preset asset you created.

Once you select the custom preset asset, you can edit it live from the Inspector tab by adjusting the parameters.

Use a Network Scenario#

The Network Simulator tool supports NetworkScenarios. A NetworkScenario is a way to script how you want to affect the network conditions at runtime. They allow you to change parameters and presets dynamically.

It comes packaged with a couple network scenarios presets, such as the Connections Cycle and Random Connections Swap.

note

To use a network scenario:

  1. Select the NetworkSimulator component from the Hierarchy tab.
  2. Under Network Scenarios in the Inspector tab, set the Scenario field to the network scenario you want to use.

tip

Tip: You can control whether the Network Scenario runs automatically by toggling the Auto Run Scenario checkbox. You can also set this option dynamically via code.

Connections Cycle#

The Connections Cycle Network Scenario allows you to cycle through different network conditions at specific intervals. By default, it includes one cycle that’s set to None. To configure the Connection Cycle:

  1. From the Inspector tab, expand the Network Scenarios > Configurations section.

  1. Set the first Connection Preset to a built-in preset or a custom preset.

  1. Set the Change Interval Milliseconds field to the time to wait before switching to the next preset.

  1. Select the plus (+) symbol to add another cycle.

  1. Configure the next cycle as you see fit.

The Connections Cycle scenario cycles through the configurations list at the Change Interval until you use the Pause button to pause the connection cycling.

Random Connections Swap#

The Random Connections Swap Network Scenario allows you to specify a set of network configuration presets to swap through at random. By default, it includes one cycle that’s set to None. To configure the Random Connection Swap:

  1. From the Inspector tab, expand the Network Scenarios > Configurations section.

  1. Set the Class Preset to a built-in preset or a custom preset.

  1. Select the plus (+) symbol to add another configuration.

  1. Configure the configuration as you see fit.

\

The Random Connections Swap scenario selects one of configurations from the list at random at the Change Interval until you use the Pause button to pause the connection cycling.

Network types#

A network type is the general state of a user’s network connection. This section has the descriptions of the available Network Simulator preset configurations. These configuration presets fall into five categories:

Home broadband connections#

A typical home broadband connection preset represents common connections from desktops, console platforms, and some mobile devices.

The Home Broadband Network Simulator presets simulates a good-quality mobile connection

Poor-quality mobile connections#

A poor-quality mobile connection preset represents an extremely poor connection, entirely unsuitable for synchronous multiplayer gaming due to exceptionally high ping. However, it might work for some turn-based games.

The following Network Simulator presets simulate a poor-quality mobile connection:

Medium-quality mobile connections#

A medium-quality mobile connection preset represents the minimum supported mobile connection for synchronous gameplay. Expect high pings, jitter, stuttering, and packet loss.

The Mobile 3.5G Network Simulator presets simulates a medium-quality mobile connection.

Decent-quality mobile connections#

A decent-quality mobile connection preset represents a suitable network for synchronous multiplayer. However, the ping and overall connection quality and stability might result in poor player experience due to packet drops. Players might drop all packets in bursts of one to 60 seconds, so you must ensure you handle reconnections.

The following Network Simulator presets simulate a poor quality mobile connection:

Good quality mobile connections#

A good quality mobile connection preset represents a mobile connection comparable to or better than a typical home broadband connection.

The Mobile 5G Network Simulator preset simulates a good-quality mobile connection

Network configuration presets#

A network configuration preset is a bundle of Network Simulator parameters that simulate a common network connection type. This section covers the available Network Simulator configuration presets.

Home Broadband#

The Home Broadband network simulation preset simulates a typical home broadband connection.

NameHome Broadband [WIFI, Cable, Console, PC]
DescriptionSimulates a typical home broadband connection.
Packet delay (ms)32
Packet jitter (ms)12
Packet loss interval0
Packet loss percent2

Mobile 2G#

The Mobile 2G network simulation preset simulates a typical 2G mobile connection.

NameMobile 2G [CDMA & GSM, '00]
DescriptionSimulates a poor-quality mobile connection.
Packet delay (ms)400
Packet jitter (ms)200
Packet loss interval0
Packet loss percent3

Mobile 2.5G#

The Mobile 2.5G network simulation preset simulates a typical 2.5G (GPRS) mobile connection.

NameMobile 2.5G [GPRS, G, '00]
DescriptionSimulates a poor-quality mobile connection.
Packet delay (ms)200
Packet jitter (ms)100
Packet loss interval0
Packet loss percent3

Mobile 2.75G#

The Mobile 2.75G network simulation preset simulates a typical 2.75G (EDGE) mobile connection.

NameMobile 3.75G [HDSDPA+, H+, '11]
DescriptionSimulates a decent-quality mobile connection.
Packet delay (ms)75
Packet jitter (ms)50
Packet loss interval0
Packet loss percent3

Mobile 3G#

The Mobile 3G network simulation preset simulates a typical 3G mobile connection.

NameMobile 3.75G [HDSDPA+, H+, '11]
DescriptionSimulates a decent-quality mobile connection.
Packet delay (ms)75
Packet jitter (ms)50
Packet loss interval0
Packet loss percent3

Mobile 3.5G#

The Mobile 3.5G network simulation preset simulates a typical 3.5G (HSDPA/H) mobile connection.

NameMobile 3.75G [HDSDPA+, H+, '11]
DescriptionSimulates a decent-quality mobile connection.
Packet delay (ms)75
Packet jitter (ms)50
Packet loss interval0
Packet loss percent3

Mobile 3.75G#

The Mobile 3.75G network simulation preset simulates a typical 3.75G (HSPA+/H+) mobile connection.

NameMobile 3.75G [HDSDPA+, H+, '11]
DescriptionSimulates a decent-quality mobile connection.
Packet delay (ms)75
Packet jitter (ms)50
Packet loss interval0
Packet loss percent3

Mobile 4G#

The Mobile 4G network simulation preset simulates a typical 4G (LTE) mobile connection.

NameMobile 4G [4G, LTE, '13]
DescriptionSimulates a decent-quality mobile connection.
Packet delay (ms)50
Packet jitter (ms)25
Packet loss interval0
Packet loss percent2

Mobile 4.5G#

The Mobile 4.5G network simulation preset simulates a typical 4.5G (LTE+) mobile connection.

NameMobile 4.5G [4G+, LTE-A, '16]
DescriptionSimulates a decent-quality mobile connection.
Packet delay (ms)50
Packet jitter (ms)25
Packet loss interval0
Packet loss percent2

Mobile 5G#

The Mobile 5G network simulation preset simulates a typical 5G mobile connection.

NameMobile 5G ['20]
DescriptionSimulates a good-quality mobile connection.
Packet delay (ms)1
Packet jitter (ms)10
Packet loss interval0
Packet loss percent2

Network events#

The following sections cover common network connection events and problems you can simulate with the Network Simulator.

Disconnects#

A network disconnect is a disruption or termination of the connection between the sender and the receiver.

You can trigger a network disconnect in the Unity Editor with the Network Simulator component by setting the Connection to Disconnected. See the Disconnect scenario example.

Lag spikes#

A lag spike refers to a temporary increase in network latency. Some of the most common causes of lag spikes include overburdened CPUs, temporary network disconnects, and unreliable connections with high jitter.

You can trigger a simulated lag spike in the Unity Editor with the Network Simulator component by setting the Duration of the lag spike (ms), then selecting Trigger. See the Lag spike scenario example.

Latency#

Network latency measures the time it takes a packet to travel across a network in milliseconds (ms). Players experience high latency (sometimes called “lag”) when the time delay between the server (or host) sending the information and the client receiving the information creates communication bottlenecks or an undesirable playing experience.

You can trigger control the simulated network latency in the Unity Editor with the Network Simulator component by setting the Packet Delay (ms) parameter.

note

Note: A common method of measuring the latency of a network connection is through ping messages. Pings are small network packets that you can use to measure the time it takes a packet to reach its destination in milliseconds. High ping often equates to high latency.

Packet loss#

Packet loss occurs when packets fail to reach their destination when transmitted across a network. It’s typically measured as a percentage of packets lost or the frequency of packets dropped.

You can trigger control the simulated packet loss in the Unity Editor with the Network Simulator component by setting the Packet Loss Interval and the Packet Loss (%) parameters.

Jitter#

Jitter is the variation in packet delays (latency) measured in milliseconds (ms). High-quality network connections typically have reliable and consistent latency. However, poorer-quality network connections experience high variations in latency, which can create an inconsistent or poor experience for players. These high variations in latency can cause issues such as flickering displays, stuttering, further packet delays, and additional CPU usage.

You can trigger control the simulated network jitter in the Unity Editor with the Network Simulator component by setting the Packet Jitter (ms) parameter.

Instability#

An unstable network connection might consist of intermittent network issues, such as network disconnects, packet loss, jitter, and latency.

See the Unstable connection scenario example.

Network scenarios#

Network scenarios are built-in (or custom) presets for network types that simulate a specific scenario, such as intermittent lag spikes. They allow you simulate a variable combination of issues and automatically switching configuration presets.

You can use the Network Simulator SDK to create custom network scenarios that automatically trigger network events (such as a lag spike) at specific frequencies and intervals.

The code samples in this section showcase how you can build custom network simulator scenarios.

Lag spike scenario#

The following code snippet shows using NetworkScenarioTask to create a custom network scenario that simulates a connection with lag spikes. See LagSpikeScenarioWithAsyncTask.cs.

Disconnect scenario#

The following code snippet uses NetworkScenarioBehaviour to create a custom network scenario that simulates a connection with frequent player disconnects. See DisconnectScenarioWithMonoBehaviour.cs.

Unstable connection scenario#

The following code snippet shows using NetworkScenarioTask to create a custom network scenario that simulates an unstable connection. See UnstableConnection.cs.

Affect connection parameters using Animation Curves scenario#

The following code snippet uses NetworkScenarioBehaviour to create a custom network scenario that simulates multiple connection problems. It dynamically changes multiple connection parameters using Animation Curves. See ConnectionParametersWithCurves.cs.

The sample scenario showcases a dynamic scenario using an animation curve loop with variable packet delays, packet jittering, and packet loss.