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 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

Rely to AccelByte OSS

AccelByte OSS already has a single AccelByteInstance.
Therefore, developer can use the existing instance conveniently.

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

    FOnlineSubsystemAccelByte* CastABSubsystem = static_cast<FOnlineSubsystemAccelByte*>(ABSubsystem);
    if(CastABSubsystem == nullptr)
    {
        return;
    }
    
    FAccelByteInstancePtr AccelByteInstancePtr = CastABSubsystem->GetAccelByteInstance().Pin();

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

Access the API class

Continuation of the AccelByteInstance snippets above:

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

    // For game server
    auto ServerApiClient = AccelByteInstancePtr->GetServerApiClient();
    
    // Example of making an API call
    LobbyGameClient->RequestFriend(...)
    ServerApiClient->ServerInventory.GetInventories(...);

Migration from FRegistry-FMultiRegistry Singleton to AccelByte Instance

To start migrating, we need to follow the guide above to obtain 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

    const FString ApiClientId = TEXT("YOUR_CUSTOM_API_CLIENT");

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