# Local Storage in SceneScript
SceneScript allows you to store up to 100 KB of data per wallpaper. This can be useful if you want to track certain data points across system restarts or just wallpaper changes.
# Persisting Data with Local Storage
Local storage is handled via the ILocalStorage class. You can access this feature via the localStorage
global variable which is available anywhere in SceneScript.
# Storage Location: Global or Per Screen?
First, you need to decide if your data is related to the specific screen that the wallpaper is running on or if it is something that is valid across all potential screens a user might have.
In our example, we want to store the high score of a game-themed wallpaper. The high score is valid across all screens, so we want to store it globally using the LOCATION_GLOBAL
constant.
An opposite example would be if we wanted to keep track of the position of some wallpaper element on the screen. In this case, we would instead store this value per-screen using LOCATION_SCREEN
. This is also the default state, so if you do not specify this option, wallpaper settings will be stored per screen.
# Storing Data
To actually store our data, we simply access the global localStorage
object anywhere in our code. Use the localStorage.set()
function to store your data:
localStorage.set('highscore', userScore, localStorage.LOCATION_GLOBAL);
The first 'highscore'
parameter is the key under which we store our data. Name it appropriately for your use-case, you will need this later to retrieve the data again. The userScore
variable contains the data we want to store, this would need to be replaced by whatever you want to store. Additionally, we set the location to LOCATION_GLOBAL
because our high score is valid across all screens, see the section above for a lengthier explanation.
# Loading Data
While you can load data anywhere in your code, we highly recommend to do this only once in the init event and assign the loaded data to a variable that you can use throughout your code. The init
event is triggered whenever the wallpaper is loaded, allowing you to load the data from storage before any other functions run.
To retrieve data, use the localStorage.get()
function and re-use the same storage key and storage location that you have used while setting the data. In our example, we will re-use highscore
and localStorage.LOCATION_GLOBAL
and assign it to a global variable that we are calling currentHighscore
.
Additionally, you may want to set a default value in case no value was found in the local storage. In our example, we want to set a default value of 0 if no data is found. We accomplish this by adding a logical "or" after the function: || 0
.
var currentHighscore;
/**
* @param {Boolean} value
*/
export function init(value) {
currentHighscore = localStorage.get('highscore', localStorage.LOCATION_GLOBAL) || 0;
}