Storage API Reference
The storage API lives in the castle.storage module. The API lets your game use a database that Castle provides to save game state. The data is saved "in the cloud," so it is shared across computers. You do not need to perform any set-up for your game to have access to this database, your games can use these APIs out-of-the-box!
There are two kinds of storage:
- Global storage: This storage is shared across all users playing a game. Example data that makes sense to store here includes high scores that you want all users to see or shared world state that you want to persist across runs of the game.
- User storage: This storage is private to each user. Example data that makes sense to store here includes the level a user reached in a single-player game with many levels, or the attributes of a character a user developed in a role-playing game.
In both cases, the storage is separate per-game, so that one game can't accidentally overwrite another game's data.
Keys and values
The databases are "key-value" stores, where you associate a value with a key then use that key again later to retrieve that value. The keys are always strings. The values must be of one of the following Lua types:
- table, where the elements of the table are of valid types and the table has no circular references. Metatables are ignored.
For in-depth information on value-type encoding, please refer to the manual for Lua CJSON
, which the API uses internally to save values into the database. In short, Lua tables with 'plain data' and no circular references will always work.
All of the functions below perform network requests to access the database and take time to complete. So, calling them directly from love.update or love.draw would block the processing or drawing of your game while the network request finished. Instead, you should use network.async to run a block of code asynchronously from your game events. For example, to save the high-score when a new score is made:
-- ... Other game code ...
-- When a new score is created at the variable 'score'
local lastHighScore = castle.storage.getGlobal('highscore')
if not lastHighScore or lastHighScore < score then
-- ... More other game code ...
For these reasons it makes sense to not call these functions every frame, and instead only once in a while (say at the start of your game, when the user tries to save some data, when an important event such as a new highscore occurs, etc.).
Global storage functions
Save value at key (string) in global storage. value must have a value type as described above, or it can be nil. If it is nil, this key is deleted from global storage.
Get the value stored at key (string) in global storage. Returns nil if there was no value saved at key or if it was deleted.
User storage functions
Save value at key (string) in user storage. value must have a value type as described above, or it can be nil. If it is nil, this key is deleted from user storage.
Get the value stored at key (string) in user storage. Returns nil if there was no value saved at key or if it was deleted.