Integrate PGOS C++ SDK

This article explains the general steps for using PGOS C++ SDK here, it takes the case Visual Studio + PGOS Windows SDK as an example for explanation, and you can download the C++ SDK Sample as a reference.

1. Introduction to the Sample Structure

C++ SDK Sample includes two sub-projects for demonstrating the PGOS Client/Server SDK. All projects are managed through CMake:

• ClientSample: Sub-project for demonstrating the PGOS Client SDK.

• ServerSample: Sub-project for demonstrating the PGOS Server SDK.

• deps: Contains the PGOS SDK and some common code. In the screenshot below, we renamed the windows directory of PGOS SDK package to pgos_sdk_windows in ./deps.

  

• Script: Contains a batch script for generating a Visual Studio solution and completing the build process.

2. Additional Include Directories for PGOS SDK

• For Client Sample CMakeLists file:

  

  /deps/pgos_sdk_windows/include/pgos_core/raw

  /deps/pgos_sdk_windows/include/pgos_core

  /deps/pgos_sdk_windows/include/pgos_client/raw

  /deps/pgos_sdk_windows/include/pgos_client

• For Server Sample CMakeLists file:

  

  /deps/pgos_sdk_windows/include/pgos_core/raw

  /deps/pgos_sdk_windows/include/pgos_core

  /deps/pgos_sdk_windows/include/pgos_server/raw

  /deps/pgos_sdk_windows/include/pgos_server

3. Change the Build Configs

PGOS SDK currently only provides x64 Release version for Windows.

4. Coding For Client

4.1 General Steps

• Add Header File Include

  #include "pgos_client_sdk.h"

• Create and Destroy PGOS

  void CreatePGOS() {
      auto sdk = pgos::client::ClientSDK();
      if (sdk) {
          auto root_dir = GetRootDir();
          sdk->InitSdk(root_dir.append("/pgos/"), root_dir.append("/pgos_res/"));
          
          // the original secret key can be obtained from the developer portal,
          // it is recommended not to hardcode the original secret key in the code.
          const char* encrypted_secret_key = "the ciphertext of the original secret key";
          auto secret_key = SimpleDecrypt(encrypted_secret_key);
  
          pgos::pmap<pgos::pstring, pgos::pstring> cfgs;
          cfgs["title_id"] = "your title id";  // obtain from the developer portal
          cfgs["secret_key"] = secret_key;
          sdk->InitConfig(cfgs);
      }
  }
  
  void DestoryPGOS() {
      auto sdk = pgos::client::ClientSDK();
      if (sdk) {
          sdk->Destroy();
      }
  }
  
  int main()
  {
      CreatePGOS();
  
      // other business code...
      
      DestoryPGOS();
      return 0;
  }

• How to get PGOS modules

  All modules can be found and get object pointers through the help functions in pgos_client_sdk.h, and then you can call the module APIs.

  // get module object pointers.
  auto sdk = pgos::client::ClientSDK();
  auto fas = pgos::client::FakeAccount();
  auto auth = pgos::client::PlayerAuth();
  // ...
  
  // call module APIs.
  auto my_player_id = auth->MyPlayerID();
  // ...

  Before making actual calls to the PGOS services, you must first successfully log in to PGOS (call IPlayerAuth::LoginPGOS API).

• How to listen to the module events

  Bind a handler function or lambda to the event through the module's SetOn*() APIs:

  auto auth = pgos::client::PlayerAuth();
  if (!auth) {
      return;
  }
  
  auth->SetOnPlayerBanned(OnPlayerBanned);
  auth->SetOnPlayerSessionChanged(
      [](const PlayerSessionChangedEvt& event) {
          // todo
      });

• Key Notes

  • In PGOS C++ SDK, all API callbacks and event callbacks are executed in child threads, so it is important to consider thread safety when accessing data in a callback.
  • When accessing PGOS services, whether using C++ SDK or Unreal Plugin, the overall process and method are the same. So, for more details about the use of PGOS SDK, you can also refer to service manual.

4.2 Workflow of Client Sample

The workflow of the Client Sample is managed by a state machine. Below is a description of the tasks performed by the sample in each state.

• Idle: Waiting for state transition to occur.
• ToLoginAccountSystem: Logging into the account system. This is done using the PGOS fake account system in the Client Sample.
• ToLoginPGOS: Logging into PGOS is required after logging into the account system.
• ToChooseTask: Selecting the task to be executed. The following options are provided:
  • Initiating a single-player matchmaking, and user needs to input the matchmaking config name.
  • Directly connecting to Server Sample, where the user needs to input the DS port.
• ToConnectDS: Directly connecting to DS. The user needs to input the DS port.
• ToMatchmaking: Initiating a single-player match. The user needs to input the matchmaking config ID.
• ToStop: Terminating the sample.

// ClientSample.cpp
enum class ClientState {
    Idle,                   // do nothing and wait state change.
    ToLoginAccountSystem,   // login account system.
    ToLoginPGOS,            // login PGOS.
    ToChooseTask,           // choose to start matchmaking or connect DS directly.
    ToMatchmaking,          // start matchmaking and wait till complete.
    ToConnectDS,            // connect to DS when matchmaking complete.
    ToStop,                 // client stop.
};

Note: To use the ToMatchmaking feature, you must first deploy the Server Sample to the PGOS DS Hosting service. Please refer to the following documentation for more information on the relevant features:

• DS Hosting service.
• Matchmaking service.

5. Coding For Server

5.1 General Steps

• Add Header File Include

  #include "pgos_server_sdk.h"

• Create and Destroy PGOS

  void CreatePGOS() {
      auto sdk = pgos::server::ServerSDK();
      if (sdk) {
          auto root_dir = GetRootDir();
          sdk->InitSdk(root_dir.append("/pgos/"), root_dir.append("/pgos_res/"));
          
          pgos::pmap<pgos::pstring, pgos::pstring> cfgs;
          cfgs["title_id"] = "your title id";  // obtain from the developer portal
          sdk->InitConfig(cfgs);
      }
  }
  
  void DestoryPGOS() {
      auto sdk = pgos::server::ServerSDK();
      if (sdk) {
          sdk->Destroy();
      }
  }
  
  int main()
  {
      CreatePGOS();
  
      // other business code...
      
      DestoryPGOS();
      return 0;
  }

• How to get PGOS modules

  All modules can be found and get object pointers through the help functions in pgos_server_sdk.h, and then you can call the module APIs.

  // get module object pointers.
  auto sdk = pgos::server::ServerSDK();
  auto hosting = pgos::server::Hosting();
  auto player_profile = pgos::server::PlayerProfile();
  // ...
  
  // call module APIs.
  player_profile->GetPlayerInfo(...);
  // ...

• How to listen to the module events

  Bind a handler function or lambda to the event through the module's SetOn*() APIs:

  auto hosting = pgos::server::Hosting();
  if (!hosting) {
      return;
  }
  
  hosting->SetOnHealthCheck(OnHealthCheck);
  hosting->SetOnStartBattleSession(
      [](const pgos::server::BattleSession & battle_session) {
          // todo
      });

• Key Notes

  • In PGOS C++ SDK, all API callbacks and event callbacks are executed in child threads, so it is important to consider thread safety when accessing data in a callback.
  • When accessing PGOS services, whether using C++ SDK or Unreal Plugin, the overall process and method are the same. So, for more details about the use of PGOS SDK, you can also refer to service manual.

5.2 Workflow of Server Sample

The Server Sample registers itself as a Local DS when running locally. You can also deploy the Server Sample to a Fleet as an Online DS.

After running, the Server Sample starts a TCP server to handle client connection requests and manages the process declaration period in the WorkLoop thread.

// server life cycle control 
std::thread workerThread(WorkLoop);

// will block until the g_server stops.
g_server.Run();

if (workerThread.joinable()) {
    workerThread.join();
}

The following callbacks are used to handle battle session placement requests and player events. For more details on managing battle sessions, please refer to Battle Session.

// monitor hosting events
hosting->SetOnHealthCheck(OnHealthCheck);
hosting->SetOnStartBattleSession(OnStartBattleSession);
hosting->SetOnProcessTerminate(OnProcessTerminate);
hosting->SetOnPlayerBattleSessionsTerminated(OnPlayerSessionTerminated);
hosting->SetOnBattleSessionUpdated(OnBattleSessionUpdated);
hosting->SetOnBattlePlayerBanned(OnBattlePlayerBanned);
hosting->SetOnBattlePlayerOffline(OnBattlePlayerOffline);

6. Run the Project

Build the project and get the executable file, copy the pgos_client/pgos_server binary file to the directory where the executable file is located, and then you can run or debug the program.

The binary files are in the bin directory of the SDK.