1 of 6

Game Services

Besides the core Replicator and Simulator, coherence offers additional services to enhance your game's experience and we are constantly working on more.

Currently available services are:

Enabling Game Services

In the Project sidebar, you can find links to each service. Each service has an enabled checkbox which you can tick to enable and disable those features:

Disabling a service will immediately remove that functionality from your game. Please disable with caution.

Account

Motivation

coherence provides an API for creating player game accounts that uniquely identify players across multiple devices. An account is required in order to use the rest of the online services, like the key-value store and matchmaking.

Account Types

There are two types of accounts that are currently supported - guest accounts and user accounts.

Guest Accounts

Guest accounts provide an easy way to start using the coherence online services without providing any user interface for user names or password. Everything is controlled with the API, and is completely transparent to the player.

The session data for the account is stored locally on the device so it is important to know that uninstalling the game will also wipe out all the data and the account will be no longer accessible even if the player installs the game again.

User Accounts

User accounts require explicit authorization by the player. Currently, only user name and password are supported as means for authentication. The user interface for entering the credentials must be provided by the game. Check the API how to use this feature.

In the future, there will be support for many more authentication mechanisms like Steam, Google Play Games, Sign in with Apple, etc.

Using game accounts

Please refer to the Cloud API: Game Accounts.

Key-Value Store

Motivation

coherence provides an API and a database for storing key-value pairs from within game sessions.

Description

The key-value store provides a simple way to store and retrieve data for the currently logged in player. For example, you could store the player's score, email address, or any other data.

This feature requires a game account.

Limitations

The keys must be alphanumerical strings, underscore or dash. Currently, only strings are accepted as values. If you need to store numbers or complex types like arrays, you have to convert them to strings.

The total amount of stored data (keys + values) cannot exceed 256 KB per player (TBD).

There is no limit how often the data is stored or retrieved.

Using key-value store

Please refer to the Cloud API: Key-value store.

API

Overview

The coherence Cloud API allows us to access online services like game accounts, key-value store, matchmaking, and others. It also allows you to get the addresses (IP and port number) of the Servers the players can connect to.

The Cloud API requires you to use.

List of endpoints

Game account

Creating a player account is the first step towards using the coherence Cloud API. It is required in order to use the rest of the services.

Initialization

To initialize the Cloud API you need to provide a that can be obtained from the .

Callbacks

Guest Account

The easiest way to get started is by using a guest account. The only thing that is needed is to call LoginAsGuest. This will create a random username / password combination and will authenticate the player with the coherence Cloud.

Once logged in, the credentials are securely persisted so that if the game is restarted the player will be able to log in automatically.

If the game is uninstalled then the account credentials will be lost and a new guest account will be created next time the game is installed.

User Account

Another alternative is to login with a username and a password. You have to provide the user interface.

Example

This example initializes the Cloud API, checks for an existing session and, if no session was found or if it expired, logs in the player as guest.

Key-value store

The key-value store provides a simple persistence layer for the players.

Coherence.Runtime.KvStore

The player needs need to be logged in to use the key-value store.

This class provides the methods to set, get and unset key-value pairs. This is executed within the context of the currently logged in player.

public static class KvStore
{
    // Sets a value
    // key: lowercase letters, numbers, underscore, dash
    // val: any string (null is not allowed)
    public static void Set(string key, string val)
    
    // Gets a value
    // key: lowercase letters, numbers, underscore, dash
    public static string Get(string key)
    
    // Unsets a value, removing it from the store
    // key: lowercase letters, numbers, underscore, dash
    public static void Unset(string key)
}

Example

Coherence.Runtime.KvStore.Set("foo", "1");

var foo = Coherence.Runtime.KvStore.Get("foo");
Debug.Log(string.Format("foo={0}", foo)); // foo=1

Coherence.Runtime.KvStore.Unset("foo");

Limitations

Size: there are no limits to the number of stored key/values as long as the total size is less than 256 kB.

Requests: Set/Get/Unset can be called unlimited amount of times but the execution may be throttled.

Account

Motivation

Account Types

There are two types of accounts that are currently supported - guest accounts and user accounts.

Guest Accounts

User Accounts

In the future, there will be support for many more authentication mechanisms like Steam, Google Play Games, Sign in with Apple, etc.

Using game accounts

Please refer to the Cloud API: Game Accounts.

Key-value store

The key-value store provides a simple persistence layer for the players.

Coherence.Runtime.KvStore

The player needs need to be logged in to use the key-value store.

This class provides the methods to set, get and unset key-value pairs. This is executed within the context of the currently logged in player.

public static class KvStore
{
    // Sets a value
    // key: lowercase letters, numbers, underscore, dash
    // val: any string (null is not allowed)
    public static void Set(string key, string val)
    
    // Gets a value
    // key: lowercase letters, numbers, underscore, dash
    public static string Get(string key)
    
    // Unsets a value, removing it from the store
    // key: lowercase letters, numbers, underscore, dash
    public static void Unset(string key)
}

Example

Coherence.Runtime.KvStore.Set("foo", "1");

var foo = Coherence.Runtime.KvStore.Get("foo");
Debug.Log(string.Format("foo={0}", foo)); // foo=1

Coherence.Runtime.KvStore.Unset("foo");

Limitations

Size: there are no limits to the number of stored key/values as long as the total size is less than 256 kB.

Requests: Set/Get/Unset can be called unlimited amount of times but the execution may be throttled.

Game account

Creating a player account is the first step towards using the coherence Cloud API. It is required in order to use the rest of the services.

Initialization

To initialize the Cloud API you need to provide a that can be obtained from the .

Callbacks

Guest Account

Once logged in, the credentials are securely persisted so that if the game is restarted the player will be able to log in automatically.

If the game is uninstalled then the account credentials will be lost and a new guest account will be created next time the game is installed.

public static class Auth
{
    // Authenticates the players as a guest.
    // callback - invoked upon completion.
    public static void LoginAsGuest(OnSession callback)
}

User Account

Another alternative is to login with a username and a password. You have to provide the user interface.

public static class Auth
{
    // Authenticates the player with a username and a password.
    // userName   - any combination of letters, numbers, underscore and dash.
    // password   - any combination of ASCII characters
    // autosignup - whether to create an account automatically if it
    //              doesn't exist and the username is not taken
    // callback   - invoked upon completion
    public static void LoginAsUser(string userName, string password,
        bool autosignup, OnSession callback)
}

Example

This example initializes the Cloud API, checks for an existing session and, if no session was found or if it expired, logs in the player as guest.

using Coherence;
using Coherence.Runtime;
using UnityEngine;

public class ExampleLogin : MonoBehaviour
{
    void OnLogin()
    {
        Debug.Log(string.Format("Logged in. UserName={0}", Auth.UserName));
    }

    async void Start()
    {
        // Initialise the Cloud API
        Play.Init(RuntimeSettings.instance);

        // Check for existing session
        var res = await Auth.IsLoggedIn();
        if (res == Result.Success)
        {
            // Session resumed
            OnLogin();
            return;
        }
        else if (res == Result.SessionExpired || res == Result.UserNotFound)
        {
            // No session found, or session expired. Proceed with normal login.
            res = await Auth.LoginAsGuest();
            if (res == Result.Success)
            {
                OnLogin();
                return;
            }
        }

        UnityEngine.Debug.LogError(string.Format("Could not login. Error={0}", res));
    }
}