Store in-game configurations in game records

Last updated on April 4, 2024

Overview​

The Cloud Save service enables you to store your game data, for your game use case, in JSON format. The game records stored are for global title uses that are accessible, and in some cases are editable, by the players. Storing, for example:

  • A game seasonal UI theme configuration
  • Game event/news information
  • Players' collective game data (e.g. clan area/map), etc.

In this guide, you will learn how to utilize a game record to store your game data, display it within the game client, and modify it according to your game use case.

Goals​

  • Provide an understanding and overview of game records
  • Provide an understanding on how to game data in game records
  • Provide an understanding on how to display game records
  • Provide an understanding on how to modify game records
  • Provide an understanding on how to delete game records
  • Explain how to utilize game records using the AccelByte SDK

Prerequisites​

You will need access to:

  • The Admin Portal
  • The AccelByte Unreal or Unity SDK, including the permissions:
    • Client ID
    • Client Secret
  • The AccelByte Cloud Save API documentation

Store data in a new game record​

Store data in a new game record via the Admin Portal​

Creating game records via the admin portal is suitable if you want to store data that does not need to be modified by the game client, and will only be retrieved by the game client. For example: Seasonal UI theme configuration, Event/News Information, etc.

To create a game record, follow the steps below:

  1. In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Game Records.

  2. On the Cloud Save page, click the Create Game Record button.

  3. The Add Record form will appear. Fill in the required fields.

    • Input the Game Record Key using the appropriate format. You can use this as your record title and it can be used as an identifier to retrieve the record from the SDK later.
    • You can also add extra validation to make sure that only the game server, or game client, can update the records by selecting your choice in the Write Permission section. See Write Permission for a full list of the available options.
    • Input your data you want to store, in JSON format, under the JSON Configuration.

  4. When you have finished, click the Add button, and the new record will be added to the list.

Store data in new game records with the SDK​

This is suitable if you need game records that are dynamically created after some actions are triggered from the game client. As an example, storing public customizable map�s data. You store the data by creating a new game record using the following function.

Create a game record via a client​

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = FString("map-data");

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=125;Y=256;Z=125"));
RecordRequest->SetStringField(FString("npc2"), FString("X=115,Y=225,Z=120"));
                
ApiClient->CloudSave.SaveGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if SaveGameRecord has is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if SaveGameRecord has an error
    }));

Create a game record via a server​

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("map-data");

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=125;Y=256;Z=125"));
RecordRequest->SetStringField(FString("npc2"), FString("X=115,Y=225,Z=120"));

ServerApiClient->ServerCloudSave.SaveGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if SaveGameRecord has is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if SaveGameRecord has an error
    }));

Create a temporary game record via a server​

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("map-data");

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=125;Y=256;Z=125"));
RecordRequest->SetStringField(FString("npc2"), FString("X=115,Y=225,Z=120"));

FTTLConfig TTLConfig{};
TTLConfig.Action = EAccelByteTTLConfigAction::DELETE_RECORD;
TTLConfig.Expires_At = FDateTime::UtcNow() + FTimespan(0, 0, 5); // Will delete this record in the next five seconds   

ServerApiClient->ServerCloudSave.SaveGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if SaveGameRecord has is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if SaveGameRecord has an error
    })
    , TTLConfig);

Display game records data​

The game records that are stored and created both from your Admin Portal, or game client, can be retrieved by all players. With that data, you can do whatever you want to support your game use cases. As examples, use the data to replace the UI for seasonal themes, display the data to show the updated news or events, etc.

You can retrieve a game record using the following function:

Retrieve a game record via a client​

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = FString("inGameNews");        

ApiClient->CloudSave.GetGameRecord(Key
    , THandler<FAccelByteModelsGameRecord>::CreateLambda([](const FAccelByteModelsGameRecord& Result)
    {
        // Do something if GetGameRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if GetGameRecord has an error
    }));

Retrieve a game record via a server​

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("inGameNews");               

ServerApiClient->ServerCloudSave.GetGameRecord(Key
    , THandler<FAccelByteModelsGameRecord>::CreateLambda([](const FAccelByteModelsGameRecord& Result)
    {
        // Do something if GetGameRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if GetGameRecord has an error
    }));

Modify game records data​

Modify game records via the Admin Portal​

Modifying a game record from your Admin Portal is suitable if you want to take manual action to adjust the data. As examples, fixing data, auditing, etc. To update a game record, follow the steps below:

  1. In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Game Records.

  2. On the Cloud Save page, choose the record you want to update, and select View in the Action menu.

  3. In the Record Detail, go to the JSON Configuration section and click Edit.

  4. Input the updated information, and click Save to complete.

Modify new game records with the SDK​

This is suitable if your game requires updating the game records data from the game client. The data you store will be replaced with new data, by using the following function:

Modify a game record via a client​

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = "map-data";

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=100;Y=256;Z=125"));
RecordRequest->SetStringField(FString("npc2"), FString("X=100,Y=225,Z=120"));

ApiClient->CloudSave.ReplaceGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceGameRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something if ReplaceGameRecord has an error
    }));

Modify a game record via a server​

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "map-data";

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=100;Y=256;Z=125"));
RecordRequest->SetStringField(FString("npc2"), FString("X=100,Y=225,Z=120"));

ServerApiClient->ServerCloudSave.ReplaceGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceGameRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something if ReplaceGameRecord has an error
    }));

Modify a game record to become temporary via a Server​

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = "map-data";

TSharedPtr<FJsonObject> RecordRequest = MakeShareable(new FJsonObject);
RecordRequest->SetStringField(FString("npc1"), FString("X=100;Y=256;Z=125"));
RecordRequest->SetStringField(FString("npc2"), FString("X=100,Y=225,Z=120"));

FTTLConfig TTLConfig{};
TTLConfig.Action = EAccelByteTTLConfigAction::DELETE_RECORD;
TTLConfig.Expires_At = FDateTime::UtcNow() + FTimespan(0, 0, 5); // Will delete this record in the next five seconds

ServerApiClient->ServerCloudSave.ReplaceGameRecord(Key
    , *RecordRequest
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if ReplaceGameRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something if ReplaceGameRecord has an error
    })
    , TTLConfig);

Delete game record data​

Delete new game records via the Admin Portal​

To delete a game record, follow the steps below:

  1. In the Game Management section of the Admin Portal, go to the Cloud Save menu and select Game Records.

  2. On the Cloud Save page, select the record you want to delete from the list and click the Delete button under the Action menu.

  3. The Delete Game Record confirmation modal will appear. Click Delete to continue.

Delete new game records via the SDK​

If your game requires you to delete game records from the SDK side, you can delete it using the following function.

Delete a game record via a client​

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString Key = FString("map-data");              

ApiClient->CloudSave.DeleteGameRecord(Key
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if DeleteGameRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if DeleteGameRecord has an error
    }));

Delete a game record via a server​

FServerApiClientPtr ServerApiClient = FMultiRegistry::GetServerApiClient();

FString Key = FString("map-data");

ServerApiClient->ServerCloudSave.DeleteGameRecord(Key
    , FVoidHandler::CreateLambda([]()
    {
        // Do something if DeleteGameRecord is successful
    })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Do something if DeleteGameRecord has an error
    }));
Last updated on

On this page