跳到主要内容

客户端 SDK 实例模式

PgosSDK实例是在游戏中访问PGOS服务的入口对象，它包含了客户端和服务器端使用的API。作为一个C++类对象实例，它具有自己的数据和上下文，在游戏客户端中，一个PgosSDK实例只能服务于一个本地玩家。

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

客户端 PgosSDK 实例模式表示游戏客户端中 PgosSDK 实例的管理模式，包含两种模式：

  • 单例模式：PgosSDK 实例在游戏客户端中是一个单例实例。
  • 本地玩家模式：游戏客户端中 PgosSDK 实例的数量取决于本地玩家的数量，每个本地玩家都有自己的 PgosSDK 实例。
提示

对于游戏服务器，PgosSDK 始终以单一全局实例的形式存在，即以单例模式运行。

1. 配置模式​

在虚幻引擎编辑器中，导航至 Settings->Project Settings->Plugins->PgosSDK->Client Settings，然后您可以配置 Client PgosSDK Instance Mode：

image-20240417163532526

2. 编程差异​

本章将讨论这两种模式在编程方面的一些差异。

2.1 单例模式​

单例模式是默认模式，在该模式下PgosSDK作为游戏客户端中的单个全局实例存在。在使用此模式编程时，请注意以下几点：

IPgosSDKCpp::Get API的LocalPlayer参数将被忽略。

// 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();

如果您需要在游戏客户端中进行与PGOS相关的蓝图编程，请使用API的静态函数版本而不是LocalPlayerSubsystem版本。具体来说：

  • CreatePGOS：使用UPgosSDKBp::CreatePGOS而不是PgosClientSDKBpSubsystem::CreatePGOS。
  • DestroyPGOS：使用UPgosSDKBp::DestroyPGOS而不是PgosClientSDKBpSubsystem::DestroyPGOS。
  • ClientEventDispatcher：使用PgosClientEventDispatcher而不是PgosClientEventDispatcherSubsystem来监听客户端PgosSDK事件。
  • 其他客户端蓝图API：API的Owner Player参数可以忽略。

image-20240506150004917

2.2 LocalPlayerBased 模式​

LocalPlayerBased 模式指游戏客户端中 PgosSDK 实例的数量是基于本地玩家数量的，每个本地玩家都有自己的 PgosSDK 实例。在此模式下编程时，请注意以下几点：

调用 IPgosSDKCpp::Get API 时，确保为 LocalPlayer 参数传入有效的本地玩家。

// 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();

如果需要在游戏客户端中进行与 PGOS 相关的蓝图编程，请使用 LocalPlayerSubsystem 版本的 API，而不是静态函数版本。具体来说：

  • CreatePGOS：使用 PgosClientSDKBpSubsystem::CreatePGOS 而不是 UPgosSDKBp::CreatePGOS。
  • DestroyPGOS：使用 PgosClientSDKBpSubsystem::DestroyPGOS 而不是 UPgosSDKBp::DestroyPGOS。
  • ClientEventDispatcher：使用 PgosClientEventDispatcherSubsystem 而不是 PgosClientEventDispatcher 来监听客户端 PgosSDK 事件。
  • 其他客户端蓝图 API：必须为 Owner Player 参数传入有效的本地玩家。

image-20240506151104176

  1. 模式选择建议

以下是关于选择Client PgosSDK Instance Mode的一些建议，您可以根据自己的场景和需求选择合适的Client PgosSDK Instance Mode。

  • 如果您正在开发多人游戏，建议使用LocalPlayerBased模式，因为它允许您在虚幻编辑器的PIE模式下使用不同的玩家账号启动多个游戏实例（在一个进程中运行多个PgosSDK实例）。这对于开发者调试/测试多人游戏非常有用。

您无法通过Singleton + PIE模式启动使用不同玩家账号的多个游戏实例，因为在游戏客户端中，一个PgosSDK实例只能服务于一个本地玩家。

image-20240423155706075

下图展示了使用 LocalPlayerBased + PIE 模式启动6个玩家实例的示例。与 Singleton + 独立游戏模式相比，这种方法更快捷方便。

image-20240423154026358

另一方面，LocalPlayerBased 模式在获取 PgosSDK 实例时需要传入一个有效的 LocalPlayer 实例，这需要在代码架构设计时进行一些考虑。

  • 如果您正在开发一个本地多人游戏，其中多个玩家在同一个进程中游玩，且每个玩家都有自己的游戏账号（类似于 Xbox 上的游戏《双人成行》），那么 LocalPlayerBased 模式是您唯一的选择。

    image-20240423163408956

  • 如果您在编码时优先考虑获取 PgosSDK 实例的便利性，且不开发本地多人游戏，那么 Singleton 单例模式将是一个合适的选择。