How to use Cloud Save to find and match players

This guide describes how you can use Unity Cloud Save to find players by name (or any other property).

This functionality is supported in Cloud Save SDK for Unity and the C# and JavaScript SDKs 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.

This example assumes there are indexes on the keys "name" and "level" 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. the keys "name" and "level") 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 System.Collections.Generic;
using Unity.Services.CloudSave;
using Unity.Services.CloudSave.Models;
using Unity.Services.CloudSave.Models.Data.Player;
using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;

var playerName = "Alex";
var playerLevel = "5";
var data = new Dictionary<string, object> { { "name", playerName }, { "level", playerLevel } };
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 System.Collections.Generic;
using Unity.Services.CloudSave;
using Unity.Services.CloudSave.Models;
using Unity.Services.CloudSave.Models.Data.Player;
using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;

// Query to find all players named Alex AND who are level 5 or above
var playerName = "Alex";
var playerLevel = "5";
var query = new Query(
  new List<FieldFilter> {
    new FieldFilter("name", playerName, FieldFilter.OpOptions.EQ, true),
    new FieldFilter("level", playerLevel, FieldFilter.OpOptions.GE, true)
  },
  new HashSet<string> {
   "name", "level", "location", "avatar" // List of any keys in the Public Access Class to return along with results
  }
);
var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query, new QueryOptions());

Debug.Log($"Number of players returned {results.Count}");
results.ForEach(r => {
  Debug.Log($"Player ID: {r.Id}");
  r.Data.ForEach(d => Debug.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 in the Public Access Class 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.

For example, in a real game you might want to store a players level in the Protected Access Class - which a player can read from, but only Cloud Code (or a game server) can write to. Alternatively, you could use Access Controls to disable clients from writing to data in the Public Access Class. Both approaches are good ways to implement server authortative game logic.

Enforcing Uniqueness

Cloud Save does not support enforcing uniqueness on values, if that is something you need you would need to write code to implement that logic.

Alternative approaches

This is only intended an example of how you can use Unity Cloud Save, and may not be the best approach for all use cases.

The Unity Authentication service natively supports the concepts of Player Names, you should consider if that is appropriate to use for your use case.

Documentation

About Cloud Save Queries https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/queries
About Player Data Access Classes https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/player-data#Access_Classes
How to query Player Data https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/tutorials/unity-sdk#Query_Player_Data

iaincollins/Unity Cloud Save - How to find and match players.md