Integration

1. Overview

This article describes the game modules that need to interact with the DS Hosting service and how to integrate these game modules with PGOS DS Hosting service.

1.1 Key Components

• Game Server (DS) are server-side processes running on a fleet. A game server process will hold a battle session and accept connecting requests from game clients.
• Game Client is process running on player's device. The game client can communicate with PGOS using the PGOS Client SDK if you need to request DS resources through the PGOS battle services (Matchmaking and Lobby).
• Game Backend Service are custom services that handle request and events with PGOS. We recommend that the backend service relay all the game client's communication with PGOS if the PGOS Client SDK is not integrated to your game client.
• Battle Session is a game running on your game server. Battle sessions can be created by the PGOS battle service (Matchmaking, Lobby), or by DS Hosting Standalone API that PGOS provides.

1.2 Standalone Mode of DS Hosting

The PGOS battle service (Matchmaking and Lobby) is seamlessly integrated with the ds hosting service. For example, the matchmaking service will automatically request a suitable ds resource when some players were found for a match.

In addition, a HTTP API suit is provided to the games to access the DS Hosting Service without PGOS battle service. We call this the Standalone-mode of DS Hosting service. Here is a comparison of the two approaches to ds hosting services:

Factors	Use DS Hosting with Matchmaking / Lobby	Use DS Hosting with Standalone API (Standalone mode)
PGOS Client SDK	Required	Not required
PGOS Server SDK	Required	Required
DS Standalone API	Not required	Required
PGOS Player Auth	Required	Not required
Player Identity	PGOS built-in	Provided by Game in API

2. Use DS Hosting with Matchmaking / Lobby / World

2.1 Work Flow

• Register game server - Register a running ds instance to the DS Hosting service with PGOS Server SDK, only registered ds instances will be assigned battle sessions.
• Create/Activate battle session - The battle session created by the PGOS Battle Sevices is placed on a registered DS. After the battle session is activated by the DS, PGOS pushes the DS access info to the game client that participating in the battle session.
• Player in and out - PGOS provides a set of interfaces to help DS validate and manage player sessions in a battle.
• Shut down the battle session - Once the battle session is over, DS needs to notify PGOS and end the process. PGOS will pull up a new DS process in preparation for the arrival of the new battle session.

2.2 Preparing Player Latency Data

PGOS will initiate speed test to all available Data Center regions after a player successfully login. The resulting player latency data will be refreshed at a lower frequency and will be used for battle session placement when using services such as Matchmaking, Lobby, and World, aiming to select game servers with better latency for players.

This speed test behavior is performed by the PGOS Client SDK and typically does not require further attention from the game. However, we still provide an interface for the game client to obtain this player latency data, with example code as follows:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Battle = IPgosSDKCpp::Get().GetClientBattleAPI();
   if (Battle)
   {
       
       Battle->GetDSHostingLatencies([]() {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("GetDSHostingLatencies Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("GetDSHostingLatencies Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

2.3 Check Current Battle Sessions for a Player

PGOS allow a player to join multiple battle sessions at the same time, and the game client can query the information of the battle sessions the player is currently in through the DescribeBattleSessions interface. This interface will return all the information needed for a player to connect the ds that holding the battle session, including access IP, port and player battle session id.

void SomeUObjectClass::Function()
{
    FPgosResult Result = IPgosSDKCpp::Get().GetClientBattleAPI()->DescribeBattleSessions(
        Player->PlayerBattleSessionID);

    PGOS_CALL_ASYNC_API(UPgosClientAPIDescribeBattleSessions::DescribeBattleSessions,
                        this,
                        &SomeUObjectClass::DescribeBattleSessionsSuccess,
                        &SomeUObjectClass::DescribeBattleSessionsFailed);
}

void SomeUObjectClass::DescribeBattleSessionsSuccess(const FPgosResult& Error,const FClientDescribeBattleSessionsResult& result)
{
    UE_LOG(LogTemp, Log, TEXT("DescribeBattleSessionsSuccess"))
}

void SomeUObjectClass::DescribeBattleSessionsFailed(const FPgosResult& Error,const FClientDescribeBattleSessionsResult& result)
{
    UE_LOG(LogTemp, Log, TEXT("DescribeBattleSessionsFailed"))
}

2.4 Startup a Battle Session From Matchmaking

Battle sessions could be created form PGOS Battle Services. Read Matchmaking Integration to learn how to create a battle session through Matchmaking Service. Read Lobby Integration to learn how to create a battle session through Lobby Service.

2.5 Separate a Player from the Battle Session

A game client can separate the logged player from a battle session by calling the interface TerminatePlayerBattleSession . After the calling completed, the player will no longer be able to enter this battle session, please use with caution.

void SomeUObjectClass::Function()
{
    FPgosResult Result = IPgosSDKCpp::Get().GetClientBattleAPI()->DescribeBattleSessions(
        Player->PlayerBattleSessionID);

    PGOS_CALL_ASYNC_API(UPgosClientAPITerminatePlayerBattleSession::TerminatePlayerBattleSession,
                        this,
                        &SomeUObjectClass::DescribeBattleSessionsSuccess,
                        &SomeUObjectClass::DescribeBattleSessionsFailed,
                        BattleSessionId,
                        PlayerBattleSessionId);
}

void SomeUObjectClass::TerminatePlayerBattleSessionSuccess(const FPgosResult& Error,const FClientTerminatePlayerBattleSessionResult& result)
{
    UE_LOG(LogTemp, Log, TEXT("TerminatePlayerBattleSessionSuccess"))
}

void SomeUObjectClass::TerminatePlayerBattleSessionFailed(const FPgosResult& Error,const FClientTerminatePlayerBattleSessionResult& result)
{
    UE_LOG(LogTemp, Log, TEXT("TerminatePlayerBattleSessionFailed"))
}

2.6 Events for Battle Session Placement

During the whole battle life cycle, the following events will be triggered:

• event_battle_session_placement_fulfilled
• event_battle_session_placement_timedout
• event_battle_session_placement_failed

For their data schema, please refer to WebPortal \ Extensions \ Event.

For the WebHook encapsulation, please refer to WebHook document.

3. Use DS Hosting with Standalone API

3.1 Work Flow

• Register game server - Register a running ds instance to the DS Hosting service, only registered ds instances will be assigned battle sessions.
• Create/Activate battle session - The battle session created through the Standalone HTTP API is placed on a registered DS. After the battle session is activated by the DS, PGOS pushes the DS access info to the game client that participating in the battle session.
• Player in and out - PGOS provides a set of interfaces to help DS validate and manage player sessions in a battle.
• Shut down the battle session - Once the battle session is over, DS needs to notify PGOS and end the process. PGOS will pull up a new DS process in preparation for the arrival of the new battle session.

3.2 Check Current Battle Sessions for a Player

PGOS allow a player to join multiple battle sessions at the same time, and the game can query the information of the battle sessions the player is currently participated by PGOS HTTP API QueryPlayerBattleSessions. This interface will return all the information needed for a player to connect the ds that holding the battle session, including access IP, port and player battle session id.

3.3 Startup a Battle Session

Battle sessions could be created form DS Hosting Standalone HTTP API.

Use the RequestBattleSessionID interface to request a battle session id from the PGOS backend before initiating a battle session placement request. Battle session placement work should be abort if any error occurs on this interface.

Then, use StartBattleSessionPlacement to require a dedicated server and place the battle session on it. And use the CancelBattleSessionPlacement interface to terminate an in-progress battle session placement.

Progress of a battle session placement could be tracked by calling DescribeBattleSessionPlacement interface or handling PGOS Events.

Players can be added to a battle session with AddPlayersToBattleSession interface.

3.4 Separate a Player from the Battle Session

A game client can separate the logged player from a battle session by calling the interface TerminatePlayerBattleSession. After the calling completed, players will no longer be able to enter this battle session, please use with caution.

3.5 Events for Battle Session Placement

During the whole battle life cycle, the following events will be triggered:

• event_battle_session_placement_fulfilled
• event_battle_session_placement_timedout
• event_battle_session_placement_failed

For their data schema, please refer to WebPortal \ Extensions \ Event.

For the WebHook encapsulation, please refer to WebHook document.

4. Integrate Your Game Server

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.

4.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.

4.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.

4.3 Activate a Battle Session

This task is required.

Add code to handle the notification OnStartBattleSession. The PGOS service invokes this function in order to place a new battle session on the server process.

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

To handle OnStartBattleSession notification the following tasks should be accomplished:

• Preparations to start a new battle session based on the ServerBattleSession 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.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.

4.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.

4.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.

4.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 battle sessions in one 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.
4. The DS process terminate it self.

Notes on the ProcessEnding interface:

• Calling ProcessEnding will signals PGOS that the process is ending. PGOS will kill the process by force if it do not exit in 2mins after ProcessEnding is called. The force killing mechanism is only a BACKUP PLAN for handling DS abnormal states and it has a certain delay, which will REDUCE the battle session load capacity of the DS fleet. Therefore, we still recommend that the DS actively terminate after calling ProcessEnding interface.
• DS needs to handle the process exit itself when running in local mode.
• The battle session running on this DS process will be terminated immediately.

tip

Interface TerminateBattleSession was deprecated in version v 0.9.0.

4.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.

4.9 Other Notifications

The game can handle the following notifications as require:

Notification	Description
FPgosHostingAPI::OnBattleSessionUpdated	Triggered when players are added to the battle session.
FPgosHostingAPI::OnPlayerBattleSessionsTerminated	Triggered when players terminate their player battle session.
FPgosHostingAPI::OnBattlePlayerOffline	Triggered when player's game client is offline.
FPgosHostingAPI::OnBattlePlayerBanned	Triggered when player is banned by PGOS.

4.10 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.

5. Shared Memory Mode

Some games need to utilize the fork mechanism of the Linux platform into the creation process of ds instances to improve the utilization of idle memory resources. Currently, PGOS has supported this behavior for DS, which we have named the Shared-memory Mode for the DS Hosting service.

This section explains how PGOS supports the working mode of forkable ds and how to make your forkable ds work in the PGOS hosting service.

5.1 Key Components

• Agent is a process running CVM to implement the ds hosting service. This process provides the game server with several interfaces related to hosting service with the PGOS Server SDK. And its existence is transparent for the game server process.
• Forking game server is the only process that is launched by PGOS in shared-memory mode, it Does NOT hold any battle session. Its role is to execute fork() operations to create child processes at the right time and to monitor the number of child processes and their running status to determine whether new child processes need to be forked.
• Forked game servers are the processes launched by forking game server in shared-memory mode. Battle sessions will only be placed on forked game servers in shared-memory mode.

5.2 Integrate Your Forking (Parent) Game Server

5.2.1 Create PGOS for Forking Process

Using multiple threads in the parent process where the fork function is called can lead to many exceptions, so the PGOS Server SDK isolates the calling to the forking process from the standard interface.

The forking process and the forked process will use the same PGOS Server SDK file, but will call different interfaces to create the corresponding PGOS instances.

Add the following codes to the appropriate location of your game project to create PGOS for the forking process:

void SomeClass::SomeFunc()
{
    IPgosSDKCpp::Get().CreatePGOSForingProcess();
    // ...
}

5.2.2 Initialize the Forking Process

Notify PGOS that a server process working on shared-memory mode and is about to fork child processes by calling ProcessReady of the ServerHostingForking module:

void SomeClass::SomeFunc()
{
    if (auto ServerHostingFrokingAPI = IPgosSDKCpp::Get().GetServerHostingForkingAPI())
    {
        TArray<FString> LogPathes;
        const auto Result = ServerHostingFrokingAPI->ProcessReady(LogPathes);
        // ...
    }
}

5.2.3 Maintain a Certain Number of Forked Processes

The game needs to maintain some child game server through the forking game server in shared-memory mode, which is covered by PGOS CVM Hosting in normal mode.

Two interfaces are provided to help maintain amount of forked processes:

• QueryDsInstancePerCVMConfig: Query DS instance per cvm configuration of the fleet, which is the maximum effective number of (child) DS processes that users expect to run on the current CVM instance.
• QueryAvailableDsInstanceCount: Query the number of (child) DS processes registered on the PGOS hosting service in the current CVM. This parameter can be used as a decision reference for the fork operation in the parent process.

Both above interfaces are provided in the ServerHostingForking module:

void SomeClass::SomeFunc()
{
    if (auto ServerHostingFrokingAPI = IPgosSDKCpp::Get().GetServerHostingForkingAPI())
    {
        int32 MaxDsCnt = HostingForkingAPI->QueryDsInstancePerCVMConfig();
        int32 CurDsCnt = HostingForkingAPI->QueryAvailableDsInstanceCount();
        // ...
    }
}

5.3 Integrate Your Forked (Child) Game Server

The integration process for the forked game server is the same as for the normal mode, please refer to chapter Integrate Your Game Server. Note that you should not change the working mode of the game server during the lifetime of the CVM instance, as this will make the CVM instance unavailable.

5.4 Sample Code

Once you have completed the above steps, you can add fork logic to your game server to create forked game servers which will be registered to the PGOS hosting service and can receive battle session placement requests from the OnStartBattleSession event.

PGOS Sample: Ping-pong Shooter has now support for shared-memory mode to make it easier for you to experience the feature and understand the use of the related PGOS interfaces.

Note

The forking implementation in the PGOS Sample is for demonstration purposes only. Please develop the forking logic in the game on your own to make it more suitable for the actual needs of the game.

• Options needs:

  • -forking to enable shared-memory mode for Ping-pong Shooter.
  • -nothreading to enable single-thread mode of UE which is recommended by the engine.

• Fork works implement: UnixPlatformHelper.h/FUnixPlatformHelper::WaitAndFork()

  This function is overriding from FUnixPlatformProcess::WaitAndFork(), simplifies the child process creation process, and monitors the number of child processes with the help of the interface provided by the ServerHostingForking module.

• The fork point: The PGOS Sample involving the fork works in the AGameModeBase::InitGame function. The timing may not be optimal for your game, please choose the appropriate fork point based on the requirements of the game.

The below diagram shows the workflow of forking&forked game server processes in the PGOS Sample: