An example of how to use Unity Cloud Save Indexes and Queries

How to use Cloud Save Queries and Indexes for matching players.md

How to use Cloud Save Queries for matching players

An example of how to do you can player matching with Unity Cloud Save using Indexes and Queries

This is supported in Cloud Save SDK for Unity and the C# and JavaScript SDK for Unity Cloud Code.

1. Create Indexes for the keys you want to query on

Before saving data, first define an Index for the keys you want to query on (e.g. in the Unity Cloud Dashboard or using the Unity CLI) so that you can query on these keys in the next step.

This example assumes there is an index on the key "location" in the Public Access Class for Player Data.

2. Save Player Data to the Public Access Class

Write to the data you want to use for matching (e.g. region, language, level, etc) to Player Data in the Public Access Class (public data is directly readable by other players, but only the player the data belongs to can write to it).

using Unity.Services.CloudSave;
using Unity.Services.CloudSave.Models;
using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;

var data = new Dictionary<string, object> { { "location", "Paris" } };
await CloudSaveService.Instance.Data.Player.SaveAsync(data, new SaveOptions(new PublicWriteAccessClassOptions()));

3. Query for data from your game

You can now find other players using a query in your game.

using Unity.Services.CloudSave;
using Unity.Services.CloudSave.Models;

var query = new Query(
  new List<FieldFilter> {
    new FieldFilter("location", "Paris", FieldFilter.OpOptions.EQ, true)
  },
  { "location", "name", "avatar" } // List of keys in the Public Access Class to return along with results
);
var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query);

Debug.Log($"Number of players returned {results.Count}");
results.ForEach(r => {
  Debug.Log($"Player ID: {r.Id}");
  r.Data.ForEach(d => Log($"Key: {d.Key}, Value: {d.Value.GetAsString()}"));
});

---

Additional information

Server authoritative game logic

If you want players to be able to query data belonging to other players that is not Public then you can use Cloud Code (or a game server). Cloud Code Modules (C#) and Cloud Code Scripts (JavaScript) can query and return data for any player, in any Access Class.

If you want full server authoritative logic for the game client matching you could instead save data to the Protected Access Class (which game clients cannot write to directly), but there are tradeoffs and the appropriate level of complexity is going to vary depending on the use case.

Documentation

An example of how to query Player Data from Unity: https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/tutorials/unity-sdk#Query_Player_Data

An example of how to query Game Data from Unity (this is data stored in Custom Items, they do not have to be associated with a player): https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/tutorials/unity-sdk#Query_Custom_Items