Poor Connection Simulation Tool

Simulating a Spotty Connection

When running the game in the Unity Editor, you can find the connection simulation tool in the inspector of the MetaplaySDKBehavior component. Depending on the configuration, you can place the GameObject containing this component into the scene, or it will be automatically injected by the SDK. If the component is automatically injected, it will be in a MetaplaySDKBehavior GameObject. This tool requires an actual network connection and will not work in offline mode.

When the game is running, the tool shows two pieces of information about the client's internal connection state:

• Status is the current status of the network connection. This will be one of the states as described in Connection Management.
• Health displays the current value of Connection.IsHealthy.

The tool also allows you to set the Quality simulation value for the connection. The following modes are available:

• Perfect link chooses a mode where connection quality is not artificially worsened. This is the default.
• Spotty link chooses a mode where, every 3-5 seconds, the network connection either drops, no data is transmitted, or the network resumes a normal state. On each change, a log message is printed with a Spotty network updated prefix.
• No incoming data (silent network error) chooses a mode where the client apparently successfully writes data, but that data is not received by the server. Also, no data is received by the client. If the client is not connected, the connection does not succeed and will eventually time out.
• No network (active refusal) chooses a mode where the connection is actively refused by the backend or some hop along the way, such as the end-user device itself when it determines it has no connectivity.

Note that the mode can be switched at runtime, and this often is required for some test cases.

Simulating Latency

In addition, you can also use the tool to simulate latency by toggling the Enable Latency Simulation option while the game is not running. While latency simulation is enabled, you can freely change the added latency through the MetaplaySDKBehaviour component. Latency simulation is also available in builds; however, there is no readily available built-in UI to enable or change latency.

If you wish to enable latency simulation manually through code (to, for example, toggle it in a build), you can do so by adding a lambda that creates LatencySimulationMessageTransport to MetaplayClient.Connection.CreateTransportHooks before MetaplayClient.Connect() is called.

// Initialize Metaplay SDK.
MetaplayClient.Initialize(new MetaplayClientOptions { ... });

// You can use this instance later to modify the amount of added latency.
LatencySimulationMessageTransport latencySimulationMessageTransport;

// Add a lambda that wraps the internal MessageTransport with the LatencySimulationMessageTransport.
MetaplayClient.Connection.CreateTransportHooks.Add(createInnerTransport => serverGateway =>
{
    latencySimulationMessageTransport = new LatencySimulationMessageTransport(createInnerTransport(serverGateway));
    return latencySimulationMessageTransport;
});

MetaplayClient.Connect();

Example Scenarios

The tool can be used to test several different network scenarios; here are a few:

Testing that the game handles a loss of network connection

This simulates dropping from WiFi without a backup connection being available.

• Launch the game in Perfect link mode.
• At a desired point in the game lifecycle, toggle the mode to No network (active refusal).
• Observe that Connection.IsHealthy becomes Unhealthy.
• Observe that the game shows a connectivity warning to the user if this is expected.
• Wait a moment until the reconnect timeout passes.
• Observe that the connection errors out and Status becomes Error (or Connecting if the game automatically reconnects).
• Observe that the game ends the current session.

Testing that the game handles a loss of network transport

This simulates walking on the fringe of a WiFi range, where no data gets delivered, but the device still claims to have a working connection.

Launch the game in Perfect link mode.

• At the desired point in the game lifecycle, toggle the mode to No incoming data (silent network error).
• Wait for a ping timeout to pass.
• Observe that Connection.IsHealthy becomes Unhealthy.
• Observe that the game shows a connectivity warning to the user if this is expected.
• Wait a moment until the reconnect timeout passes.
• Observe that the connection errors out and Status becomes Error (or Connecting if the game automatically reconnects).
• Observe that the game ends the current session.

Testing that the game recovers from a temporary bad network event

This simulates temporary loss of network and recovery. This is expected to be transparent (with the exception of showing a connectivity warning).

• As before, start the game in Perfect link and then cause the desired kind of poor network connectivity.
• Wait until Connection.IsHealthy becomes Unhealthy.
• Restore the simulation back to Perfect link.
• Observe that the game resumes to a normal state. If a connectivity error was shown to the player, it disappears.

Alternatively, you can just leave the connectivity mode set to Spotty link and test the game normally. Note that the spottiness of Spotty link is random, and it might sometimes generate connectivity losses longer than the game’s maximum limit. This is intentional, as it allows for convenient testing of a range of different scenarios without additional effort.

Configuring Connectivity Settings

If you determine that the game is functioning as desired, but the default time limits in Metaplay SDK are unsuitable, you can change them. The connectivity rules and settings are defined in the following places:

• Connection.Config in MetaplayConnection defines client-side limits for a single connection. These default values can be overwritten after MetaplaySDK.Start and before Connection.Connect(). This can, for example, be used to make the connectivity warning appear faster (if your game requires better network connections) or slower (if you tolerate a worse connection).
• On the server side, PlayerOptions.ClientTimeMaxBehind and PlayerOptions.ClientTimeMaxAhead determine the temporal tolerances that the client must stay within. In practice, ClientTimeMaxBehind determines the maximum non-connectivity period.
• SessionActor.ShutdownPolicy determines the session linger time, i.e., the time that is still possible to transparently restore a session after a connection loss. Note that the linger timer starts when a connectivity loss is observed by the server. This is generally unobservable to the client - there is no guarantee the client has or will observe the connectivity loss in a timely fashion.
• In addition to these configurable values, there is a hard limit of 1 minute for client-to-server communication. If the server does not receive a heartbeat for one minute, the connection is terminated.