Blueprint Maps | Unreal Engine 4.27 Documentation

The Blueprint Application Programming Interface (API) in Unreal Engine 4 (UE4) has a Map container type. Much like Arrays and Sets, Blueprint Maps have a variety of uses when developing a game. If you're unfamiliar with the term "container"; think of a storage box, where you label items and place them inside of the box for immediate (or later) use. If you've used Arrays to store and work with collections of items, you've already started using Blueprint containers in UE4. For example, when using Arrays to store items for later use, the item's label is its place in the array. Maps are similar to Arrays in that they both use a label to indicate where the item is located in the container, however, labels for Maps are different from those used for Arrays. When using Arrays, the label is the item's sequential index in the container, whereas, when using Maps, the label is a key that's associated with the item in the container. Having the ability to associate items in a container with their respective keys, enables developers to efficiently lookup and retrieve items with the use of the keys, and so harness Maps in creative ways.

As you read through this page, you'll learn how to create and edit Blueprint Maps. You'll also learn about the properties of Maps, which are being included to help you get the most out of using Maps in your game projects.

For illustrative purposes, we're using a Blank Project (with the highlighted settings) to show you how to create and edit Blueprint Maps.

Click for full images.

Creating Maps

To create a new Blueprint Map, follow these steps.

If you don't have a Blueprint Class to work from, go ahead and Add a new Blueprint Class to your project.

Click for full image.
Now, select Actor from the list of classes being shown in the Pick Parent Class menu.
After naming your Actor class, go ahead and open the newly created Actor class by double-clicking on the Actor, which is located inside of the Content Browser.

Click for full image.
To begin editing the Actor's Blueprint script, select the Event Graph tab.

Click for full image.
With the Actor's Event Graph open, hover your mouse cursor over the Variables submenu to reveal the + Variable button.

Click for full image.
Now, create a new String variable, naming it MyStringIntegerMap.

Click for full image.

Although the variable's name may seem a bit pedantic, it's worthwhile to note that the variable name, specifically MyStringIntegerMap, informs you that your Map will have a String-type key associated with an Integer-type value.
Currently, MyStringIntegerMap is a single String variable. To begin turning MyStringIntegerMap into a Map container, click on the Variable Type button, which is on the right side of the Variable Type label inside of the Actor's Details panel.

Click for full image.
At this point, a drop down menu will appear, showing you four container options. Select the following option to convert MyStringIntegerMap into a Blueprint Map:

Go ahead and inspect the Variable Type for MyStringIntegerMap, verifying that the Map's key-type is a String, and that the value-type is an Integer.

Editing Maps

Before you can edit a newly created Map, you'll need to compile the Blueprint encapsulating the Map variable container.

Click for full image.

To edit MyStringIntegerMap, click the Blueprint's Compile button.

Click for full image.
After compiling the Blueprint, you'll notice that the Map's Default Value (located in the Details panel) shows that MyStringIntegerMap is empty.

Click for full image.
To add a new key-value pair to MyStringIntegerMap, click the Add (+) button, located next to 0 Map elements in the Default Value menu of the Details panel.
Go ahead and click the Add (+) button once again.

Unreal Editor will emit a warning if you try to add a key to the Blueprint Map before updating a new key-value pair's default key.
Add three key-value pairs to MyStringIntegerMap, matching them with the following image:
Now, add one more key-value pair, naming the key Banana.

Unreal Editor will emit a warning if you try to add a duplicate key into a Blueprint Map. Although duplicate values are allowed, you cannot have duplicate keys.
With the aforementioned warning in mind, go ahead and name the fourth key Date, setting its value to 2.

Excellent work! You've just created a new Blueprint Map, having added and edited four key-value pairs.

Container Properties

If you want to get started with using Blueprint Map containers in UE4, please refer to the following property list.

Keys in a Map must be unique.
All keys in a Map must be defined (initialized).
Currently, only single key-value pairs are supported in Blueprint Maps.
Adding, removing, and finding values, using their associated keys in a Map, are fast operations.
Currently, Map values are immutable, which means that they cannot be modified after they have been created.
Although key-types may differ from value-types, all keys and values in a Map are homogeneous (of the same type). In other words, if a particular Map's key is specified as a String-type with its value specified as an Integer-type, then all subsequent keys will be Strings, and all subsequent values will be Integers.

Now that you know how to create and edit Map containers in Blueprints, check out the Blueprint Map Nodes reference guide to learn more about the Blueprint Map Node Interface.