AccelByte Instance Usage in AGS Unreal Engine SDK

Last updated on June 23, 2025

Overview

The old implementation of the AGS Unreal Engine SDK relied heavily to a singleton pattern.
The singleton pattern is deprecated.

• The deprecation affects FRegistry & FMultiRegistry classes.
• The deprecation does not affect ApiClient and its usage.
• The singleton is replaced by AccelByteInstance, a self-contained instance.

If developer uses those FRegistry & FMultiRegistry classes, they need to change the way to access the ApiClient/API class (i.e. User, Lobby, Chat, etc.) and needs to migrate their implementation to use AccelByteInstance.

Obtaining ApiClient from AccelByte Instance

Developer has two choice to obtain the AccelByte Instance:

1. [Recommended] Rely to the AccelByte OnlineSubystem (OSS) instance
2. Create AccelByte Instance and manage it by themselves

1. Rely to AccelByte OSS

AccelByte OSS already has an AccelByteInstance already.
If developer is implementing AccelByte OSS, they can proceed to obtain the ApiClient for its player num without need to access AccelByte Instance directly

    #include "OnlineSubsystemAccelByteDefines.h"
    ...
    auto ABSubsystem = IOnlineSubsystem::Get(ACCELBYTE_SUBSYSTEM);
    if(ABSubsystem == nullptr)
    {
        return;
    }

    FOnlineSubsystemAccelByte* AccelByteOnlineSubsystemPtr = static_cast<FOnlineSubsystemAccelByte*>(ABSubsystem);
    if(AccelByteOnlineSubsystemPtr == nullptr)
    {
        return;
    }

    // For game client
    auto ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient(YOUR_PLAYER_LOCAL_NUM);
    auto LobbyGameClient = ApiClient->GetLobbyApi().Pin();
    LobbyGameClient->RequestFriend(...)

    // For game server
    FAccelByteInstancePtr AccelByteInstancePtr = AccelByteOnlineSubsystemPtr->GetAccelByteInstance().Pin();
    auto ServerApiClient = AccelByteInstancePtr->GetServerApiClient();
    ServerApiClient->ServerInventory.GetInventories(...);

Else, if developer is only using AccelByte SDK without AccelByte OSS, they can obtain it this way:

    #include "OnlineSubsystemAccelByteDefines.h"
    ...
    auto ABSubsystem = IOnlineSubsystem::Get(ACCELBYTE_SUBSYSTEM);
    if(ABSubsystem == nullptr)
    {
        return;
    }

    FOnlineSubsystemAccelByte* AccelByteOnlineSubsystemPtr = static_cast<FOnlineSubsystemAccelByte*>(ABSubsystem);
    if(AccelByteOnlineSubsystemPtr == nullptr)
    {
        return;
    }

    // For game client
    const FString ApiClientId = TEXT("YOUR_CUSTOM_IDENTIFIER");
    FAccelByteInstancePtr AccelByteInstancePtr = AccelByteOnlineSubsystemPtr->GetAccelByteInstance().Pin();
    auto ApiClient = AccelByteInstancePtr->GetApiClient(ApiClientId);
    auto LobbyGameClient = ApiClient->GetLobbyApi().Pin();
    LobbyGameClient->RequestFriend(...)

    // For game server
    FAccelByteInstancePtr AccelByteInstancePtr = AccelByteOnlineSubsystemPtr->GetAccelByteInstance().Pin();
    auto ServerApiClient = AccelByteInstancePtr->GetServerApiClient();
    ServerApiClient->ServerInventory.GetInventories(...);

2. Create & Manage AccelByte Instance manually

If developer doesn't want to use the AccelByte OnlineSubsystem (OSS) plugin, developer can obtain & manage AccelByteInstance by themselves.
Ensure the lifetime of the AccelByteInstancePtr.

    #include "AccelByteUe4SdkModule.h"
    ...
    auto AccelByteInstancePtr = IAccelByteUe4SdkModuleInterface::Get().CreateAccelByteInstance();
    if (!AccelByteInstancePtr.IsValid())
    {
        return;
    }

Migration from FMultiRegistry ApiClient to AccelByte Instance's ApiClient

To start migrating, we need to follow the guide above to obtain the ApiClient from the AccelByteInstance.
Then refer this example to compare the migration.

Before

    const FString ApiClientId = TEXT("YOUR_CUSTOM_API_CLIENT");
    auto ApiClient = FMultiRegistry::GetApiClient(ApiClientId);
    ApiClient->User.LoginWithDeviceId(...);

After

    int32 LocalUserNum = 0;//example
    const FString ApiClientId = TEXT("YOUR_CUSTOM_API_CLIENT");

    // If developer is implementing AccelByte OSS
    auto ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient(LocalUserNum);
    // else, if developer only use AccelByte SDK
    auto ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient(ApiClientId);

    auto User = ApiClient->GetUserApi().Pin();
    if (!User.IsValid())
    {
        return;
    }
    User->LoginWithDeviceId(...);

    // For Game Server
    auto ServerApiClient = AccelByteOnlineSubsystemPtr->GetServerApiClient();