WebStorage

Note: as of r206, WebStorage is deprecated in favour of the new Local Storage plugin. This manual entry remains for any old projects which are still using WebStorage, but new projects should use Local Storage instead.

The WebStorage object can store data locally on the user's computer between sessions. For example, it can be used to store the last save checkpoint, and restore the player's progress if they come back the next day. (Note: if you want a full-state save and load feature, see How to make savegames.)

Note that despite the name the WebStorage object does not use online storage. Since data is stored locally to the user's computer, it will work when offline, as well as for storing data in offline exporters such as NW.js or mobile wrappers like CocoonJS.

WebStorage does not store in the browser cache. If the user opts to empty the browser cache, WebStorage data remains intact. However if the user opts to clear all their cookies or offline website data, WebStorage will be cleared. This is intentional by the browser makers so users have a way to free up disk space and prevent websites storing information about them. This usually has other side-effects like logging the user out of every website they were previously logged in to. On platforms that are not a web browser with an address bar (like Windows 8 apps, Cordova or NW.js) the storage is permanent and there is no option for the user to clear it.

Storage per domain

The WebStorage object associates all stored data with the current domain. For example, all games running on scirra.com share the same data, but games running on facebook.com use a different set of data and cannot access any data saved from scirra.com.

Most browsers implement a maximum size of the data that can be stored with WebStorage - 5mb is a common limit. If you exceed the limit, the WebStorage's On quota exceeded trigger runs.

Local vs. Session storage

The WebStorage object allows data to be stored in two places: Local storage and Session storage.

Local storage is permanent (until the user clears their cache). If the user comes back the next day, local storage still has the saved data.

Session storage only lasts with the current browser session. If the user comes back the next day, session storage is empty again.

Using WebStorage

The WebStorage object uses a very simple storage model: values are stored under named keys, similar to how the Dictionary object works. For example, the value 100 could be stored for the key score with the action Set local value "score" to 100. Similarly the value John can be stored for the key name. Then the expression WebStorage.LocalValue("score") returns "100" (as a string) and WebStorage.LocalValue("name") returns "John", and these values persist between sessions. (If session storage was used instead, the values would only last as long as the browser session.)

Note WebStorage only stores strings. If you set a key to a number like 100, when you retrieve it back it will be a string. To convert it back, use the system expression int, e.g. int(WebStorage.LocalValue("score")).

WebStorage conditions

Compare key value (as number)

Compare the value of a given key to a number. Since the WebStorage object only stores values as strings, this condition will first convert the value to a number, then compare it. If the key value is not a number, the condition will always be false.

Compare key value (as text)

Compare the value of a given key to a string. Note the WebStorage object only stores values as strings, so if a number was previously stored it will have been converted to a string already.

Local/session key exists

Check whether a value has been saved for a key in either local or session storage.

On quota exceeded

Most browsers limit the amount of data that can be stored in WebStorage to about 5mb. If this limit is exceeded, or the user declines to increase the storage limit if the browser prompts them, then On quota exceeded runs. You will not be able to add any new keys, or set existing keys to longer values, until you delete some other values or clear the storage entirely.

WebStorage actions

Clear local/session storage

Reset either local or session storage to empty for this domain, with no data stored.

Remove local/session value

Delete a key (and its associated value) from local or session storage. It will no longer exist after this action.

Set local/session value

Store a value (string or number) for a key in local or session storage. If the key does not exist it is created, otherwise its value is simply updated.

Load JSON

Load local storage keys and values from JSON data. The Dictionary object's JSON format is compatible, so data can be interchanged between Dictionary and WebStorage, but note WebStorage only stores strings (so all numbers will be converted to strings when loading). If Mode is Set, local storage is first cleared, then the data loaded. If Mode is Merge, the keys in the JSON data are added or overwritten to the existing keys in storage.

WebStorage expressions

LocalAt

SessionAt

Return the value at a zero-based index if all the keys in storage are listed in alphabetical order. Useful for listing all stored data.

LocalCount

SessionCount

Return the number of keys that exist in storage for this domain.

LocalKeyAt

SessionKeyAt

Return the key name at a zero-based index if all the keys in storage are listed in alphabetical order. Useful for listing all stored data.

LocalValue

SessionValue

Retrieve the value stored for a key in storage. If the key does not exist this returns an empty string.

AsJSON

Return the entire contents of local storage in JSON format. The result can also be loaded in to the Dictionary object, but note WebStorage only stores strings so all result values in the Dictionary object will also be strings.