跳到主要内容

游戏 Config Data

1. 概述​

游戏 Config Data 是一组适用于整个游戏的 key-value 键值对。它通常用于存储适用于整个游戏的配置数据，例如游戏区服信息列表、游戏客户端版本控制数据等。游戏客户端和游戏服务器都可以读取这些数据,但只能通过控制台或 CLI 进行更新。 完成本教程后,您将了解以下内容:

  • 如何在控制台自定义游戏 Config Data
  • 如何在代码中查询游戏 Config Data

2. 自定义游戏 Config Data​

登录网页门户,进入控制台:

image-20240628193530646

点击顶部的"Global Data"链接，激活"Config Data"标签页：

image-20240628193135475

2.1 添加新数据项​

点击"添加"按钮来添加新数据项：

image-20240628194149432

字段说明：

  • Key：数据项名称，由字母、数字、下划线和空格组成，必须以字母开头，不能超过128个字符。

  • Is JSON：数据项值是否需要遵循JSON约束。如果开发者想在代码中将此项目值作为JsonValue访问，建议设置为true，这样在编辑值时会进行JSON约束检查。

  • Server Only：数据项是否只能由服务器访问。

  • True：游戏服务器可读，游戏客户端不可见。

  • False：游戏服务器和游戏客户端均可读。

  • Description：数据项描述信息，仅用于数据项，对PgosSDK不可见。

  • Value：数据项的值，最大字符长度为1048576（1*1024*1024）。

  • 通过PgosSDK查询获得的字符串值将会是：

  • 如果Is Json为false：与编辑框中的字符串相同。

  • 如果Is Json为true：编辑框中去除空白字符后的字符串（以节省传输带宽）。

数据项的值将以FKVDataValue结构的形式呈现，开发者可以使用以下函数：AsStr、AsInt32、AsInt64、AsFloat、AsDouble、AsJson来获取所需的数据格式。

点击"确定"按钮提交创建。每个游戏最多可以有1000个 Title Config Data 项。

2.2 编辑项目字段​

如果开发人员需要修改的数据项字段，请点击"操作"列中的"编辑"链接：

image-20240628194946397

弹出编辑面板：

image-20240628195030643

当Is Json设置为true时，Value编辑框将检查JSON约束。

2.3 删除现有数据项​

如果您不再需要某些数据项，可以选中它们并点击Remove按钮将其删除。

image-20240628195318051

3. 查询游戏 Config Data​

您可以通过 PgosSDK 在游戏中查询指定的游戏 Config Data 项。

3.1 游戏客户端​

APIDescription
GetTitleConfigKVData查询游戏 Config Data 中指定的 key-value 数据。
GetAllTitleConfigKVData查询游戏 Config Data 的所有的 key-value 数据。

GetTitleConfigKVData Client API​

接口原型:

/**
* Query the specified key-value data of the title config data.
* 
* @param QueryKeys Keys to query
*/
void GetTitleConfigKVData(
    const TArray<FString>& QueryKeys,
    TFunction<void(const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data)> Callback) const;

代码示例:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleConfigData = IPgosSDKCpp::Get().GetClientTitleConfigDataAPI();
 if (TitleConfigData)
 {
     TArray<FString> QueryKeys;
     QueryKeys.Add(TEXT("ClientMinimumSupportedVersionInfo"));
     TitleConfigData->GetTitleConfigKVData(QueryKeys, [](const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

GetAllTitleConfigKVData Client API​

接口原型:

/**
* Query all key-value data of the title config data.
*/
void GetAllTitleConfigKVData(TFunction<void(const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data)> Callback) const;

代码示例:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleConfigData = IPgosSDKCpp::Get().GetClientTitleConfigDataAPI();
 if (TitleConfigData)
 {
     
     TitleConfigData->GetAllTitleConfigKVData([](const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

3.2 For Game Server​

APIDescription
GetTitleConfigKVData查询游戏 Config Data 中指定的 key-value 数据。
GetAllTitleConfigKVDataQuery all key-value data of the title config data.

GetTitleConfigKVData Server API​

接口原型:

/**
* Query the specified key-value data of the title config data.
* 
* @param QueryKeys Keys to query
*/
void GetTitleConfigKVData(
    const TArray<FString>& QueryKeys,
    TFunction<void(const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data)> Callback) const;

代码示例:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleConfigData = IPgosSDKCpp::Get().GetServerTitleConfigDataAPI();
 if (TitleConfigData)
 {
     TArray<FString> QueryKeys;
     QueryKeys.Add(TEXT("Key_ServerOnly_1"));
     TitleConfigData->GetTitleConfigKVData(QueryKeys, [](const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

GetAllTitleConfigKVData Server API​

接口原型:

/**
* Query all key-value data of the title config data.
*/
void GetAllTitleConfigKVData(TFunction<void(const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data)> Callback) const;

代码示例:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleConfigData = IPgosSDKCpp::Get().GetServerTitleConfigDataAPI();
 if (TitleConfigData)
 {
     
     TitleConfigData->GetAllTitleConfigKVData([](const FPgosResult& Ret, const FTitleConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

3.3 关键错误处理​

Error CodeRelevant APIHandling Suggestion
kBackendServerValidateFailGetTitleConfigKVData Client API
GetAllTitleConfigKVData Client API
GetTitleConfigKVData Server API
GetAllTitleConfigKVData Server API		输入参数无效,请查看错误信息了解详情。
kBackendAllFailedGetTitleConfigKVData Client API
GetAllTitleConfigKVData Client API
GetTitleConfigKVData Server API
GetAllTitleConfigKVData Server API		所有待查询的数据均失败，请检查'fails'字段以获取失败原因。
kSdkNetworkErrorAll Network API网络错误,请查看错误信息了解详情。