DS 集成 PgosSDK

您的游戏服务器部署后，需要与 PGOS 服务进行通信。每个游戏服务器进程都必须响应 PGOS 服务触发的事件，并且必须让 PGOS 了解服务器进程的状态和玩家连接情况。

了解如何将 PGOS SDK 设置为 Unreal Engine 项目：初始设置。

了解如何将 PGOS SDK 设置为 Unity 项目：初始设置。

1. 初始化服务器进程

此过程为必需步骤。

所有 API 和数据类型均在 PgosServerAPI.h 文件中。

添加代码以与 PGOS 服务建立通信，并报告服务器进程已准备好承载战斗会话。此代码必须在任何依赖 PGOS 的代码（例如玩家数据查询）之前运行。

#include "PgosSDKCpp.h"
#include "Core/PgosServerAPI.h"
#include "Core/PgosServerHostingAPI.h"

// Example codes in PGOS's sample 'Pingpong Shooter'
void APGOSBattleGameMode::PreparePgosSDK()
{
    // fill config options of pgos
    TMap<FString, FString> Config;
    Config.Add(TEXT("title_id"), TEXT("xxx"));
    Config.Add(TEXT("secret_key"), TEXT("yyy"));
    Config.Add(TEXT("log_level"), TEXT("0"));
    IPgosSDKCpp::Get().GetServerAPI()->InitConfig(Config);

    // fill port
    int32 Port = GetWorld()->NetDriver->LocalAddr->GetPort();

    // fill log paths
    TArray<FString> LogPathes;
    FString ServerLogFilePath = IFileManager::Get().ConvertToAbsolutePathForExternalAppForRead(*FGenericPlatformOutputDevices::GetAbsoluteLogFilename());
    FString PgosSavedPath = FPaths::ConvertRelativePathToFull(FPaths::ProjectSavedDir());
    FString PgosLogPath = FPaths::Combine(PgosSavedPath, FString("pgos"));
    FString Binpath = FPaths::ConvertRelativePathToFull(
        FPaths::Combine(FPaths::ProjectDir(), FString("Binaries")));

    LogPathes.Add(PgosLogPath);
    LogPathes.Add(ServerLogFilePath);

    // bind callbacks
    auto HostingAPI = IPgosSDKCpp::Get().GetServerHostingAPI();
    HostingAPI->OnHealthCheck().AddUObject(this, &APGOSBattleGameMode::OnHealthCheck);
    HostingAPI->OnStartBattleSession().AddUObject(this, &APGOSBattleGameMode::OnStartBattleSession);
    HostingAPI->OnProcessTerminate().AddUObject(this, &APGOSBattleGameMode::OnProcessTerminate);
    HostingAPI->OnTerminateBattleSession().AddUObject(this, &APGOSBattleGameMode::OnTerminateBattleSession);
    HostingAPI->OnBattlePlayerOffline().AddUObject(this, &APGOSBattleGameMode::OnBattlePlayerOffline);
    HostingAPI->OnBattlePlayerBanned().AddUObject(this, &APGOSBattleGameMode::OnBattlePlayerBanned);

    // Notify PGOS that a server process is ready to host a battle session
    FPgosResult Result = HostingAPI->ProcessReady(Port, LogPathes);
}

1. 调用 InitConfig 初始化 PGOS DS SDK。

2. 调用 ProcessReady 并传入以下信息，通知 PGOS 服务器进程已准备好发起战斗会话。

• 端口号 是服务器进程使用的。该端口号和 IP 地址将提供给游戏客户端，以便它们连接到服务器进程并加入战斗会话。

• log_paths 您希望 PGOS 保留的日志文件。这些文件由服务器进程在战斗会话期间生成。它们临时存储在运行服务器进程的 CVM 实例上，并在 CVM 实例关闭后丢失。此处列出的所有路径都将在战斗会话结束后上传到 PGOS 后端。您可以在 PGOS 的门户网站上访问它们。点击此处了解更多详情。注意：请勿将配置文件和其他资源文件放入 log_paths 中，因为 log_paths 中的文件可能会被清理。

• PGOS 服务可在服务器进程上调用的回调函数名称。您的游戏服务器需要实现这些函数。本文档的其余部分将介绍如何实现这些函数。

• OnHealthCheck（必需）会定期调用，以从服务器进程请求健康状态报告。

• 当 PGOS 服务收到在游戏服务器进程中启动新战斗会话的请求时，会调用 OnStartBattleSession（必需）。

• 当 PGOS 服务需要强制终止服务器进程时，会调用 OnProcessTerminate（必需），以便服务器进程正常关闭。

• 当战斗会话中的玩家离线时，会调用 OnBattlePlayerOffline（可选）。

• 当战斗会话中的玩家被禁言时，会调用 OnBattlePlayerBanned（可选）。

2. 报告服务器进程健康状况

此过程为必需步骤

// Example codes in PGOS's sample 'Pingpong Shooter'
bool APGOSBattleGameMode::OnHealthCheck()
{
    return true;
}

添加代码以实现回调函数“onHealthCheck”。此函数由 PGOS 服务调用，用于定期从服务器进程收集健康指标。服务器进程对健康检查的响应是一个布尔值：健康或不健康。

PGOS 使用服务器进程健康状况来有效地结束不健康的进程并释放资源。在以下情况下，PGOS 后端可能会关闭该进程并启动一个新进程：

• 游戏服务器进程连续三次健康检查都报告不健康。
• 游戏服务器进程连续三次健康检查均未响应。

3. 激活战斗会话

此过程为必需步骤。

添加代码以实现回调函数 OnStartBattleSession。PGOS 服务调用此函数以在服务器进程中触发新的战斗会话。

OnStartBattleSession 函数以 FServerBattleSession 对象作为输入参数。该对象包含关键的战斗信息，例如战斗会话 ID、以键值对形式呈现的战斗属性格式、队伍结构以及战斗成员信息。

该函数实现应完成以下任务：

• 准备基于 FServerBattleSession 对象启动新的战斗会话。

• 当新的战斗会话准备好接受玩家时，调用 ActivateBattleSession。调用成功后，PGOS 服务会将战斗会话状态更改为 ACTIVE。

4. 验证新玩家

此步骤可选。

// Example codes in PGOS's sample 'Pingpong Shooter'
void APGOSBattleGameMode::PreLogin(
    const FString& Options,
    const FString& Address,
    const FUniqueNetIdRepl& UniqueId,
    FString& ErrorMessage)
{
    ...
#if UE_SERVER
    FPgosResult Result = IPgosSDKCpp::Get().GetServerHostingAPI()->AcceptPlayerBattleSession(
        CurrentBattleSession.battle_session_id,
        PlayerBattleSessionID);
#else
    ...
}

添加代码以验证与 PGOS 服务的玩家连接请求。此代码应在新玩家尝试连接到服务器进程时运行，直至接受玩家连接。玩家验证使 PGOS 能够跟踪战斗会话中的当前玩家和可用位置。

来自游戏客户端的连接请求应包含玩家战斗会话 ID。此 ID 由 PGOS 服务在游戏客户端请求加入战斗会话（例如，“开始匹配”请求）时生成。该 ID 用于在战斗会话中预留玩家位置。收到游戏客户端连接请求后，服务器进程会使用玩家战斗会话 ID 调用 AcceptPlayerBattleSession。然后，PGOS 会验证战斗会话中是否预留了玩家战斗会话 ID。一旦 AcceptPlayerBattleSession 返回 True，玩家战斗会话的状态将变为 Active。

一旦 PGOS 验证了玩家战斗会话 ID，服务器进程即可接受连接。如果玩家战斗会话 ID 未经 PGOS 服务验证，则服务器进程应拒绝连接。

5. 举报玩家战斗会话断开连接

此步骤可选。

// Example codes in PGOS's sample 'Pingpong Shooter'
void APGOSBattleGameMode::Logout(AController* Exiting)
{
#if UE_SERVER
    FPgosResult Result = IPgosSDKCpp::Get().GetServerHostingAPI()->DisconnectPlayerBattleSession(
        CurrentBattleSession.battle_session_id,
        Player->PlayerBattleSessionID);
#endif
}

当玩家与游戏 DS 断开连接时，调用 DisconnectPlayerBattleSession 通知 PGOS 服务。调用此接口后，玩家战斗会话状态将变为 Disconnected ，在状态变为 Completed 之前，仍可通过再次调用 AcceptPlayerBattleSession 恢复到 Active 状态。

6. 玩家战斗会话结束上报

此步骤可选。

// Example codes in PGOS's sample 'Pingpong Shooter'
void APGOSBattleGameMode::Logout(AController* Exiting)
{
#if UE_SERVER
    FPgosResult Result = IPgosSDKCpp::Get().GetServerHostingAPI()->RemovePlayerBattleSession(
        CurrentBattleSession.battle_session_id,
        Player->PlayerBattleSessionID);
#endif
}

当玩家退出战斗会话时，调用 RemovePlayerBattleSession 通知 PGOS 服务。调用此接口后，玩家战斗会话状态将变为 Completed，且该玩家战斗会话将不再被 PGOS 接受。

7. 结束战斗会话

此过程为必需步骤

战斗会话结束后，游戏服务器应关闭，以便回收和刷新托管资源。我们不支持在 DS 的生命周期内托管多个游戏。以下是游戏服务器进程退出流程的示例：

1. 战斗会话结束。
2. 执行自定义退出准备。
3. 调用 ProcessEnding 通知 PGOS 服务游戏服务器进程正在关闭。
4. 退出游戏服务器。

备注：接口 TerminateBattleSession 在 v 0.9.0 版本中已弃用。

8. 响应服务器进程关闭通知

此过程为必需步骤

当游戏服务器进程持续被报告为不健康，或运行游戏服务器进程的实例即将终止时，回调函数 OnProcessTerminate 会被调用。

9. 测试集成

为了方便在非生产环境中快速在 DS 上部署游戏，PGOS 提供了本地 DS 机制。这使您可以在本地（非云）DS 上部署游戏，而无需在 DS 或游戏客户端上添加任何额外代码。此类 DS 作为可用 DS 包含在 PGOS 工作系统中，并分配给游戏客户端。这在将 PGOS 与您的游戏服务器集成时非常有用。点击此处了解更多详情