Client SDK Instance Mode

The PgosSDK instance is an entry object for accessing PGOS services in the game,it includes APIs for client-side and server-side usage. As a C++ class object instance, it has its data and context, and in the game client, one PgosSDK instance can only serve one Local Player.

class IPgosSDKCpp
{
public:
    /** Get PgosSDK instance */
    static IPgosSDKCpp& Get(ULocalPlayer* LocalPlayer = nullptr);
    ...
    /** Client API */
    virtual PgosClientPtr GetClientAPI() const = 0;
    virtual PgosClientBattlePtr GetClientBattleAPI() const = 0;
    virtual PgosClientBlocklistPtr GetClientBlocklistAPI() const = 0;
    ...
    /** Server API */
    virtual PgosServerPtr GetServerAPI() const = 0;
    virtual PgosServerBattlePtr GetServerBattleAPI() const = 0;
    virtual PgosServerEconomyPtr GetServerEconomyAPI() const = 0;
    ...
}

The Client PgosSDK Instance Mode represents the PgosSDK instance management mode in the game client, which consists of two modes:

• Singleton: the PgosSDK instance is a singleton instance in the game client.
• LocalPlayerBased: the number of PgosSDK instances in the game client is based on the number of local players, with each local player having their own PgosSDK instance.

tip

For the game server, the PgosSDK always exists as a single global instance, meaning it operates in Singleton mode.

1. Configuring Modes

In the Unreal Engine Editor, navigate to Settings->Project Settings->Plugins->PgosSDK->Client Settings, then you can configure the Client PgosSDK Instance Mode:

2. Programming Differences

In this chapter, we will discuss some differences in programming between these two modes.

2.1 Singleton Mode

Singleton Mode is the default mode, where the PgosSDK exists as a single global instance in the game client. When programming in this mode, please pay attention to the following points:

• The LocalPlayer parameter of the IPgosSDKCpp::Get API will be ignored.

  // The Get PgosSDK instance API:
  //     static IPgosSDKCpp& Get(ULocalPlayer* LocalPlayer = nullptr)
  // You can ignore the `LocalPlayer` parameter:
  IPgosSDKCpp::Get().CreatePGOS();
  auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();

• If you need to perform blueprint programming related to PGOS in the game client, use the static function version of APIs instead of the LocalPlayerSubsystem version. Specifically:

  • CreatePGOS: use UPgosSDKBp::CreatePGOS instead of PgosClientSDKBpSubsystem::CreatePGOS.
  • DestroyPGOS: use UPgosSDKBp::DestroyPGOS instead of PgosClientSDKBpSubsystem::DestroyPGOS.
  • ClientEventDispatcher: use PgosClientEventDispatcher instead of PgosClientEventDispatcherSubsystem to listen for client PgosSDK events.
  • Other Client Blueprint APIs: the Owner Player parameter of the API can be ignored.

  

2.2 LocalPlayerBased Mode

LocalPlayerBased Mode means that the number of PgosSDK instances in the game client is based on the number of local players, with each local player having their own PgosSDK instance. When programming in this mode, please pay attention to the following points:

• Make sure to pass in a valid local player to the LocalPlayer parameter when calling the IPgosSDKCpp::Get API.

  // The Get PgosSDK instance API:
  //     static IPgosSDKCpp& Get(ULocalPlayer* LocalPlayer = nullptr)
  // Make sure to pass in a valid local player to the `LocalPlayer` parameter:
  IPgosSDKCpp::Get(LocalPlayer).CreatePGOS();
  auto spFAS = IPgosSDKCpp::Get(LocalPlayer).GetClientFakeAccountAPI();

• If you need to perform blueprint programming related to PGOS in the game client, use the LocalPlayerSubsystem version of APIs instead of the static function version. Specifically:

  • CreatePGOS: use PgosClientSDKBpSubsystem::CreatePGOS instead of UPgosSDKBp::CreatePGOS.
  • DestroyPGOS: use PgosClientSDKBpSubsystem::DestroyPGOS instead of UPgosSDKBp::DestroyPGOS.
  • ClientEventDispatcher: use PgosClientEventDispatcherSubsystem instead of PgosClientEventDispatcher to listen for client PgosSDK events.
  • Other Client Blueprint APIs: must pass in a valid local player to the Owner Player parameter.

  

3. Advice on Mode Selection

Here is some advice on the selection of Client PgosSDK Instance Mode, you can choose a suitable Client PgosSDK Instance Mode based on your scenarios and needs.

• If you are developing a multiplayer game, the LocalPlayerBased mode is recommended as it allows you to launch multiple game instances with different player accounts (multiple PgosSDK instances within one process) using the PIE mode in Unreal Editor. This is very useful for developers to debug/test multiplayer games.

  You cannot launch multiple game instances with different player accounts through Singleton + PIE mode, because in the game client, one PgosSDK instance can only serve one Local Player.

  

  The screenshot below showcases an example of launching 6 player instances using LocalPlayerBased + PIE mode. This method is faster and more convenient compared to the Singleton + Standalone Game mode.

  

  On the other hand, the LocalPlayerBased mode requires you to pass a valid LocalPlayer instance when obtaining the PgosSDK instance, which requires some design considerations in your code architecture.

• If you are developing a Local multiplayer game where multiple players play in a single process, and each player has their own account running in the game (similar to the game "It Takes Two" on Xbox), then the LocalPlayerBased mode is your only choice.

  

• If you prioritize the convenience of obtaining the PgosSDK instance during coding and are NOT developing a local multiplayer game, then the Singleton mode would be a suitable choice.