Construct 2 Dictionary Tutorial

Construct 2 dictionaries store data in key-value pairs. Think of a Dictionary as a table with one column for names of values and one column for values associated with the names. If you want a value from a Construct 2 Dictionary, you request the value associated with a key (keys are sometimes called “names”). You can also have Construct 2 get all the key-value pairs, one pair at a time, and do things with them, such as print out high scores.

If you know one or more programming languages, this may all sound familiar to you. The Construct 2 Dictionary is similar to associative arrays and hashmaps found in other languages.

Names (called keys) cannot be duplicated in a Construct 2 Dictionary. For example, if you have a Dictionary of high scores, you could store key-value pairs of Doug-35, Bob-99, and John-42, but you could not have two scores named “John” in the list. For example, Doug-35, John-42, and John-33 would not work because the key “John” is used twice.

Note to Advanced Programmers: You can get around the no-duplicate-keys limitation by having multiple minion-style Construct 2 Dictionaries keyed off values from a master Dictionary. It would work like foreign keys in relational databases. I won’t go into that now, but remember, having no duplicate keys in a table is not a limiting factor. It just requires some extra planning and work.

Dictionaries are extremely useful for storing lots of related data. Dictionary use is easy for old-time programmers, but dictionaries need explaining in more detail for newer Construct 2 game developers. So, here’s a Construct 2 project example that shows the basics of Construct 2 Dictionary use.

New Empty Construct 2 Project
Select a new empty Construct 2 project.

Here is the *.capx in a zip for this tutorial.

Start by creating a new empty Construct 2 project. Do this by clicking “File” in the upper-lefthand corner of the Construct 2 window and then selecting “New”. After you select “New”, a dialog opens with lots of different types of project options. Select “New Empty Project”.

Construct 2 Project Tab
See everything in your project in a tree structure in the Construct 2 project tab.

You should be able to see the project properties on the left side of the Construct 2 window. If not, select the “Project” tab on the right side of the screen, and select the “New project” root node in the Projects area. If you have renamed your project to something other than “New project” then select your project’s name in that area.

Construct 2 Project Properties
The project properties allow you to modify all the project specific properties, such as window size.

In the project properties, you can change the author, email, or name of your project. However, I just want to copy the window size and then set the layout size to that same size.

Construct 2 Layout Properties
Set the layout size to match the screen size in the layout properties.

Go ahead and copy the window size x and y values, then click anywhere on the layout. That brings up the layout properties. Paste the values in the layout size, and your layout will now match your window in size.

Just to make life easier, I set “show grid” and “snap to grid” in the View ribbon.

Right click on the layout and select “Insert new object”. Select “Text” under “General”, then size the Text to look like the following.

Adding Text in Construct 2 Layout
After inserting the Text object, don’t forget to resize it to your liking.

Set the Text property of “Text” to be empty by deleting the word “Text”. (Yeah. Lot’s of “Text” in that sentence, but the goal is just to have an empty box for text without the word “Text” being displayed.

Next add five button objects using the same method. I created five distinct button objects instead of creating one and copying it. Lay them out as in the image below.

Add Construct 2 Buttons
Insert these buttons across the top of your layout.

Rename the button objects as follows.

Rename the Button Objects
Make your buttons match these.

We need one more object—the all-important Dictionary. Insert a new object into your layout. Select Dictionary from the Data & Storage section of the Insert New Object dialog. Change the name of the inserted object to “ScoreDictionary”.

Insert a Construct 2 Dictionary Object
The Construct 2 Dictionary is similar to Hashmaps and associative arrays in other programming languages.

Also, add the Function object from General. Your Construct 2 objects should look something like the following.

Construct 2 Objects
You should have all of these Construct 2 objects.

Now we’ll set up the event sheet.

Add a new event. Select System in the Add event dialog.

Add System Event
Construct 2’s system event.

Then select the condition of “On start of layout”.

On Start of Layout
Setting On start of layout condition to a System event in Construct 2.

Select “Add action” and select the “ScoreDictionary”. This allows you to select “Add key”

Add Construct 2 Dictionary Key
Add key action via the Dictionary object that you want to add the key to.

Set the parameters in ScoreDictionary as follows. We want something to print in the Text when the program runs. This way we’ll already have something in the Construct 2 Dictionary.

Setting "Doug" Dictionary Key
Setting the “Doug” Dictionary key in Construct 2.

This is where we need the Construct 2 function call. We’ll need a function to call to update the scores list. We could include the exact same actions every time a button is pushed to update the scores display, but calling one function to do the work is easier, and I’m all about easier code.

Click “Add event” in the event sheet, and create a function. Select “On function” and create a function named “displayScoreDictionary”. Add a sub-condition using the ScoreDictionary object and “For each key”. For your actions, set the ScoresText to “” in the first function condition and then append to the ScoresText from the key-values of each score in the dictionary in the sub-condition. Clearing the scores happens once, and printing a key-value pair from the dictionary happens once per key-value pair, until all the key-value pairs are printed to the screen.

The append text looks like the following.

Set Scores Text
The & is used to concatenate text in Construct 2. Also, grab the key and value using CurrentKey and CurrentValue properties of the Dictionary object.

Now that we have a display function, add an action of Function and call “displayScoreDictionary” to the original System “On start of layout”.

The event sheet entries should now look like this. Note that we do not want Set text to “” to happen on every key-name stored in the database. That would result in only the last key-value pair of data getting printed to Text. We just want the old list of scores deleted once.

Add Key and For Each Key
These three Construct 2 events show the use of add key and for each key with Dictionaries.

The important thing to learn here is that a Dictionary event can have a condition of “For each key”. The action is performed on a per-key basis, meaning that the keys are each cycled through, and the action is performed over-and-over until you run out of keys. To access the current key or current value, the dictionary name is used, followed by a dot and “CurrentKey” or “CurrentValue”. In this case, Construct 2 uses the dictionary name of “ScoreDictionary”.

Run the application and you will see that the current key-value of Doug and 35 are stored in the Dictionary at start of the layout. This value is displayed in the ScoresText. We need to hook up the buttons now, to get a little more practice working with our Construct 2 dictionary.

Add the events for the two score adding buttons. The add key actions for the ScoreDictionary is just the same as the original one you set up for Doug. The two new Construct 2 events should look like the following.

Construct 2 Button Events
Use the “On click” condition of the Construct 2 buttons to trigger the desired Dictionary actions and the display refresh.

You’ll notice quickly when displaying more names with scores that the names and scores are all being displayed on one line without any linebreaks. The quick fix is to add a newline to the append action in the display displayScoreDictionary function. It should now read something like:

ScoreDictionary.CurrentKey & “…..” & ScoreDictionary.CurrentValue & newline

Set up the final three buttons to work with the following events.

Last Three Dictionary Actions
Examples of Construct 2’s Dictionary delete key, set key, and dictionary clear actions.

The DeleteDougButton deletes the key of “Doug” from the dictionary. (Good-bye Doug!) This also removes the value associated with Doug. Don’t forget to call the “displayScoreDictionary” to update the ScoresText.

The ClearAllScoresButton calls Clear on the Construct 2 Dictionary. Clear removes every key-value pair from the dictionary. Then we update the call displayScoreDictionary function, again.

The ChangeScoresButton implementation is a bit different. The additional ScoreDictionary “For each key” condition is added to make sure we can cycle through all the keys and change their values to 0.

That is all there is to basic use of dictionaries with Construct 2.