调用 PgosSDK 接口

PgosSDK 提供两种类型的API：C++ API和蓝图API。您可以根据需要只调用其中一种类型，或混合使用两种类型。某些API需要在其他API之前调用，也就是说，您需要先调用CreatePGOS、InitConfig、LoginPGOS，这些将为其他API调用准备工作环境。详情请点击编程快速入门。

在调用LoginPGOS之前可以调用FakeAccount接口API，FakeAccount接口用于FAS登录。

完成本教程后，您将学会：

如何调用PgosSDK C++ API。
如何调用PgosSDK蓝图API。

1. 调用 PgosSDK C++ API

PgosSDK 插件中的 PgosSDKCpp 模块提供了 PGOS C++ API。

1.1 获取服务接口

所有服务接口都可以在 PgosSDKCpp.h 中找到：

class IPgosSDKCpp : public IModuleInterface
{
public:
    /** Get PgosSDKCpp singleton instance */
    static IPgosSDKCpp& Get();

    /** Create and Destroy PGOS in the main thread */
    virtual void CreatePGOS() = 0;   // Create PGOS service, must be called first before using PGOS service.
    virtual void DestroyPGOS() = 0;  // Destroy PGOS service, should be called during process shutdown if possible.

    /** Server API */
    virtual PgosServerPtr GetServerAPI() const = 0;  // Server global interface
    virtual PgosServerBattlePtr GetServerBattleAPI() const = 0;  // Battle interface
    virtual PgosServerEconomyPtr GetServerEconomyAPI() const = 0;  // Economy interface
    virtual PgosServerHostingPtr GetServerHostingAPI() const = 0;  // Hosting interface
    ...

    /** Client API */
    virtual PgosClientPtr GetClientAPI() const = 0;  // Client global interface
    virtual PgosClientEconomyPtr GetClientEconomyAPI() const = 0;  // Economy interface
    virtual PgosClientFakeAccountPtr GetClientFakeAccountAPI() const = 0;  // FakeAccount interface
    virtual PgosClientPlayerAuthPtr GetClientPlayerAuthAPI() const = 0;  // PlayerAuth interface
    ...
}    

要获取相应的服务实例，只需调用相应的Get*API()函数。例如，以下代码将获取FakeAccount的服务实例：

auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();

获取服务实例后，您可以调用其所有服务 API，这些 API 可以在 "Core/Pgos{ServiceName}API.h" 文件中找到。

1.2 调用API

PgosSDK中包含同步和异步API，一般来说，带有回调参数的API为异步，不带回调参数的API为同步。异步API的回调会在Game Thread中执行，我们为每个功能提供了两个API，分别提供不同的回调形式：Delegate回调和TFunction回调，您可以选择喜欢的回调方式。以下是FAS登录功能的两个API声明示例：

DECLARE_DELEGATE_TwoParams(FPgosClientOnLogin, const FPgosResult& /* Result */, const FClientFasLoginInfo* /* Data */)
/**
 * Log in with the specified account.
 * The FAS account does not need to be registered in advance, it can be any string without line breaks ('\r', '\n') and is managed by the game.
 * 
 * @param Account FAS account, if the account is empty, then will use a local historical account.
 * @param ResultDelegate The result delegate after the API execution ends, and it will be called in the GAME THREAD.
 */
void Login(
    const FString& Account,
    FPgosClientOnLogin ResultDelegate) const;

/**
 * Log in with the specified account.
 * The FAS account does not need to be registered in advance, it can be any string without line breaks ('\r', '\n') and is managed by the game.
 * 
 * @param Account FAS account, if the account is empty, then will use a local historical account.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void Login(
    const FString& Account,
    TFunction<void(const FPgosResult& Ret, const FClientFasLoginInfo* Data)> ResultCallback) const;

以下是 FAS 登录 API 调用的示例代码：

#include "PgosSDKCpp.h"

// using the TFunction callback.
void SomeUObjectClass::CallWithLambda()
{
    auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();
    if (spFAS)
    {
        FString MyAccount = TEXT("SomeAccountString");
        spFAS->Login(MyAccount, [](const FPgosResult& Ret, const FClientFasLoginInfo* LoginInfo) {
            UE_LOG(LogTemp, Log, TEXT("On FAS login callback."));
        });
    }
}

// using the Delegate callback.
void SomeUObjectClass::CallWithDelegate()
{
    auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();
    if (spFAS)
    {
        FString MyAccount = TEXT("SomeAccountString");
        FPgosClientOnLogin CallbackDelegate;
        CallbackDelegate.BindUObject(this,&SomeUObjectClass::OnFASLoginCallback);
        spFAS->Login(MyAccount, CallbackDelegate);
    }
}

void SomeUObjectClass::OnFASLoginCallback(const FPgosResult& Result, const FClientFasLoginInfo* Data)
{
    UE_LOG(LogTemp, Log, TEXT("On FAS login callback."));
}

对于TFunction类型的回调实现，如果需要在回调中访问UObject的数据，为了确保生命周期安全，建议使用PgosSDKCpp.h中提供的CreateWeakCallback来创建一个绑定到UObject的lambda表达式。以上述FAS登录TFunction API调用为例，代码可以按如下方式组织：

#include "PgosSDKCpp.h"

// using the  TFunction callback.
void SomeUObjectClass::CallWithLambda()
{
    auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();
    if (spFAS)
    {
        FString MyAccount = TEXT("SomeAccountString");
        auto CallbackFunction = IPgosSDKCpp::CreateWeakCallback<FClientFasLoginInfo>
            (this, [](const FPgosResult& Ret, const FClientFasLoginInfo* LoginInfo) {
                UE_LOG(LogTemp, Log, TEXT("On FAS login callback."));
            });
        spFAS->Login(MyAccount, CallbackFunction);
    }
}

1.3 监听事件

PgosSDK 会在特定情况下触发相应的事件，例如玩家会话状态变更、玩家加入/离开组队等。这些事件在游戏线程中执行。开发者可以监听这些事件并采取相应的操作（如更新UI）。以 PlayerAuth 服务的 OnPlayerSessionChanged 事件为例，您可以参考以下代码来监听 PgosSDK 事件：

#include "PgosSDKCpp.h"

void SomeUObjectClass::MonitorPlayerSessionEvt()
{
    auto Auth = IPgosSDKCpp::Get().GetClientPlayerAuthAPI();
    if (Auth) {
        Auth->OnPlayerSessionChanged().AddUObject(this, &SomeUObjectClass::OnPlayerSessionChanged);
    }
}

void SomeUObjectClass::OnPlayerSessionChanged(const FClientPlayerSessionChangedEvt& event) {
    UE_LOG(LogTemp, Log, TEXT("pgos player session has changed."));
}

❗注意：为了避免遗漏事件，建议在事件触发前就开始监控。

2. 调用 PgosSDK 蓝图 API

所有的 BlueprintCallable 函数都放置在 "PGOS" 分类下：

您可以根据想要实现的功能轻松找到所需的函数，如果已经知道函数名称，也可以直接通过搜索栏查找。PgosSDK中的大多数API都是异步操作，使用方式类似。您可以按照以下步骤创建蓝图：

2.1 发起API调用

在可执行操作对话框中，搜索特定API的名称或在PGOS类别中找到它，选择后将其添加到蓝图中。
根据需要填写输入引脚的内容。
选择成功时（或失败时）引脚并将其拖动到空白位置。在可执行操作对话框中，搜索您想要执行的下一步操作，例如打印字符串，然后选择它以添加到蓝图中。
选择Error输出引脚并将其拖动到空白位置。在弹出的对话框中，选择Break PgosResult，您可以在失败时引脚的下一个操作中查看错误详情。
可能还会有另一个引脚，它是异步API的数据响应。您可以在成功时引脚的下一个操作中使用它。

2.2 监控事件

如果您需要监控事件：

在可执行动作对话框中搜索Get Pgos Client Event Dispatcher并选择它以添加到蓝图中。
选择Return Value的输出引脚并将其拖动到空白位置。在弹出的对话框中，搜索关键词Bind，您将看到可以绑定或解绑的事件。选择您需要的事件将其添加到蓝图中。

完成后，您的蓝图应该类似于下图：

❗ 注意
异步 API 回调和触发事件都在游戏线程中执行，因此不建议在其中执行任何耗时操作。

1. 调用 PgosSDK C++ API​

1.1 获取服务接口​

1.2 调用API​

1.3 监听事件​

2. 调用 PgosSDK 蓝图 API​

2.1 发起API调用​

2.2 监控事件​