Storage

The Puls platform enables data synchronization across all devices using two available modules in our Runtime. Data synchronization is optimized for speed and delivery through a standardized API, ensuring the best web gaming experience for players.

Data synchronization is limited to a maximum data size of 1MB. This should suffice for most use cases but must be considered when deploying a game on Puls Games.

Puls Memory

Puls Memory is a high-speed read/write memory storage module that uses the LocalStorage API. It is accessible via window.puls.memory. To use Puls Memory, initialize it by calling the open() method.

// Opening Puls Memory
window.puls.memory.open(): Promise<void>

// Get Item
window.puls.memory.getItem(key: string): string

// Set Item
window.puls.memory.setItem(key: string, value: string): void

// Remove Item
window.puls.memory.removeItem(key: string): void

// Clear
window.puls.memory.clear(): void

Puls Storage

Puls Storage is a lower-level module accessible via window.puls.storage. It is optimized for high-speed network data retrieval, taking less than 80ms. However, this storage is not suitable for frequent data access or manipulation.

Puls Storage implements the "Last Write Wins" strategy, allowing you to load the latest data version by calling load() or store a player's state with save(). To compare the local data version with the remote version, you can use a synchronization token. Remote data is stored exclusively in string format.

Recommendation: To use this module efficiently, implement data loading at the start of the game to fetch user data and update it either periodically or after specific game events, such as game completion or level achievement.

Loading Game State

To load the remote game state of the current signed-in player, call load(). The remote data is returned in the data field of a StorageResponse as a string value for further processing.

// Loading game state
// ===
//
// This function loads game state of the current logged player.
// The remote data will be returned as a string value that
// can be further proccessed.
// 'syncToken' is optional.
type StorageResponse = {
     sync: SynchronizationToken // string
     data: StorageData // string
}
window.puls.storage.load([syncToken: string]): Promise<

Saving Game State

To store a player's game state, call the save() method with string data that adheres to the maximum allowed size.

// Saving game state
// ===
// 
// This function stores game state of the current logged player.
// The response includes a new synchronization token that might
// be stored locally for further comparation.
window.puls.storage.save(data: string): Promise<string

Errors

If an issue occurs while saving or loading data, a PulsStorageError is thrown with descriptive error messages.

- `NO_DATA`: The Puls Storage does not have any data.
- `INVALID_DATA`: The data has an invalid format.
- `SESSION_EXPIRED`: The game session has expired.
- `MAX_SIZE`: The data exceeds the maximum allowed size limit.
- `RATE_LIMIT`: The Puls Storage is accessed too often.
- `UNKNOWN`: An unregistered error occurred

Synchronization (Optional)

You can compare local and remote data using a synchronization token, which is returned each time data is stored in Puls Storage. Store this token in local storage to compare data versions and ensure the local state is not newer than the remote state, preventing unintended overwrites (e.g., a higher score).

When using a synchronization token during loading, two outcomes are possible:

1) The local data, represented by the synchronization token, is newer than the data in Puls Storage. In this case, a StorageResponse is returned with the same synchronization token provided and an empty data field, indicating that the local data is newer.

2) The remote data is newer or the same as the local data. A StorageResponse is returned with the synchronization token and data in string format. The synchronization token is always included in the response.

If the local storage contains a newer version of the game state, call the save() function to update the remote data to match the local version.