Offline Support
By using the Unity SDK for Hiro, you are able to make use of the “Offline Support” feature. This will allow many Hiro systems to store state locally on the player’s device. Later on, when the device is able to connect to your Nakama backend, this locally stored state will be synced back to the server and cleared locally to free up any space that was being used.
For Hiro systems that support offline mode, implementing it doesn’t require any change to how you write your gameplay logic. Hiro handles local state management and syncing behind the scenes. All that is required is some simple configuration in your HiroCoordinator script, demonstrated below.
Offline Support only works on devices that have connected your Nakama server at least once, so that the client can pull configurations from the server. Once the first connection has been made, the game can be played offline by using the latest data from the server. Future updates to the game will only be seen once the game client connects to the server for a sync.
Supported Systems #
Certain systems cannot function without a network connection due to their nature, such as Teams, which requires direct interaction with other players. Accordingly, only a subset of systems have Offline Support capability.
Here is a list of all the systems that have Offline Support:
Even these systems that have offline capabilities might not have 100% support for all their features. For example, the Economy system has Offline Support, the player can gain soft currency while offline, but can’t purchase hard currency due to requiring an online connection to process the online payments.
Reachability Probes #
For your Unity client to be able to detect whether it is online or offline you must register at least one INetworkProbe. You can implement your own custom INetworkProbe if you have a very specific use case, however, we supply a few implementations out of the box that should handle the majority of use cases.
ALL registered network probes must determine that Online == true, otherwise offline mode will be entered. While only a small optimization, it is recommended to register your probes in this order if you are using more than one. This is in order of how easy/fast it is to be certain that there is no connectivity, and return early to save having to check the other probes.
ForceNetworkProbe #
Allows the developer to keep reference to the probe and set the Online property to false to manually enter offline mode. This can be useful to reduce the number of network calls when playing parts of the game where being online isn’t necessary. The Online property can then be switched back to true when you want to sync and start receiving network updates again.
InternetReachabilityNetworkProbe #
Uses Unity’s Application.internetReachability static property to determine whether Wi-Fi/Cellular Data is enabled on the device or not. This does not guarantee internet reachability, but if this is turned off, we can be certain that internet reachability is impossible.
NakamaClientNetworkProbe #
Updates online state based on whether calls to your Nakama server have been successful recently. An interval for checking can be configured to reduce connectivity jitter when rapidly gaining and losing network connection. This is done by staying in offline mode for interval seconds, even when back online.
Server Setup #
You must initialize the base system for offline support to work. Set the second argument of WithBaseSystem to true to register the base system RPCs, including the Sync RPC that the client calls to send offline changes to the server.
| |
Unity Setup #
Here is how you would set up Offline Support in your HiroCoordinator script. Keep in mind that you don’t need to use all of the network probes shown here, this is just an example that uses them all together.
If your game doesn’t use Offline Support, create the NetworkMonitor without any probes and set AutoSync to false on the systems container. Otherwise, the client calls the Sync RPC on startup, which fails with RPC function not found if the server doesn’t register the base system RPCs.
| |
| |
Custom RPC Calls #
Direct calls made to Nakama via custom RPCs are not automatically guarded against network failures. You need to check connectivity yourself before making them.
Check _monitor.Online before any custom Nakama call:
| |
Syncing Objects #
On the Client #
The client syncs local state deltas back to the server when the systems initialize and each time the device regains a connection. To sync at any other time, call SyncAsync:
| |
SyncAsync does nothing if a sync is already in progress.
Turn off automatic syncs #
To control when syncs happen, or if your server doesn’t register the base system RPCs, set AutoSync to false on the systems container. The client then skips the syncs on initialization and on reconnect, and only syncs when you call SyncAsync. The ConnectivityChanged event still fires when the device goes offline or comes back online.
| |
Setting AutoSync back to true while online starts a sync immediately. Await SyncTask to wait for it to finish:
| |
Keep these behaviors in mind:
- Set
AutoSyncfrom the main thread. - Turning
AutoSyncoff doesn’t cancel a sync that’s already in progress.
On the Server #
When each client submits their sync data, the server will process the offline state deltas, then return the entire up to date server state.
