DS Integrates PgosSDK

Your game server needs to communicate with the PGOS service once it is deployed. Each game server process must respond to the events triggered by the PGOS service and it must also keep PGOS informed about the server process statuses and player connections.

Learn how to set up PGOS SDK to an Unreal Engine project here: Intial Setup.

Learn how to set up PGOS SDK to an Unity project here: Intial Setup.

1. Initialize the Server Process

This task is required.

All API and data types are organized in PgosServerAPI.h.

Add code to establish communication with the PGOS service and report that the server process is ready to host a battle session. This code must run before any PGOS-dependent code, such as player data query.

#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. Initialize PGOS DS SDK by calling InitConfig.

2. Notify PGOS that a server process is ready to host a battle session by calling ProcessReady with the following information.

   • Port number is used by the server process. The port number and an IP address would be provided to game clients so that they can connect to the server process to join a battle session.
   • log_paths of log files that you want PGOS to retain. These files are generated by the server process during a battle session. They are stored temporarily on the CVM instance where the server process is running and is lost when the CVM instance shuts down. Any paths listed here will be uploaded to the PGOS backend after the battle session ends. You can access them on PGOS's portal. Click here for more details. Note: do not put configuration and other resource files in log_paths, the files in log_paths may be cleaned up.
   • Names of callback functions that can be invoked by the PGOS service on the server process. Your game server needs to implement these functions. Instructions for implementing these functions is covered in the remainder of this document.
     • OnHealthCheck (required) is called regularly to request a health status report from the server process.
     • OnStartBattleSession (required) is called when the PGOS service receives a request to start a new battle session in the game server process.
     • OnProcessTerminate (required) is called when the PGOS service needs to force the server process to terminate, allowing the server process to shut down gracefully.
     • OnBattlePlayerOffline (optional) is called when a player in the battle-session is offline.
     • OnBattlePlayerBanned (optional) is called when a player in the battle-session is banned.

2. Report Server Process Health

This task is required.

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

Add code to implement the callback function onHealthCheck. This function is invoked by the PGOS service to periodically collect health metrics from the server process. The server process's response to a health check is a boolean value: healthy or unhealthy.

Server process health is used by PGOS to efficiently end unhealthy processes and release resources. In the following cases, the PGOS backend may shut down the process and start a new one:

• A game server process continues to report unhealthy for three consecutive health checks.
• A game server process does not respond for three consecutive health checks.

3. Activate a Battle Session

This task is required.

Add code to implement the callback function OnStartBattleSession. The PGOS service invokes this function in order to trigger a new battle session in the server process.

The OnStartBattleSession function takes a FServerBattleSession object as an input parameter. This object includes key game battle information such as battle session id, battle property format in key-value pairs, team structure, and battle members information.

The function implementation should accomplish the following tasks:

• Preparations to start a new battle session based on the FServerBattleSession object.

• Call ActivateBattleSession when the new battle session is ready to accept players. In response to a successful call, the PGOS service will change the battle session status to ACTIVE.

4. Validate a New Player

This task is optional.

// 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
    ...
}

Add code to verify a player connection request with the PGOS service. This code should run whenever a new player attempts to connect to the server process before a player connection is accepted. Player validation enables PGOS to track current players and available slots in the battle session.

Connection requests from a game client should include a player-battle-session-ID. This ID is generated by the PGOS service when the game client asks to join a battle session (for example, a "start matchmaking" request). The ID is used to reserve a player slot in the battle session. On receiving a game client connection request, the server process calls AcceptPlayerBattleSession with the player-battle-session-ID. PGOS then verifies whether a player-battle-session-ID was reserved in the battle session. Once the AcceptPlayerBattleSession returns True, the status of player battle session will become Active.

Once the player battle session ID is validated by PGOS, the server process can accept the connection. If the player battle session ID is not validated by the PGOS service, the server process should deny the connection.

5. Report a Player Battle Session Disconnected

This task is optional.

// 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
}

Call DisconnectPlayerBattleSession to notify the PGOS service when a player disconnected from game DS. After calling this interface the status of the player battle session will changed to Disconnected , and before the status becomes Completed, the status can still be restored to Active by calling AcceptPlayerBattleSession again.

6. Report a Player Battle Session Ending

This task is optional.

// 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
}

Call RemovePlayerBattleSession to notify the PGOS service when a player leaves the battle session. After calling this interface the status of the player battle session will changed to Completed, and the player battle session will not be accept by PGOS.

7. End a Battle Session

This task is required.

Game DS should shut down once a battle session is end in order to recycle and refresh hosting resources. We do not support hosting multiple games in the life cycle of DS. Here's an example of the game server process exit flow:

1. Battle session comes to an end.
2. Do custom preparation for exit.
3. Call ProcessEnding to notify PGOS service that the game server process is shutting down.
4. Exit game DS.

Remark: Interface TerminateBattleSession was deprecated in version v 0.9.0.

8. Respond to a Server Process Shutdown Notification

This task is required.

The callback function, OnProcessTerminate is called when the game server process has been consistently reported as unhealthy, or if the instance where the game server process is running on is about to be terminated.

9. Testing Your Integration

To facilitate the rapid deployment of the game on a DS in a non-production environment, PGOS provides a local DS mechanism. This allows you to deploy a game on a local (non-cloud) DS without having to add any additional code to the DS or game client. This type of DS is included in the PGOS work system as an available DS and allocated to the game client. This will be useful when integrating PGOS with your game server. Click here for more details