Introduction to Cloud Save

Last updated on October 24, 2024

Overview

AccelByte Cloud Save is a service that provides storage for arbitrary game data, in JSON format or binary format. The game data can be updated, replaced, retrieved and deleted from your game client, game server or Admin Portal.

By utilizing Cloud Save you can store:

• game theme configurations
• the event configuration
• game info/news
• player save game data
• player character attributes
• player game settings

The Cloud Save service supports many different storage scenarios, giving you multiple options for your games storage needs.

In this section, you will learn about the key concepts of the Cloud Save service, supported features, and best practices to utilize the service.

Key Concepts

To make your integration as seamless as possible, it is important to understand some of the key concepts that are used in the design of this service.

Cloud Save types

Game data can be store in two different types of Cloud Save:

• JSON: stores game data in human-readable characters or in a textual format, which can be easily understood by human or computer. This typically requires additional space for formatting and escaping characters.

  tip

  We recommend limiting the size of each record to 1 MB or less for optimal performance. If your game requires more, we recommend storing records in Binary Cloud Save instead.

• Binary: stores game data in executable files which requires specialized systems or tools to interpret or manipulate. This is typically more space-efficient because the data is stored in a more compact form. Binary Cloud Save supports file types such as jpeg, jpg, png, bmp, gif, mp3, webp, and bin.

  tip

  We recommend limiting the size of each record to 100 MB or less for optimal performance.

Access levels

There are two access levels for data stored in Cloud Save:

• Player Accessible Records: refers to game data that players use. This data can be accessed and edited by players. For example, player-saved game data.
• Admin Records: refers to sensitive game data that game server uses. This data can only be accessed and edited by admins and is not visible to players. For example, randomized variables in gameplay, such as chances of finding items.

Record Type

Game data can be stored in one of two types of record:

1. Game Records: used to store game data for global title uses (at the Game Namespace level). For example, theme configuration, event configuration, game info/news, and similar global data.
2. Player Records: used to store game data for a specific player's uses (at the user level). For example, player save game data, player character customization, and player game settings.

Record Key

You can use a Record Key as an identifier or title for your records. Game and Player record keys should be unique.

Metadata

Metadata allows game clients, or game servers, to define the behavior of the Cloud Save records. Record metadata is defined in the request body with the field name __META. Metadata is assigned with a default value, if not otherwise defined. Game clients support a limited range of Cloud Save records, but the game servers are able to define everything available in __META.

Player Accessible Record Write Permission (set_by)

This metadata indicates which party can modify the record. This metadata is available only in admin endpoints. The possible values are:

• Server: the record can only be modified by the server.
• Client: the record can be modified by either the client or the server. This is the default value.

Player Accessible Record Read Permission (is_public)

This metadata indicates whether the record is public or not, and is available in both admin and public endpoints. The possible values are:

• Public: the record is accessible to other players. The value displayed in the is_public field is True.
• Private: the record is not accessible to other players. The value displayed in the is_public field is False.

Custom Validation

Cloud Save allows you to have a validation logic that you can customize according to your needs. The custom validation will override default validation logic when creating/updating or retrieving the cloud save records.

Cloud Save Service Extra Validation

This section explains how the Cloud Save service record can be created, updated, and deleted, both from the game client and game server. You can choose to add extra validation using the set_by and is_public fields explained in the previous section. Understanding the extra validation below will make it easier to understand behaviors and how to best utilize the Cloud Save service.

Base on Read Permission (is_public)

	Admin	Record Owner player	Other players
Public	Read	Read	Read
Private	Read	Read	n/a

Base on Write Permission (set_by)

Game Records	Player	Admin
Server	n/a	Modify
Client	Modify	Modify

Player Records	Admin	Record Owner player	Other players
Public	Modify	n/a	n/a
Private	Modify	Modify	n/a

Admin Records

Other than player accessible records, Cloud Save service supports you to store data restrictedly from the players in Admin Records. The table below will give you more understanding about the admin record access permission.

Record Type	Public Endpoints	Admin Endpoints
Admin Player Records	-	Read, Modify
Admin Game Records	-	Read, Modify

Best Practices

The best scenario to use the Cloud Save service is when you need to store additional information for your game, that can be retrieved or updated from the game client/server.

You can utilize public player records in Cloud Save if you have a use case that requires you to store specific player information.

You might not need to use Cloud Save if you require to store only numerical values, perhaps needed for further integration. This is because you can utilize the values in Statistics, and these values can be integrated with the Leaderboard, Achievements, Matchmaking, among other services.