storage¶

Simple key/value storage.

Saving happens in the background, so your project can keep running smoothly. If you need to make sure your changes are saved right away (for example, before quitting or switching levels), call storage:flush().

Storage uses string keys (like “highScore”), and the value you save must be either boolean, number, string, or a table containing only those kinds of values. If you store nil for a given key, then that key/value pair will be removed from storage.

You can read and write values directly using property-style access (storage.highScore = 100 and print(storage.highScore)).

The default storage is per-project. A device-wide store is available under storage.global.

Basic Usage

-- Default project storage
storage.highScore = 9001
print(storage.highScore or 0)

-- Missing key uses default
print(storage.missing or 42)

-- Remove a key
storage.temp = nil

storage.has(key)¶

Checks if a key exists.

Parameters:: key (string) – Key to check
Returns:: True if the key exists, false otherwise
Return type:: boolean

if storage:has("playerName") then
    print("Player name saved")
end

storage.delete(key)¶

Removes a key.

Parameters:: key (string) – Key to remove

storage:delete("tutorialSeen")

storage.keys()¶

Returns a sorted array of all keys in the store.

Returns:: Sorted list of keys
Return type:: table

for _, key in ipairs(storage:keys()) do
    print(key)
end

storage.clear()¶

Removes all keys from the store.

storage:clear()

storage.flush()¶

Writes any pending changes synchronously.

storage.level = 3
storage:flush()

storage.asset()¶

Returns the underlying asset key for the storage file.

Returns:: Asset key used for the store file
Return type:: assetKey

print(storage:asset())

storage.namespace(prefix)¶

Returns a view of the store that prefixes all keys with prefix. A . is added automatically if missing.

Parameters:: prefix (string) – Namespace prefix (for example, "prefs")
Returns:: Namespaced storage view
Return type:: table

local prefs = storage:namespace("prefs")
prefs.audioMuted = true -- stored as "prefs.audioMuted"
print(prefs.audioMuted)

storage.project: storage¶: Default project-scoped storage (stored under asset). This is the same store used by the top-level storage functions.

storage.global: storage¶: Default device-wide storage (stored under asset.documents).

storage.projectStore(name)¶

Convenience wrapper for storage(name, "project").

Parameters:: name (string) – Store name
Returns:: Storage instance
Return type:: table

storage.globalStore(name)¶

Convenience wrapper for storage(name, "global").

Parameters:: name (string) – Store name
Returns:: Storage instance
Return type:: table

storage(name[, scope])

Returns a named store. Stores are cached by name and scope, so repeated calls return the same store instance.

Parameters:

name (string) – Store name (used to derive the file name)
scope (string) – Store scope ("project" or "global")

Returns:

Storage instance

Return type:

table

local settings = storage("settings")
local globalPrefs = storage("prefs", "global")

Usage Patterns

-- Separate storage for different systems
local prefs = storage:namespace("prefs")
local stats = storage:namespace("stats")

prefs.musicEnabled = true
stats.gamesPlayed = 12

-- Project vs global
local projectStore = storage.project
local globalStore = storage.global

projectStore.level = 3
globalStore.unlocked = { "sword", "shield" }

Notes

Keys must be strings
Values must be (nil, boolean, number, string, table)
Storage saves in the background, call storage:flush() if you need to write storage immediately (for example, before quitting)