Cloud Storage

Store data in the cloud

Cloud Storage is a general data storage service offered within the coherence Cloud.

Storage Object Identifier

Objects stored in cloud storage are identified using a tuple called storage object identifier or StorageObjectId.

The storage object identifier consists of a type and an id. Type is intended to describe the general category that the object belongs to - for example, "Player" or "Settings" - and id is intended to uniquely distinguish the object from all other objects with the same type.

For example, to store player-specific data in cloud storage, you can set id to be the identifier of a user that has logged in to coherence Cloud:

StorageObjectId playerInventoryId = ("PlayerInventory", user.UserId);

The StorageObjectId type is serializable by Unity, and can also be edited using the Inspector as a serialized field.

public StorageObjectId objectId = ("Level", Guid.NewGuid());

Usage

You must be logged in coherence Cloud to use this service. Read more about authentication on the Player Account Authentication page.

The CloudStorage API provides three methods, allowing you to save, load and delete objects.

Saving Objects

The SaveObjectAsync method can be used to save an object to cloud storage.

using Coherence.Toolkit;
using UnityEngine;

class SaveExample : MonoBehaviour
{
    public StorageObjectId objectId = ("Greeter", 1);
    public CoherenceBridge bridge = null!;

    CloudStorage CloudStorage => bridge.CloudService.GameServices.CloudStorage;

    async void Start()
    {
        // Save the string "Hello, World!" in cloud storage:
        await CloudStorage.SaveObjectAsync(objectId, "Hello, World!");
    }
}

Loading Objects

The LoadObjectAsync method can be used to load an object from cloud storage.

async void Start()
{
    // Load a string from cloud storage:
    string text = await CloudStorage.LoadObjectAsync(objectId);
    Debug.Log(text);
}

Deleting Objects

The DeleteObjectAsync method can be used to delete an object from cloud storage.

async void Start()
{
    // Delete a string from cloud storage:
    await CloudStorage.DeleteObjectAsync(objectId);
}

Storage Operation

All of CloudStorage's methods return a StorageOperation or a StorageOperation<TResult>.

Async Methods

These are Task-like objects. Methods that contain the async keyword can use await to wait for the operation to complete:

async void AsyncMethod(StorageOperation operation)
{
    await operation;
    Debug.Log(operation);
}

Coroutines

Coroutines can also use yield return to wait for the operation to complete:

IEnumerator Coroutine(StorageOperation operation)
{
    yield return operation;
    Debug.Log(operation);
}

Callbacks

It is also possible to execute a function when the operation completes successfully or fails, using OnSuccess and OnFail respectively.

void Method(StorageOperation<string> operation)
{
    operation.OnSuccess(result => Debug.Log($"Result: {result}"));
             .OnFail(error => Debug.LogWarning(error));
}

If you need further info on how to do asynchronous programming within Unity, check out their documentation.

Error Handling

StorageOperations never cause exceptions to be thrown, even if you use the await or yield keywords with them. Instead, it is expected that you will detect and handle errors manually.

You can determine if a completed StorageOperation has failed using the HasFailed property. If an operation has failed, you can acquire more information about the failure via the StorageError object found in the Error property.

async void Start()
{
    var operation = await CloudStorage.LoadObjectAsync<string[]>(objectId);
    if(operation.HasFailed)
    {
        Debug.LogWarning(operation.Error);
        return;
    }
    
    foreach(string item in operation.Result)
    {
        Debug.Log($"Loaded item: \"{item}\".");
    }
}

Serialization

When an object is saved to cloud storage, its state is serialized to JSON using Json.NET.

By default all the public properties and fields of objects are serialized.

You can use Json.NET's serialization attributes to control how Json.NET serializes and deserializes your object.

Supported Types

In addition to supporting all the types that Json.NET can handle by default (primitive types, arrays, lists, dictionaries...), Cloud Storage also supports the following Unity types:

• Vector2

• Vector3

• Quaternion

• Color

• Color32

Saving and loading objects whose type derives from UnityEngine.Object is not supported. You can however serialize a UnityEngine.Object into a string using the built-in JsonUtility, and then save that string in cloud storage instead.

Throttling

coherence Cloud has a rate limit of one API request of a particular type per second.

Having a rate limit of one API request of a type per second means is that if, for example, a save operation is made while another save operation is already in progress, then the second save operation will be queued, and will only get sent to the backend after one second has passed since the previous save operation.

However, the Cloud Storage service is able to automatically batch multiple storage operations into a single API request behind-the-scenes, which means that in practice an operation should almost never have to sit in queue for more than a second.

Other Considerations

Currently, data is held for one hour. In the future, this will be configurable.

Any client can read or write storage objects at any time. Data is available as long as the client knows the identifier to access it.