Local storage

This module is used to save and load local storage under a specific name. It uses the GenericStorage class to store data. Users can have multiple storages with different names. The storages are typically used to save game data.

To use this module, include the following line in your project file:

require engine.local_storage_core // or require engine.core

Limits

save_storage checks the limits before writing anything, so a refused save keeps the previously saved data intact:

  • All storages of a project hold up to 1 MB of serialized data in total; a save that would go over it is refused with SaveStorageResult.FileSizeLimitExceeded. The old data of the storage being saved does not count.

  • A project holds up to 20 storages; creating one more is refused with SaveStorageResult.LimitExceeded. Saving under an already used name is always allowed; remove_storage frees a name.

Enumerations

SaveStorageResult

The result of saving a storage.

Values:

  • UnableToSave = 0 - The storage could not be saved. Issue with the storage or the file system.

  • Success = 1 - The storage was saved successfully.

  • FileSizeLimitExceeded = 2 - The storage was not saved because it would make the total size of the game saves exceed the limit (1mb).

  • LimitExceeded = 3 - The storage was not saved because it exceeded the global files limit (20 files).

Functions

load_storage(name: string): GenericStorage

Loads the storage with the given name and returns the data.

Arguments:

  • name : string - the name of the storage to load

Returns:

  • GenericStorage - the loaded data as a GenericStorage object, storage will be empty if the data could not be loaded

Usage example:

var storage = load_storage("myStorage")
let score = get_or(storage, "score", 0)
load_storage(name: string; blk: block<(var data:GenericStorage#):void>): bool

Loads the storage with the given name and passes the data to the provided block. Preferred over the other version of load_storage because it cleans up the memory after the block is done executing.

Arguments:

  • name : string - the name of the storage to load

  • blk : block<(data: GenericStorage#):void> - the block to receive the loaded data

Returns:

  • bool - true if the data was loaded successfully, false otherwise

Usage example:

load_storage("myStorage") $(var storage : GenericStorage#) {
    let score = get_or(storage, "score", 0)
}
load_storage(name: string; value: auto(T)&): bool

Loads a struct, array or table value saved by save_storage. Fields are matched by name, so fields absent in the stored form keep their current value.

Arguments:

  • name : string - the name of the storage to load

  • value : auto(T)& - the variable to load into

Returns:

  • bool - true if the value was loaded successfully, false otherwise

Usage example:

var settings = Settings()
load_storage("settings", settings)
remove_storage(name: string): bool

Removes the storage with the given name.

Arguments:

  • name : string implicit - the name of the storage to remove

Returns:

  • bool - true if the storage was removed successfully, false otherwise

Usage example:

remove_storage("myStorage")
save_storage(data: GenericStorage|GenericStorage#; name: string = ""): SaveStorageResult

Saves the given data to local storage with an optional name.

Arguments:
Returns:

Usage example:

var storage : GenericStorage
set(storage, "score", score)
save_storage(storage, "myStorage")
save_storage(value: auto(T); name: string = ""): SaveStorageResult

Saves a struct, array or table value to local storage with an optional name, without a GenericStorage. The value is stored as DataBlock text, so floats keep about 6 significant digits.

Arguments:

  • value : auto(T) - the value to be saved

  • name : string - the name of the storage (optional)

Returns:

Usage example:

save_storage(settings, "settings")