Store in-game configurations in game records

Last updated on July 10, 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 or news information
Players' collective game data such as their clan, area or map

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

On the Admin Portal sidebar, go to Progression & Inventory > Cloud Save menu and select Game Records.
On the "Cloud Save" page, open the Game Records tab and click on the Create Game Record button. The "Add Record" form appears.
Fill in the required information:
- Fill in 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.
- Add the data you want to store in JSON format.
Click Add. The new record is added to the records 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 data. You store the data by creating a new game record using the following function.

Create a game record via a client

Unreal
Unity

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

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:125,y:256,z:125"},
  {"NPC2", "x:115,y:225,z:120"}
};

cloudSave.SaveGameRecord(key, recordRequest, result =>
{
    if (result.IsError)
    {
        // Do something if SaveGameRecord has an error
        Debug.Log($"Error SaveGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if SaveGameRecord is successful
});

Create a game record via a server

Unreal
Unity

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

ServerCloudSave serverCloudSave = AccelByteSDK.GetServerRegistry().GetApi().GetCloudSave();

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:125,y:256,z:125"},
  {"NPC2", "x:115,y:225,z:120"}
};

RecordSetBy setBy = RecordSetBy.CLIENT;

serverCloudSave.SaveGameRecord(key, recordRequest, setBy, result =>
{
    if (result.IsError)
    {
        // Do something if SaveGameRecord has an error
        Debug.Log($"Error SaveGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if SaveGameRecord is successful
});

Create a temporary game record via a server

Unreal

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.

You can retrieve a game record using the following function:

Retrieve a game record via a client

Unreal
Unity

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

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

string key = "inGameNews";
cloudSave.GetGameRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if GetGameRecord has an error
        Debug.Log($"Error GetGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if GetGameRecord is successful
});

Retrieve a game record via a server

Unreal
Unity

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

ServerCloudSave serverCloudSave = AccelByteSDK.GetServerRegistry().GetApi().GetCloudSave();

string key = "inGameNews";

serverCloudSave.GetGameRecords(key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteUserRecord has an error
        Debug.Log($"Error DeleteUserRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if DeleteUserRecord is successful
});

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:

On the Admin Portal sidebar, go to Progression & Inventory > Cloud Save > Game Records.
On the "Game Records" page, depending on the record type, open the JSON or the Binary tab. From the list, find and view the record you want to update.
On the details page of the record, click on the pencil or edit icon of the fields or sections to update the content.
Save your changes.

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

Unreal
Unity

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

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
    {"NPC1", "x:100,y:256,z:125"},
    {"NPC2", "x:100,y:225,z:120"}
};

cloudSave.ReplaceGameRecord(key, recordRequest, result =>
{
    if (result.IsError)
    {
        // Do something if ReplaceGameRecord has an error
        Debug.Log($"Error ReplaceGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if ReplaceGameRecord is successful
});

Modify a game record via a server

Unreal
Unity

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

ServerCloudSave serverCloudSave = AccelByteSDK.GetServerRegistry().GetApi().GetCloudSave();

string key = "map-data";

Dictionary<string, object> recordRequest = new Dictionary<string, object>
{
  {"NPC1", "x:100,y:256,z:125"},
  {"NPC2", "x:100,y:225,z:120"}
};

RecordSetBy setBy = RecordSetBy.CLIENT;

serverCloudSave.ReplaceGameRecord(key, recordRequest, setBy, result =>
{
    if (result.IsError)
    {
        // Do something if ReplaceGameRecord has an error
        Debug.Log($"Error ReplaceGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if ReplaceGameRecord is successful
});

Modify a game record to become temporary via a Server

Unreal

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 these steps:

On the Admin Portal sidebar, go to Progression & Inventory > Cloud Save > Game Records.
On the "Game Records" page, depending on the record type, open the JSON or the Binary tab. From the list, find the record you want to delete and click on its Delete button under the Action menu.
Click Delete on the confirmation message.

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

Unreal
Unity

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

CloudSave cloudSave = AccelByteSDK.GetClientRegistry().GetApi().GetCloudSave();

string key = "map-data";

cloudSave.DeleteGameRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteGameRecord has an error
        Debug.Log($"Error DeleteGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");

    }
    
    // Do something if DeleteGameRecord is successful
});

Delete a game record via a server

Unreal
Unity

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

ServerCloudSave serverCloudSave = AccelByteSDK.GetServerRegistry().GetApi().GetCloudSave();

string key = "map-data";

serverCloudSave.DeleteGameRecord(key, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteGameRecord has an error
        Debug.Log($"Error DeleteGameRecord, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if DeleteGameRecord is successful
});

Overview​

Goals​

Prerequisites​

Store data in a new game record​

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

Store data in new game records with the SDK​

Create a game record via a client​

Create a game record via a server​

Create a temporary game record via a server​

Display game records data​

Retrieve a game record via a client​

Retrieve a game record via a server​

Modify game records data​

Modify game records via the Admin Portal​

Modify new game records with the SDK​

Modify a game record via a client​

Modify a game record via a server​

Modify a game record to become temporary via a Server​

Delete game record data​

Delete new game records via the Admin Portal​

Delete new game records via the SDK​

Delete a game record via a client​

Delete a game record via a server​

On this page