Skip to main content

Implement Multiple Registries

Last updated on June 23, 2025
danger

Multiple Registries for AGS Unreal Engine SDK has been wrapped under AccelByte Instance!
AccelByte OnlineSubsytem is not affected.
Please refer to [the migration guide].

Introduction

The Multiple Registries is a feature designed to support multiple local users logging in to the same game instance in AccelByte Gaming Services (AGS). Having multiple registries allows game developers to create games that can support local multiplayer. It stores player information and progression for each player independently based on the account linked with the game controller.

Multiple registries are containers of API clients that store logged-in player information and acts as a player when calling AGS APIs.

The current SDK has limitations as it used a singleton class to represent a player, thus only allowing one account to log in at any given time within the same game instance. To overcome these limitations, we created a new class, ApiClient to represent a player. It serves the same purpose and uses the same entry point to access AGS APIs. Game developers will need to use this new class and the multiple registries will maintain this class.

The ApiClient infrastructure offers the following advantages:

  • Reduces singleton and static class usage.
  • Easier to manage for developers, who can easily create and delete ApiClient instances.
  • More extensible as the ApiClient is used as the entry point to create custom API classes.

After you have implemented the ApiClient class, the API calls operate in a similar manner to the previous SDK's. These SDK changes will also impact game server implementation (which was previously mixed between client and server implementation). A new class called ServerApiClient has therefore been created to focus on managing game server-related APIs.

Prerequisites

Implement Multiple Registries using Client SDKs

  1. Include the following library at the top of your class before implementing multiple registries.

    AGS Unreal Engine SDK migration [guide].

    DEPRECATED. Please refer to migration [guide].
    #include "Core/AccelByteMultiRegistry.h"

    The ApiClient represents a player in your game and holds the additional APIs needed to create and send requests to the backend services.

  2. Define each player in this class using a unique key for each player so that each player can be isolated by calling GetApiClient().

    AccelByteInstance

      //⚠️ Deprecated method to obtain the ApiClient using MultiRegistry
    //// Define User A
    //FApiClientPtr ApiClientA = FMultiRegistry::GetApiClient(TEXT("0"));
    //// Define User B
    //FApiClientPtr ApiClientB = FMultiRegistry::GetApiClient(TEXT("1"));

    The latest method to obtain the ApiClient using AccelByteInstance
    // Define User A
    auto ApiClientA = AccelByteInstancePtr->GetApiClient(TEXT("0"));
    // Define User B
    auto ApiClientB = AccelByteInstancePtr->GetApiClient(TEXT("1"));
    NOTES
    • For the unique key, apply the following rules:
      • Unreal Engine: use FString with the default as default.
      • Unreal (OSS): use int with no default value.
      • Unity: use string with the default as default.
    • Make sure to use the same key if you want to call the function in other classes.
  3. As this is a gateway, you must authenticate each player before they can access any AGS service. To do this, set up an AGS login method. You can use any login method that AGS allows, such as the username method in the example below:

    AccelByteInstance

    //⚠️ Deprecated method to obtain the ApiClient using MultiRegistry
    //FApiClientPtr ApiClientA = FMultiRegistry::GetApiClient(TEXT("0"));
    //FApiClientPtr ApiClientB = FMultiRegistry::GetApiClient(TEXT("1"));

    Latest method to obtain ApiClient using AccelByteInstance
    auto ApiClientA = AccelByteInstancePtr->GetApiClient(TEXT("0"));
    auto ApiClientB = AccelByteInstancePtr->GetApiClient(TEXT("1"));

    // Login with username
    ApiClientA->User.LoginWithUsername(
    TEXT("user+a@example.com"),
    TEXT("Password321"),
    FVoidHandler::CreateWeakLambda(this, [this]()
    {
    UE_LOG(LogTemp, Log, TEXT("Login User A successful"));
    }), FCustomErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage, const FJsonObject& ErrorObject)
    {
    UE_LOG(LogTemp, Error, TEXT("Login User A Failed : %d, %s"), ErrorCode, *ErrorMessage);
    }));

    ApiClientB->User.LoginWithUsername(
    TEXT("user+b@example.com"),
    TEXT("Password321"),
    FVoidHandler::CreateWeakLambda(this, [this]()
    {
    UE_LOG(LogTemp, Log, TEXT("Login User B successful"));
    }), FCustomErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage, const FJsonObject& ErrorObject)
    {
    UE_LOG(LogTemp, Error, TEXT("Login User B Failed : %d, %s"), ErrorCode, *ErrorMessage);
    }));

What's next

Learn how to migrate your game from a singleton-based registry to multiple registries.