使用示例:使用默认配置值初始化新注册的玩家
此使用示例演示了如何在新玩家首次注册时使用 Triggers 在 Cloud Save 中以默认生命值和耐力值初始化新玩家。此示例使用 Authentication 服务发出的 signedUp
事件,并将值记录在 Cloud Save 中。
先决条件
必须首先创建具有所需访问角色的服务帐户,并配置 UGS CLI。
使用服务帐户进行身份验证
在调用 Triggers 服务之前,必须使用服务帐户进行身份验证。
- 导航到 Unity Cloud Dashboard。
- 选择 Administration(管理)> Service Accounts(服务帐户)。
- 选择 **New(新建)**按钮并输入服务帐户的名称和描述。
- 选择 Create(创建)。
添加产品角色并创建密钥:
- 选择 Manage product roles(管理产品角色)。
- 将以下角色添加到服务帐户:
- 从 LiveOps 下拉选单中,选择 **Triggers Configuration Editor(Triggers 配置编辑者)**和 Triggers Configuration Viewer(Triggers 配置查看者)。
- 从 Admin(管理)下拉选单中,选择 Unity Environments Viewer(Unity 环境查看者)。
- 从 LiveOps 下拉选单中,选择 **Triggers Configuration Editor(Triggers 配置编辑者)**和 Triggers Configuration Viewer(Triggers 配置查看者)。
- 选择 Save(保存)。
- 选择 Add Key(添加密钥)。
- 使用 base64 编码方式对 **Key ID(密钥 ID)**和 **Secret key(密钥)**进行编码。格式为“key_id:secret_key”。请记下此值。
如需了解更多信息,请参阅身份验证。
配置 UGS CLI
按照以下步骤操作以开始使用 UGS CLI:
按如下方式配置 Project ID 和环境:
ugs config set project-id <your-project-id>
ugs config set environment-name <your-environment-name>
使用您先前创建的服务帐户进行身份验证。请参阅接受身份验证。
检查 signed-up
事件
在创建新玩家时,Authentication 服务发出 signed-up
事件。事件有效负载如下所示:
{
"playerId": "string",
"providerId": "string",
"createdAt": "string"
}
事件有效负载作为参数传递给 Cloud Code。
请参阅 Authentication:注册以了解更多信息。
设置 Cloud Code
定义一个模块终端或一个脚本,在其中调用 Cloud Save 来使用默认生命值和耐力值初始化经过身份新验证的新玩家。
Cloud Code C# 模块
创建一个包含必需字符串参数 playerId
的 InitializeNewPlayer
模块函数,内容如下:
C#
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Unity.Services.CloudCode.Core;
using Unity.Services.CloudCode.Apis;
using Unity.Services.CloudCode.Shared;
using Unity.Services.CloudSave.Model;
public class ModuleSample
{
private const string HealthKey = "HEALTH";
private const string StaminaKey = "STAMINA";
private const int DefaultValue = 100;
private readonly ILogger<ModuleSample> _logger;
public ModuleSample(ILogger<ModuleSample> logger)
{
_logger = logger;
}
[CloudCodeFunction("InitializeNewPlayer")]
public async Task InitializeNewPlayer(IExecutionContext ctx, IGameApiClient gameApiClient, string playerId)
{
try
{
var response = await gameApiClient.CloudSaveData.GetItemsAsync(ctx, ctx.ServiceToken, ctx.ProjectId, playerId, new List<string>() { HealthKey, StaminaKey });
if (response.Data.Results.Count == 0)
{
await gameApiClient.CloudSaveData.SetItemBatchAsync(ctx, ctx.ServiceToken, ctx.ProjectId, playerId,
new SetItemBatchBody(new List<SetItemBody>{new (HealthKey, DefaultValue), new (StaminaKey, DefaultValue)}));
_logger.LogInformation("The player has been initialized with the {HealthKey} and {StaminaKey} keys with values of {DefaultValue}", HealthKey, StaminaKey, DefaultValue);
}
} catch (ApiException e)
{
_logger.LogError("Failed to initialize player data in Cloud Save. Error: {Error}", e.Message);
throw new Exception($"Failed to initialize {playerId} data in Cloud Save. Error: {e.Message}");
}
}
public class ModuleConfig : ICloudCodeSetup
{
public void Setup(ICloudCodeConfig config)
{
config.Dependencies.AddSingleton(GameApiClient.Create());
}
}
}
部署该模块。
请参阅部署 Hello World 以了解如何部署模块。
**注意:**如果您使用 UGS CLI 来部署模块,请不要忘记添加额外的服务帐户角色 Cloud Code Editor
。
Cloud Code JavaScript 脚本
创建一个具有必要字符串参数 playerId
的 InitializeNewPlayer
脚本,内容如下:
JavaScript
const { DataApi } = require("@unity-services/cloud-save-1.4");
const CLOUD_SAVE_HEALTH_KEY = "HEALTH";
const CLOUD_SAVE_STAMINA_KEY = "STAMINA";
const DEFAULT_VALUE = 100;
module.exports = async ({ params, context, logger }) => {
const cloudSaveApi = new DataApi(context);
try {
// Check if player has been initialized yet
const cloudSaveGetResponse = await cloudSaveApi.getItems(context.projectId, params.playerId, [CLOUD_SAVE_HEALTH_KEY, CLOUD_SAVE_STAMINA_KEY]);
if (cloudSaveGetResponse.data.results.length === 0) {
// Record new values for player
await cloudSaveApi.setItemBatch(context.projectId, params.playerId, {
data: [
{
key: CLOUD_SAVE_HEALTH_KEY,
value: DEFAULT_VALUE,
},
{
key: CLOUD_SAVE_STAMINA_KEY,
value: DEFAULT_VALUE,
},
],
});
logger.info(`The player has been initialized with the ${CLOUD_SAVE_HEALTH_KEY} and ${CLOUD_SAVE_STAMINA_KEY} keys with values of ${DEFAULT_VALUE}`, { "affectedPlayerId": params.playerId });
return;
}
logger.info("The player has already been initialized.", { affectedPlayerId: params.playerId });
} catch (err) {
logger.error("Failed to update Cloud Save data", { "error.message": err.message }, { "affectedPlayerId": params.playerId });
throw err;
}
};
// Uncomment the code below to enable the inline parameter definition
// - Requires Cloud Code JS dev environment setup with NodeJS (https://docs.unity3d.com/Packages/com.unity.services.cloudcode@latest/index.html?subfolder=/manual/Authoring/javascript_project.html)
//
// module.exports.params = {
// playerId: { type: "String", required: true },
// };
**注意:**如果您使用 Unity 编辑器来管理您的脚本,您可以取消注释脚本尾部的代码,以便声明所需的 playerId
脚本内参数。要了解有关如何管理脚本内参数的更多信息,请参阅在 Unity 编辑器中修改脚本参数。发布该脚本。
请参阅部署 Hello World 以了解如何部署脚本。
**注意:**如果您使用 UGS CLI 来部署脚本,请不要忘记添加额外的服务帐户角色 Cloud Code Script Publisher
和 Cloud Code Editor
。
配置触发器
要将 Cloud Code 资源关联到 Authentication signed-up
事件,请创建触发器。触发器会在触发事件时(例如,每次新玩家注册时)执行 Cloud Code 脚本或模块。
运行 new-file
命令在本地创建触发器配置:
ugs triggers new-file triggers-config
如果您创建了 Cloud Code 脚本,请使用以下配置来更新 triggers-config.tr
文件:
{
"$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",
"Configs": [
{
"Name": "initialize-new-player",
"EventType": "com.unity.services.player-auth.signed-up.v1",
"ActionUrn": "urn:ugs:cloud-code:InitializeNewPlayer",
"ActionType": "cloud-code"
}
]
}
如果您创建了 Cloud Code 模块,请使用以下配置来更新 triggers-config.tr
文件:
{
"$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",
"Configs": [
{
"Name": "initialize-new-player",
"EventType": "com.unity.services.player-auth.signed-up.v1",
"ActionUrn": "urn:ugs:cloud-code:ModuleSample/InitializeNewPlayer",
"ActionType": "cloud-code"
}
]
}
使用 UGS CLI 工具部署此配置:
ugs deploy triggers-config.tr
您应该会看到类似于以下内容的响应:
Deployed:
triggers-config.tr
现在,您有了一个触发器会在玩家注册时执行 Cloud Code 脚本或模块。
**注意:**您可以定义多个触发器来针对同一事件执行不同的 Cloud Code 脚本或模块。您可以扩展此用例以添加更多触发器来初始化其他玩家数据。
验证结果
要验证结果,请使用 Authentication 服务注册新玩家。要执行此操作,可以调用任何通过玩家身份验证的 Unity 游戏服务。
例如,要触发玩家身份验证流程,您可以通过 Unity Cloud Dashboard 的 Cloud Code 脚本页面生成新的玩家 ID。
如果触发器配置为在发生 signed-up
事件时触发,则对于每个注册的新玩家,其值都会在 Cloud Save 中初始化。
- 导航到 Unity Cloud Dashboard。
- 选择 Products(产品)> Player Management(玩家管理)。
- 从列表中选择一名玩家。
- 导航到 Cloud Save > **Data(数据)**选项卡。
- 您应该可以找到默认值为
100
的HEALTH
和STAMINA
键。