LocalStorage in Construct 2

Construct 2 LocalStorage saves variables in a similar way to the Construct 2 Dictionary. (See my Construct 2 Dictionary Tutorial if you are not familiar with Dictionaries.) The two big differences between LocalStorage and Dictionary are that LocalStorage doesn’t go away when the web browser restarts, and LocalStorage is asynchronous, not synchronous like Dictionary.

If that didn’t all make perfect sense to you, don’t worry. That’s the whole point of this tutorial. This tutorial teaches the basics of using Construct 2’s LocalStorage to store information when the game is not running. We’ll make a simple app that uses LocalStorage to store variables when the web browser is not running.

Construct 2 LocalStorage Example
LocalStorage saves variables when the web browser or even the computer are not running.

Synchronous and asynchronous are usually new terms to non-coders. Since Construct 2 markets to non-coders, lots of Construct 2 users don’t know them. I’ll explain synchronous and asynchronous.

In programming, synchronous means that you wait for something to finish before doing something else. In the case of the Construct 2 Dictionary, you get the value of a key and don’t do anything else until that value is returned by the Dictionary.

Synchronous Call
The Construct 2 Dictionary is synchronous.

Asynchronous means, you request something like a value of a variable and then do something else until that variable’s value comes back. In other words, asking for variable’s value from an asynchronous LocalStorage doesn’t get you the variable’s value. Instead, LocalStorage brushes you off and says, “I’ll get back to you.” When LocalStorage completes an asynchronous task, it sends an event your way to tell you what it found.

Asynchronous Call
The Construct 2 LocalStorage is Asynchronous.

I expect those descriptions of synchronous and asynchronous might not be enough, so let’s give a few real world examples.

At the theatre, when you are about to go in, someone requests your ticket. You hand them your ticket and you get to go in. This is a synchronous exchange. They ask for something and you immediately give it to them.

If you send your friend an email asking them to come over this weekend, then on Saturday, they show up, that is an asynchronous event. You send the email, and then get on with your week. When they ring the doorbell on Saturday, they are creating an event for you to act on.

That hopefully clears up the difference between synchronous and asynchronous. It’s time to create the example. To save time, I have zipped up a *.capx of the example code. I still recommend creating this example from scratch, but if you get stuck, you can refer to the *.capx.

LocalStorageExample.capx_.zip

Construct 2 LocalStorage Example

Start a new empty Construct 2 project. Copy the window size and set the layout to the same size. We really don’t need a big layout for this example.

In the layout, insert two Buttons, a Text and a TextBox. Arrange them to look like the following image. Change their properties to suit your taste.

Construct 2 Layout
This is the Layout for our LocalStorage example.

Now that you have two Buttons, a Text and a TextBox, you are ready to add a LocalStorage. Insert it the same way that you inserted the other items in the layout. Don’t panic when nothing appears to happen. LocalStorage isn’t visible in the layout, and by default won’t show up in the Objects area. However, when you go to “Add event” in the event sheet, you will now have the option of using a LocalStorage.

Construct 2 Objects
This is the full list of objects used for the Construct 2 LocalStorage example.

I changed the filter on the objects so that I could see the LocalStorage in my list of objects. Don’t panic if yours is not visible.

All that’s left is the events. This is the list. You can easily create a duplicate list in your project by matching icons and text. Never fear! I will explain what is happening in this list.

LocalStorage Event Sheet
The LocalStorage event sheet for our Construct 2 example project.

The key to understanding this event sheet is that Construct 2 LocalStorage is asynchronous. Every LocalStorage action has a matching event that you can use as a condition. Every request to LocalStorage generates an event rather than giving you an answer right away. Remember LocalStorage always says, “I’ll get back to you.” It never gives you something exactly when you ask for it, though it is typically so fast your users won’t notice the difference.

I named my variable “someValue”. No. Not very imaginative, but it will work for this example.

The first event in our event sheet is a System On start of layout. We check if “someValue” exists, and then regardless of the result set the DisplayText to read, “No value set in local storage.”

Don’t get confused here. We don’t yet know if the variable exists. We’re just setting the default text for DisplayText. Look in the LocalStorage Events group at LocalStorage On item “someValue” exists. If the value exists, the action for changing the DisplayText happens, and then we make another request from the LocalStorage. We do the action, Get item “someValue”.

LocalStorage’s action of Get item is paired up with the event of On item “someValue” get. When local storage gets back to us about the value of “someValue”, then that event gets invoked and the action appends the DisplayText with the value of “someValue”.

Our SetButton sets the value in LocalStorage when the button is clicked. LocalStorage’s Set item “someValue” to ValueTextBox.Text just loads LocalStorage with the value we’ve typed into the ValueTextBox. In this case, we catch the even sent when the LocalStorage is updated in the LocalStorage On item “someValue” set and then update the display and request another get item event.

We also have a button for clearing out LocalStorage. Construct provides an event to notify us when clearing storage is complete, but we don’t care about this event, so we don’t have an event for clearing LocalStorage in our LocalStorage Events group.

LocalStorage Scope

Variables stored in LocalStorage are available when reopening your game (or other app). They don’t go away unless your user tells the browser to make them go away, or you remove/clear them from LocalStorage.

However, variables in Construct 2 LocalStorage cannot be shared between users on different computers or even the same user using two different web browsers. Keep that in mind when designing games.