Handling unstable connections

Your game needs to handle unstable connections and high latency. In this guide you will learn about properly handling unstable connections (Such as in cars, unstable 4G/Wi-Fi networks)

The AirConsole API makes sure that no messages and updates from the Screen and the Controllers are lost. A message or update sent by a device is guaranteed to arrive at some point in the right order even if the internet connection was disrupted, but the latency can be high.

If a request fails before onReady is called in the API, we will reload the entire game. But once onReady was called, you have to reload resources that fail to load yourself. The best practice is to load all resources before onReady if you know that they are going to be used. Additional levels and big data files should still be loaded on demand at a later point, but you are responsible to handle load failures/retries.

General

When a device such as a car's infotainment screen loses the internet connection (E.g. in a tunnel), the inputs from the Controllers will not arrive on time. When AirConsole detects a very high latency or temporary disconnect from the internet, the onPause() method will be called, and you should immediately pause the game and all audio. You don't need to inform the user about pausing the game since AirConsole will provide a pause overlay on the screen and all controllers.

Sometimes, there may be a delay in displaying the pause overlay on Controllers. This happens when the connection between the Controllers and the screen is completely lost, but as soon as the connection is re-established, the pause overlay will appear.

Once the internet connection conditions are back to normal, AirConsole will call onResume(), and you should resume the game and all sounds. AirConsole will show a countdown overlay for 3 seconds before onResume event is called.

onPause() / onResume() methods were added in AirConsole API 1.8.0. You can test them in the AirConsole Simulator if you are using at least API version 1.8.0.

Testing

Please include these following cases in your tests:

The Screen is disconnected from the internet while the game is loading and the onPause() function is called. When the game loads, it calls the onReady() callback function. AirConsole will call the onPause() function right after it executes the onReady() function from the game that just loaded. Make sure that this is handled properly and that you pause any game logic, intro videos or other background music immediately.

Steps: Load your game preview in the AirConsole Simulator, e.g.: https://www.airconsole.com/simulator/#https://game.airconsole.com/com.your.game/2023-06-07-16-06-19/ with Pause on start selected.

Expected: The game should be paused and not producing any sounds (E.g. background music, intro sound/music, video intro, etc.)

Disconnecting the Screen from the internet while playing the game should pause the game and all sounds in the game.

Steps:

Expected: The game should be paused and not producing any sounds (E.g. background music, intro sound/music, video intro, etc.)

Calling the onPause() function multiple times will not cause any issues.

The game should remain paused and not exhibit different behavior even if onPause() is called repeatedly.

Steps: Simulate calling the onPause() function multiple times (without calling onResume() in between).

Expected: Invoking onPause() on an already paused game should keep the game in a paused state.

Calling the onResume() function multiple times will not cause any issues.

The game should remain active and not exhibit different behavior even if onResume() is called repeatedly.

Steps: Simulate calling the onResume() function multiple times (without calling onPause() in between).

Expected: Invoking onResume() on an already active game should keep the game active. It should not pause the game or behave differently even if called multiple times.

General

Input latency from Controllers can be significantly higher in cars. The API call getServerTime() provides a synchronized clock between the devices.

For example in a Quiz game, this timestamp can be sent from the Controller to the Screen. If Controllers have different latency, you can still determine the correct winner by looking at all timestamps received from the Controllers to compare the real user input times.

This can be applied to almost any game. You can determine the latency of a message by sending the getServerTime() timestamp from the Controller to the Screen and compare it with the getServerTime() on the Screen. Once you know how many milliseconds the message took, you can consider this in your input. (E.g. rewind the game by X milliseconds, add the input, fast-forward X milliseconds again).

Testing

The best way to simulate a high latency between the controller and the screen is to use a VPN. The Chrome Devtools Network option won't throttle the WebRTC connection, only the loading of the game assets.