Unity SDK 教程

Use the Cloud Save Software Development Kit to save and load player data, game data, and files in your Unity project.

阅读时间6 分钟

最后更新于 12 天前

此教程演示了如何在 Unity 中使用 Cloud Save SDK 保存和加载数据。

注意

注意：从 Cloud Save SDK 版本 3 开始提供这些功能。

在 Unity 中使用 Cloud Save

您可以在 Unity 中从 C# 脚本调用 Cloud Save SDK。

在 Unity 中创建 C# MonoBehaviour 脚本。
添加代码以将数据保存到 Cloud Save 或从中加载数据（请参阅下面的示例）。
将新制作的脚本附加到游戏对象。
选择 Play（播放） 以运行项目，体验 Cloud Save 的运行效果。

要了解有关 Unity 中脚本编写的详细信息，请参阅创建和使用脚本。

SDK 示例

SDK 附带的

CloudSaveSample

脚本对此教程中的示例进行了扩展。您可以在 Unity 中选择 Package Manager（包管理器） > Cloud Save > Samples（示例） 来查看示例。

包含身份验证的示例

以下示例演示了如何使用 Authentication 包以匿名身份验证方式登录玩家帐户，初始化 Cloud Save，并提供使用 Cloud Save 保存和加载数据的方法。


using UnityEngine;using Unity.Services.Core;using Unity.Services.Authentication;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;using System.Collections.Generic;public class CloudSaveSample : MonoBehaviour{    private async void Awake()    {        await UnityServices.InitializeAsync();        await AuthenticationService.Instance.SignInAnonymouslyAsync();    }    public async void SaveData()    {        var playerData = new Dictionary<string, object>{          {"firstKeyName", "a text value"},          {"secondKeyName", 123}        };        await CloudSaveService.Instance.Data.Player.SaveAsync(playerData);        Debug.Log($"Saved data {string.Join(',', playerData)}");    }    public async void LoadData()    {        var playerData = await CloudSaveService.Instance.Data.Player.LoadAsync(new HashSet<string> {          "firstKeyName", "secondKeyName"        });        if (playerData.TryGetValue("firstKeyName", out var firstKey)) {            Debug.Log($"firstKeyName value: {firstKey.Value.GetAs<string>()}");        }        if (playerData.TryGetValue("secondKeyName", out var secondKey)) {            Debug.Log($"secondKey value: {secondKey.Value.GetAs<int>()}");        }    }}

玩家数据

您可以在 Unity Cloud 后台中查看、编辑和删除玩家的数据。

保存项

使用

SaveAsync

方法保存一个或多个项。


public async void SaveData(){    var data = new Dictionary<string, object>{{"keyName", "value"}};    await CloudSaveService.Instance.Data.Player.SaveAsync(data);}

如果您希望其他玩家能够读取数据，您可以将该数据保存在公开访问类中。


public async void SavePublicData(){    var data = new Dictionary<string, object>{{"keyName", "value"}};    await CloudSaveService.Instance.Data.Player.SaveAsync(data, new SaveOptions(new PublicWriteAccessClassOptions()));}

获取数据

使用

LoadAsync

方法获取作为玩家数据存储的键和值。


public async void LoadData(){    var playerData = await CloudSaveService.Instance.Data.Player.LoadAsync(new HashSet<string>{"keyName"});    if (playerData.TryGetValue("keyName", out var keyName)) {        Debug.Log($"keyName: {keyName.Value.GetAs<string>()}");    }}

您可以获取公开和受保护访问类中的数据的键和值。


public async void LoadPublicData(){  var playerData = await CloudSaveService.Instance.Data.Player.LoadAsync(new HashSet<string>{"keyName"}, new LoadOptions(new PublicReadAccessClassOptions()));  if (playerData.TryGetValue("keyName", out var keyName)) {      Debug.Log($"keyName: {keyName.Value.GetAs<string>()}");  }}


public async void LoadProtectedData(){  var playerData = await CloudSaveService.Instance.Data.Player.LoadAsync(new HashSet<string>{"keyName"}, new LoadOptions(new ProtectedReadAccessClassOptions()));  if (playerData.TryGetValue("keyName", out var keyName)) {      Debug.Log($"keyName: {keyName.Value.GetAs<string>()}");  }}

您可以通过传递玩家 ID 来读取（但不能写入）另一个玩家的公开访问类中的数据。


public async void LoadPublicDataByPlayerId(){  var playerId = "JE1unrWOOzzbIwy3Nl60fRefuiVE";  var playerData = await CloudSaveService.Instance.Data.Player.LoadAsync(new HashSet<string>{"keyName"}, new LoadOptions(new PublicReadAccessClassOptions(playerId)));  if (playerData.TryGetValue("keyName", out var keyName)) {      Debug.Log($"keyName: {keyName.Value.GetAs<string>()}");  }}

删除项

使用

DeleteAsync

方法删除项。


public async void DeleteData(){    await CloudSaveService.Instance.Data.Player.DeleteAsync("key");}

获取键列表

使用

ListAllKeysAsync

方法获取键列表。还可以获取元数据，例如上次修改键的时间。


public async void ListKeys(){    var keys = await CloudSaveService.Instance.Data.Player.ListAllKeysAsync();    for (int i = 0; i < keys.Count; i++)    {        Debug.Log(keys[i].Key);    }}

还可以列出公开和受保护访问类中的数据的键。


public async void ListKeys(){    var keys = await CloudSaveService.Instance.Data.Player.ListAllKeysAsync(      new ListAllKeysOptions(new PublicReadAccessClassOptions())    );    for (int i = 0; i < keys.Count; i++)    {        Debug.Log(keys[i].Key);    }}


public async void ListKeys(){    var keys = await CloudSaveService.Instance.Data.Player.ListAllKeysAsync(      new ListAllKeysOptions(new ProtectedReadAccessClassOptions())    );    for (int i = 0; i < keys.Count; i++)    {        Debug.Log(keys[i].Key);    }}

查询玩家数据

查询玩家数据公开访问类中任何索引键的值。

注意

查询不会返回在创建索引之前保存的数据（或这些数据太大而无法创建索引）。


public async void QueryPlayerData(){  var query = new Query(    // The first argument to Query is a list of one or more filters, all must evaluate to true for a result to be included    new List<FieldFilter>    {        new FieldFilter("indexedKeyName", "value", FieldFilter.OpOptions.EQ, true),        new FieldFilter("anotherIndexedKeyName", "otherValue", FieldFilter.OpOptions.NE, true)    },    // The second (optional) argument is a list of keys you want to be included with their values in the response    // This may include keys which are not part of the index, and does not need to include the index keys    // If you don't specify any, you will still get back a list of IDs for Players that matched the query    new HashSet<string>    {        "indexedKeyName"    }  );  var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query, new QueryOptions());  Debug.Log($"Number of results from query: {results.Count}");  results.ForEach(r =>  {      Debug.Log($"Player ID: {r.Id}");      r.Data.ForEach(d => Debug.Log($"Key: {d.Key}, Value: {d.Value.GetAsString()}"));  });}

游戏数据

您可以使用自定义项保存和加载非玩家特定的游戏数据。

注意

游戏客户端只能读取自定义项。客户端不能创建、修改或删除自定义项。可以使用 Cloud Code、游戏服务器、HTTP API 或 Unity Cloud 后台写入自定义项。

获取数据

使用

LoadAllAsync

获取自定义项的所有数据。


public async void LoadCustomItemData(){  var customItemId = 'my-custom-item';  var customItemData = await CloudSaveService.Instance.Data.Custom.LoadAllAsync(customId);  foreach (var customItem in customItemData)  {      Debug.Log($"Key: {customItem.Key}, Value: {customItem.Value.Value}");  }}

查询自定义项

查询自定义项默认访问类中任何索引键的值。

注意

查询不会返回在创建索引之前保存的数据（或这些数据太大而无法创建索引）。


public async void QueryCustomItems(){  var query = new Query(    // The first argument to Query is a list of one or more filters, all must evaluate to true for a result to be included    new List<FieldFilter>    {        new FieldFilter("indexedKeyName", "value", FieldFilter.OpOptions.EQ, true),        new FieldFilter("anotherIndexedKeyName", "otherValue", FieldFilter.OpOptions.NE, true)    },    // The second (optional) argument is a list of keys you want to be included with their values in the response    // This may include keys which are not part of the index, and does not need to include the index keys    // If you don't specify any, you will still get back a list of IDs for Players that matched the query    new HashSet<string>    {        "indexedKeyName"    }  );  var results = await CloudSaveService.Instance.Data.Custom.QueryAsync(query);  Debug.Log($"Number of results from query: {results.Count}");  results.ForEach(r =>  {      Debug.Log($"Custom Item ID: {r.Id}");      r.Data.ForEach(d => Debug.Log($"Key: {d.Key}, Value: {d.Value.GetAsString()}"));  });}

玩家文件

Cloud Save Files 提供了一种以任何格式存储大型保存文件（最大 1 GB）以及跨设备/平台访问保存的游戏文件的方法。

保存玩家文件

读取设备上本地保存的文件，并使用

SaveAsync

方法保存到 Cloud Save。


public async void SavePlayerFile(){    byte[] file = System.IO.File.ReadAllBytes("fileName.txt");    await CloudSaveService.Instance.Files.Player.SaveAsync("fileName", file);}

删除玩家文件

使用

DeleteAsync

方法删除玩家文件。


public async void DeletePlayerFile(){    await CloudSaveService.Instance.Files.Player.DeleteAsync("fileName");}

列示玩家文件

使用

ListAllAsync

方法获取玩家的所有文件名称列表。


public async void ListPlayerFiles(){    List<FileItem> files = await CloudSaveService.Instance.Files.Player.ListAllAsync();    for (int i = 0; i < files.Count; i++)    {        Debug.Log(files[i]);    }}

以字节数组形式获取玩家文件

使用

LoadBytesAsync

方法以字节数组形式获取玩家文件。


public async void GetPlayerFileAsByteArray(){    byte[] file = await CloudSaveService.Instance.Files.Player.LoadBytesAsync("fileName");}

以流形式获取玩家文件

使用

LoadStreamAsync

方法以流形式获取玩家文件。


public async void GetPlayerFileAsStream(){    Stream file = await CloudSaveService.Instance.Files.Player.LoadStreamAsync("fileName");}

获取玩家文件元数据

使用

GetMetadataAsync

方法获取单个玩家文件的元数据（大小、最后修改和创建日期、键、内容类型和当前 WriteLock）。


public async void GetPlayerFileMetadata(){    var metadata = await CloudSaveService.Instance.Files.Player.GetMetadataAsync("fileName");    Debug.Log(metadata.Key);    Debug.Log(metadata.Size);    Debug.Log(metadata.ContentType);    Debug.Log(metadata.Created);    Debug.Log(metadata.LastModified);    Debug.Log(metadata.WriteLock);}

您可以使用 Unity Cloud 后台访问单个玩家的文件。在 Cloud Save 模块的玩家详细信息下可以找到这些文件。

错误处理

在错误处理逻辑的方法中使用 SDK 返回的错误代码或类型。避免使用错误消息，因为它们将来可能会发生变化。

文档

引擎

服务

增长

工业

支持

Cloud Save

Unity SDK tutorial

Cloud Save for Cloud Code

Cloud Save

Unity SDK 教程

在 Unity 中使用 Cloud Save

SDK 示例

包含身份验证的示例

玩家数据

保存项

获取数据

删除项

获取键列表

查询玩家数据

游戏数据

获取数据

查询自定义项

玩家文件

保存玩家文件

删除玩家文件

列示玩家文件

以字节数组形式获取玩家文件

以流形式获取玩家文件

获取玩家文件元数据

错误处理