Search Unity

Official Cloud Save SDK 3.1 - Queries and Access Classes

Discussion in 'Cloud Save' started by IainUnity3D, Feb 15, 2024.

  1. IainUnity3D


    Unity Technologies

    Oct 5, 2022
    Last month we released version 3.1 of the Unity Cloud Save SDK which added support for running Queries directly from a game client and for reading and writing to data in different Access Classes.

    We just expanded the Unity SDK tutorial for Cloud Save to add examples of how to use Queries and Access Classes with both Player Data and Game Data (using Custom Items).

    Queries and Indexes

    Cloud Save Queries allows you to define indexes on Player Data and Game Data stored in Cloud Save so you can search / query data using Cloud Code. You must create an index before you save data that can be queried.

    You can create and manage indexes in the Unity Cloud Dashboard.

    Player Data: Access Classes

    There are 3 different Access Classes for Cloud Save Player Data:
    • Default: Readable and writable by the player the data corresponds to
    • Public: Readable by any player, writable by the player the data corresponds to
    • Protected: Readable by the player the data corresponds to, only writeable from a server
    Game Data: Access Classes

    Cloud Save supports 2 different Access Class levels for Custom Items - these can be for Game Data that does not have to be bound to a player:
    • Default: Readable by any player, writeable only from a server
    • Private: Readable and writeable only from a server

    If you want to create a system to allow players to find other players - for example for async matchmaking - you could first create an index for the names of the properties you want to be able to match on (e.g. language, location, etc).

    Player 1:

    In your game, you could then write data needed for matching to the Public Access Class for the Player, where it can be read (and queried) by other players. In this case, language and a location.

    Code (CSharp):
    1. using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
    3. var data = new Dictionary<string, object> { { "language", "FR" }, { "location", "Paris" } };
    4. await CloudSaveService.Instance.Data.Player.SaveAsync(data, new SaveOptions(new PublicWriteAccessClassOptions()));
    Player 2:

    You can then query from another client to get back a list of Player IDs for players that match a query:

    Code (CSharp):
    1. var query = new Query(
    2.   new List<FieldFilter> {
    3.     new FieldFilter("language", "FR", FieldFilter.OpOptions.EQ, true),
    4.     new FieldFilter("location", "Paris", FieldFilter.OpOptions.EQ, true)
    5.   },
    6.   { "location", "name", "avatar" } // List of Public data keys to return along with results
    7. );
    8. var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query);
    10. Debug.Log($"Number of players returned {results.Count}");
    11. results.ForEach(r => {
    12.   Debug.Log($"Player ID: {r.Id}");
    13.   r.Data.ForEach(d => Log($"Key: {d.Key}, Value: {d.Value.GetAsString()}"));
    14. });
    You can also use Custom Items to Query Game Data in the same way, or use Unity Cloud Code (or a game server) to query across data in any Access Class, and for any Player or Custom Item.

    You can use client side methods to quickly and easily to unlock new functionality without adding any server side logic and you can combine the functionality in Cloud Save with Cloud Code to create full featured systems for guilds, quests, community goals, NPCs, auction houses, inventory management, item trading, mailboxes, loot tables, etc
    AntonioModer likes this.
  2. tranpd


    Aug 12, 2016
    Hi lainUnity3D,
    I'm currently facing a challenge as my game has almost reached the limit of 20 Indexes in Unity Cloud Save. I'm exploring ways to optimize the usage of Indexes, but I'm wondering if there's a possibility to increase the maximum number of Indexes beyond 20. Is there any guidance or solution available for managing a higher number of Indexes efficiently?
  3. IainUnity3D


    Unity Technologies

    Oct 5, 2022
    Hi @tranpd,

    Apologies for the delay in following up.

    I don't have much of an answer to this yet but we appreciate the feedback and that the currently limit might be overly restrictive for some use cases - particularly games with complex behaviours - and are reviewing what we can do to provide guidance and on our end to either increase the limit or provide ways to work with it that make running into it less likely.

    Having generic names for indexes (e.g. 'Type', 'ID', 'Name') and then using them across multiple objects of a different type can help reduce the number of indexes required when working with Game Data (Custom Items).

    If you would like to share any details about the sorts of things you are modelling (Game Data, Player Data, etc) I'd be happy to take a look to either make suggestions or to inform our own thinking about how we can better support the sorts of things you would like to be able to do.

    Best regards,

    tranpd likes this.