Skip to content

Smart Objects

Smart Objects help you create and work with player's progress. It's built on the top of the Storage, but has a lot of automations. For example it generates the code required to work with the profile, it automatically tracks the changes and saves them in the cloud. If there is no internet connection, profile will be saved locally, and synchronized with the cloud was the connection is restored.

Storage

Allows you to Save and Load any data on Balancy servers. Ensure to authorize the player (at least as a guest) before using the Storage because all records are connected to specific players.

General Information

Collections and Keys

Each player can have a set of Collections, and each collection can have a set of Keys. When you save to the Storage, you must specify a Collection and a key. However, to Load the data, there are two options:

  1. Load a specific key from a specific collection
  2. Load the whole collection.

You can think of a Collection as a Book, where a Key is a book chapter. You can have as many books as you want with many different chapters in each one. It's up to you what you want to write in each chapter.

Both Collection and Key are string values. Ensure you are loading from the Collection/Key pair you used to save your data.

For example

You might have a collection 'Player' with many keys: 'Inventory', 'Spells', 'Stats', etc... When one of the data changes, you need to update only a small portion, which will be stored in one key. But when you start a game, you can load the whole profile with all the keys

Versions

Another worth mentioning topic is versions. Balancy handles them automatically, but it would be better for you to understand how it works. Each record in the database has a version number, which increases every time you change the data. It's used to prevent using outdated data.

For example

You launch a game on the Device1, play for some time, and the last version of your progress will be 5. Then you switch to the Device2, which loads progress with version 5, and saves several changes, making the last version of the progress 10. Finally, you reopen the game on the Device1, where the client still has version 5. The next time it tries to save an update, it'll get an error of the wrong version.

There are two ways to solve such an issue:

  1. Ignore the version (we have such a parameter in the Save method). I would not recommend this option. In most cases this is wrong.
  2. If you get such an error, reload your game progress to get the latest game data and version, apply it to your game, and keep playing.

Data types

We support 2 options:

  1. Simple string
  2. Any Class.

We are using Newtonsoft converter to Serialize and Deserialize objects. Here is an example of the class we can use to Save/Load in the Storage :

private class SaveExample
{
    public int IntValue;
    public string StringValue;

    [JsonIgnore]
    public int IgnoredValue;

    [JsonIgnore]
    public int AlsoIgnoredValue { get { return IntValue; } }
}

In the example above IntValue and StringValue will be saved and loaded, while the other 2 fields won't. So if you don't want any property or attribute to be synchronized, mark it with [JsonIgnore].

Save

Example of saving a string:

Balancy.Storage.Save("MyCollection1", "StringKey", "Hello World!", saveResponse =>
{
    Debug.Log("String was saved result: " + saveResponse.Success);
});

Example of saving an object:

var saveExample = new SaveExample
{
    IntValue = 5,
    StringValue = "Hello World",
    IgnoredValue = 3
};

Balancy.Storage.Save("MyCollection2", "ObjectKey", saveExample, saveResponse =>
{
    Debug.Log("Object was saved result: " + saveResponse.Success);
});

Load

Example of loading a saved string:

Balancy.Storage.Load<string>("MyCollection1", "StringKey", loadResponse =>
{
    Debug.Log("String was loaded result: " + loadResponse.Success);
    if (loadResponse.Success)
        Debug.Log("Value = " + loadResponse.Data.Value);
});

Example of loading a saved object:

Balancy.Storage.Load<SaveExample>("MyCollection2", "ObjectKey", loadResponse =>
{
    Debug.Log("Object was loaded result: " + loadResponse.Success);
    if (loadResponse.Success)
    {
        SaveExample saveExample = loadResponse.Data.Value;
        Debug.Log("String Value = " + saveExample.StringValue);
    }
});

Limits

  1. You can Save/Load the same combination of Collection & Key at most once per 20 seconds.
  2. The maximum size of a saved value is 100Kb.

It's subject to change in the future.