SaveSystem - stingray.SaveSystem namespace reference - Stingray Lua API Reference

stingray.SaveSystem namespace reference
Error codes | Status codes | PlayStation 4 | Windows, iOS, and Android
expand all | collapse all

Description

The interface to access the save and load functionality.

Note that this object is a singleton (there is only one SaveSystem), so you do not need to pass any SaveSystem object to the functions. All the functions operate on the SaveSystem singleton.

You can save the following data types:

Asynchronous operations return a SaveToken object that is used to fetch progress during the operation. This object must be closed to free the memory that is used during the save. Otherwise, the game will eventually run out of memory.

On Windows and iOS, you must set up a root directory in which the save system will read and write files. You do this in the settings.ini file for your project, in the platform-specific save_dir setting. For example:

win32 = {
    // ... other windows settings go here
    save_dir = "%APPDATA%\\MyCompany\\MyProjectName\\Saves"
}
iOS = {
    // ... other iOS settings go here
    save_dir = "%SAVEDATA%/MyProjectName"
}

See the Stingray engine settings.ini file reference for more information.

Error codes

Error codes that may be returned by the save_error_result() and load_error_result() functions.

BROKEN : integer

Loading failed because the connection was broken.

NOT_FOUND : integer

Loading failed because the data could not be found.

OTHER : integer

The save or load failed for another undefined reason.
stingray.SaveSystem.save_error_result()

Status codes

Status codes that may be returned by the status() function.

COMPLETED : integer

The operation has completed successfully.
stingray.SaveSystem.load_error_result()
stingray.SaveSystem.save_error_result()
stingray.SaveSystem.status()

STARTED : integer

The operation has started, but not yet finished.

UNKNOWN : integer

Either the specified ID was never created, or it was already freed.

PlayStation 4

The interface described here is specific to the PlayStation 4.

Parameters

id :

integer

The ID of the operation to free.

Returns
This function does not return any values.

You must call free() on all IDs that you get back from stingray.SaveSystem.save() and stingray.SaveSystem.load(), whether or not the operation completed successfully. Otherwise, the save system eventually runs out of memory.

Parameters

info :

save_system_ps4_info

A table that provides detailed information about the game and the data to load. The fields are the same as in the table for stingray.SaveSystem.save() except that title, subtitle, and details are not used, and no file data is needed.

Returns

integer

An ID for the operation, which you can pass to status().

You can use stingray.SaveSystem.status() to track the progress of the operation.When the operation has finished, you must call stingray.SaveSystem.free() to free the memory used by the operation.

Sample usage:

id = SaveSystem.load
{
    user_id = user,
    name = "save2",
    files = {
                {path = "a"},
                {path = "b"},
                {path = "c/d"},
    },
}
Parameters

id :

integer

The ID of the operation to query.

Returns

integer

An error constant that indicates the last error to occur during the load.

Parameters

id :

integer

The ID of the operation to query.

Returns

save_system_ps4_info_files[]

A list of files loaded, and the data loaded from those files.

The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

The result is in the same format as provided to stingray.SaveSystem.save(): a table with paths and values. For example:

{
    {path = "a", data = 3},
    {path = "b", data = "Niklas"},
    {path = "c/d", data = {1,2,3, {ha = "ho"}}},
}
Parameters

info :

save_system_ps4_info

A table that provides detailed information about the game and the data to save.

Returns

integer

An ID for the operation, which you can pass to status().

You can use stingray.SaveSystem.status() to track the progress of the operation.When the operation has finished, you must call stingray.SaveSystem.free() to free the memory used by the operation.

Sample usage:

id = SaveSystem.save
{
    user_id = user
    name = "save2",
    title = "A saved game",
    subtitle = "This is the game saved",
    icon = "images/icon0"
    details = "It was a wonderful game",
    files = {
        {path = "a", data = 3},
        {path = "b", data = "Niklas"},
        {path = "c/d", data = {1,2,3, {ha = "ho"}}},
    },
}
Parameters

id :

integer

The ID of the operation to query.

Returns

integer

An error constant that indicates the last error to occur during the save.

integer?

If the error type is SaveSystem.OUT_OF_SPACE, then this is the required amount of data that the user needs to free (use this when calling stingray.SaveSystemDialog.open()). Otherwise, this value will be nil.

The ? notation indicates that this type is optional: there may be zero or one instances of it.
Parameters

id :

integer

The ID of the operation to query.

Returns

integer

A status constant that indicates the status of the operation.

If this returns SaveSystem.ERROR, you can find out more detail about the error by calling save_error_result() or load_error_result().

Windows, iOS, and Android

The interface described here is specific to Windows, Mac OS X, iOS, and Android platforms.

Parameters

filename :

string

The name of the file that contains the data you want to load. You do not need to specify a directory. Only a-z, 0-9, and _ characters are allowed in the filename.

Returns

stingray.SaveToken

A token that you can query by calling progress().

The file is silently read.

Note that you must call stingray.SaveSystem.close() on the returned token in order to release the memory allocated by the operation.

Parameters

filename :

string

The name of the file that will contain the saved data. You do not need to specify a directory. Only a-z, 0-9, and _ characters are allowed in the filename. The file is silently overwritten if it exists.

data :

table

Generally, this is a table that contains the data that needs to be saved.

Returns

stingray.SaveToken

A token that you can query by calling progress().

Note that you must call stingray.SaveSystem.close() on the returned token in order to release the memory allocated by the operation.

Parameters

token :

stingray.SaveToken

The SaveToken you want to close.

Returns
This function does not return any values.

This frees the memory used by the operation.

Parameters
This function does not accept any parameters.
Returns

boolean

Returns true if the SaveSystem interface is available for use, or false otherwise.

Parameters

token :

stingray.SaveToken

The token that identifies the operation you want to query.

Returns

save_system_progress

A table that contains information about the progress of the save or load operation, as well as the data loaded (if any).

Please send us your comment about this page