Unreal Engine 5 Documentation has been moved to the Epic Developer Community

Working with Maps

Learn how to work with Maps in Blueprints.

Choose your operating system:

Windows

macOS

Linux

workingWithMaps_topicBanner.png

After Blueprint Arrays , there's a good reason why Blueprint Maps are so popular. They support efficient look-ups and retrievals of values with the use of associated keys. At the end of this guide, you'll get some experience creating and editing Maps in the Blueprint scripting environment, querying and displaying items, and performing basic operations on Blueprint Maps in Unreal Engine 4 (UE4).

1. Required Setup

Before you can start working with Blueprint Maps, you'll have to set up your project to display the container's contents.

  1. Create a new Project using the Games > First Person template, using the following settings:

    • Blueprint enabled

    • Maximum Quality enabled

    • Desktop/Console enabled

    • With Starter Content enabled

  2. Name your project, ExampleMapProject .

  3. Double-click the Blueprint folder from the project's Content Browser .

    Step1_2.png

    Click image for full view.

  4. From the Content Browser , click the Add New button, then select the Blueprint Class , which is located under the Create Basic Asset pop-up menu.

    Step1_3.png

    Click image for full view.

  5. After the Pick Parent Class menu opens, click the All Classes arrow to search for the TextRender Actor Blueprint Class.

    Step1_4.png

  6. Enter TexRenderActor in the Search Bar , selecting the TextRenderActor Blueprint Class before clicking the Select button.

    Step1_5.png

  7. At this point, you should have a new TextRender Actor located in your project's Content Browser . Go ahead and name the new Actor DisplayMap .

    Step1_6.png

    Click image for full view.

  8. Now, drag the DisplayMap TextRender Actor into Unreal Editor's Perspective (3D) Viewport .

    Step1_7.png

    Click image for full view.

  9. With the DisplayMap TextRender Actor selected, click the + Add Component button (located in the Details panel), and enter Box Collision into the Search Bar .

    Step1_8.png

    Click image for full view.

  10. After adding the Box Collision Component to the TextRender Actor, name the new Component, Trigger Box .

    Step1_9.png

    Click image for full view.

  11. Now, select the TextRender Component to view the Actor's Transform settings in the Details panel.

    Step1_10.png

    Click image for full view.

  12. Update the DisplayMap Actor's Transform settings to reflect the following values:

    Step1_11.png

  13. Now, change the DisplayMap Actor's Horizontal Alignment to be Center aligned (rather than Left aligned, which is the default Horizontal Alignment value).

    Step1_12.png

  14. Currently, the Trigger Box Component is Hidden in Game . Go ahead and clear the Hidden in Game check box (located in the Rendering menu of the Details panel) so that you can view the Box Collision Component in-game.

    Step1_13.png

    Having the ability to view Box Collision Components in-game is a great way to debug any potential issues with the underlying logic driving a triggered event.

  15. If you enter PIE (or Play in Editor) mode, you'll notice that your projectiles will have a collision response to the DisplayMap collision box. Currently, we only want the DisplayMap collision response to trigger an event that allows us to display the contents of your Map containers. To do this, go to the Collision menu (located in the Details panel), click the Collision Presets drop-down list box, and select the Custom... option.

    Step1_14.png

  16. Finally, update the Collision Presets to reflect the following values:

    Step1_15.png

Section Result

Step1_EndResult.png

Click image for full view.

By now, you've created a new project and you have also set up a new TextRender Actor, which will display the contents of a Blueprint Map container that you'll create, edit, and display in the next step.

2. Creating and Displaying a Blueprint Map

Now that you've set up a TextRender Actor in your newly created project, you're ready to create a Blueprint Map container, the contents of which you'll display in-game.

  1. From your project's Content Browser , double-click the DisplayMap TextRender Actor to open its Blueprint Event Graph . Step2_1.png

  2. If you see the following screen, go ahead and click the Open Full Blueprint Editor link to get started.

    Step2_2.png

    Click for full image.

  3. You should see the DisplayMap TextRender Actor Blueprint Event Graph , where you'll be able to add a Blueprint Map and its display logic.

    Step2_3.png

    Click for full image.

    If you don't see the aforementioned screen, click the Event Graph tab to open the Actor's Blueprint Event Graph Editor.

    Step2_3Note.png

  4. Now is the time to create a Blueprint Map container, where you'll store some key-value pairs that you'll display later on. To create a new Blueprint Map, click the + Add New button (located in the My Blueprint panel) and select Variable from the drop-down list.
    Step2_4.png

  5. Name your new variable, Instruction Map .
    Step2_5.png

  6. Click the variable's pin type button, which is located next to the variable's name.
    Step2_6.png

  7. Now, select the Integer variable type from the drop-down list.
    Step2_7.png

  8. Click the variable's container type button, which is located next to the Variable Type drop-down list in the Details panel.
    Step2_8.png

  9. Select the Map container type from the drop-down list.
    Step2_9.png

  10. Now, it's time to define your Map's key-value property types. Currently, the key is an Integer type, which is the desired property type. The value type, however, isn't a String variable type, though. To change the value from being an Integer to being a String , go ahead and click on the value property type drop down list.
    Step2_10.png

  11. Select String from the drop down list.
    Step2_11.png

  12. At this point, you have a key-value pair that is of Integer and String types (respectively). Also, the Blueprint Graph reminds you that you need to compile the Blueprint in order to the define the items that you're going to store inside of the container. Go ahead and click the Compile button to get started.

    Step2_12.png

    Click for full image.

    Compiling the Blueprint replaces the container's Default Value message with an interface, enabling you to populate your container with key-value pairs, wherein the Map's keys are Integers and the values are Strings.

  13. If you already haven't done so, go ahead and click the Save button to save all of the work that you've done so far.

    Step2_13.png

    Click for full image.

  14. Click the + (Adds Element) button (located in the Default Value menu of the Details panel) to add a new key-value pair to the newly defined Instruction Map container.

    Step2_14.png

  15. Define your container's new key-value pair, defining the key as 1 , and defining the value as WASD to run .

    Step2_15.png

  16. Repeat the previous two steps, making sure to fill your Instruction Map container with the following key-value pairs:

    Step2_16.png

Scripting the Logic

Before you can display the contents of your newly created Blueprint Map, you'll need to write the necessary logic.

  1. Now that you've defined your container, go ahead and drag the Instruction Map variable into the Blueprint Event Graph.

    Step2_17.png

    Click for full image.

  2. Select Get from the Instruction Map drop-down list.

    Step2_18.png

    Click for full image.

  3. Drag off the Instruction Map node and add the Find node from the Map Utilities interface.

    Step2_19.png

    Click for full image.

    There are several ways to get values from a Map. For this part of the tutorial, we'll go ahead and increment an integer key to display the associated values contained in the Instruction Map .

  4. With the aforementioned note in mind, go ahead and click the + Add New button, selecting Variable from the drop-down list.

    Step2_20.png

  5. Makes sure to set the variable's type to an Integer type, giving it the name, Key . Right-click to the pin type to change it to a single value instead of a map if necessary.

    Step2_21.png

  6. After you've declared and defined your new Integer variable, drag Key into the Blueprint Event Graph, and select Get from the drop-down list.

    Step2_22.png

    Click for full image.

  7. Drag off the Key node, search for, and add the IncrementInt node.

    Step2_23.png

    Click for full image.

  8. Now, go ahead and connect the IncrementInt node to the Find node.

    Step2_24.png

    Click for full image.

    For the purposes of this tutorial, you're going to use a time function to increment the Key variable.

  9. Drag off the Event Tick node, search for, and add the Delay node.

    Step2_25.png

    Click for full image.

  10. After you've set the delay duration to 2 seconds, connect the Delay node to the IncrementInt node.

    Step2_26.png

    Click for full image.

  11. Go ahead and drag off the Event BeginPlay node, search for, and connect to the Branch node.

    Step2_27.png

    Click for full image.

  12. Connect the IncrementInt node to the Branch node.

    Step2_28.png

    Click for full image.

  13. Now, connect the Boolean return value belonging to the Find node to the Branch node's Condition pin.

    Step2_29.png

    Click for full image.

    If the Find node successfully locates the item in the Map, the node returns true. Otherwise, if the Find node returns false, there is no item contained in the Map that uses the provided key.

  14. Drag off the Branch node's True pin, search for, and connect to the Set Text(TextRender) node.

    Step2_30.png

    Click for full image.

    This branch of your logic means that if there are valid key-value pairs in the container, go ahead and display the container's associated value(s).

  15. To display your container's values in-game, connect the Find node's return Value pin to the Set Text node's Value pin.

    Step2_31.png

    Click for full image.

  16. Now, drag off the Branch node's False pin, search for, and connect the Set Text(TextRender) node.

    Step2_32.png

    Click for full image.

    This branch of your logic means that if there are no valid key-value pairs in the container, go ahead and display something else.

  17. Drag off the Branch node's Value pin, search for, and connect to the ToText(string) node.

    Step2_33.png

    Click for full image.

  18. Now, define the string to read, Now, shoot the blocks! .

    Step2_34.png

    Click for full image.

  19. After inspecting your completed script, go ahead and click the Compile button before going back to the Editor's Viewport interface.

    Step2_35.png

    Click for full image.

  20. From the Editor's Viewport interface, click the Play button to see your newly implemented script at work.

    Step2_36.png

    Click for full image.

Section Result

At this point in the guide, you've defined a new Blueprint Map, filled the container with key-value pairs, and displayed the values with some basic logic that you created in your TextRender Actor's Blueprint Event Graph. If you want to learn how to perform a slightly more advanced operation, please continue onto the next step, where you'll learn how to Add a key-value pair to a Map, subsequently displaying the Map's values.

3. Adding Keys and Values to a Map

By now, you have a TextRender Actor displaying the associated values of a Blueprint Map that you defined in the previous step. In this step, you'll learn how to Add a key-value pair to a Map, subsequently displaying the Map's keys and associated values.

  1. From your project's Content Browser , double-click the Display Map TextRender Actor to open its Blueprint Event Graph . Step3_1.png

  2. You should see the Display Map TextRender Actor Blueprint Event Graph , where you'll be able to add a new Blueprint Map, to which you'll Add a new key-value pair, ultimately displaying the Map's keys and associated values to the Viewport .

    Step3_2.png

    Click for full image.

  3. At this point in the tutorial, you'll want to create a new Blueprint Map container for the upcoming Add operation. Go ahead and right-click on the Instruction Map variable and select Duplicate from the drop-down list to create a new Blueprint Map variable, naming it Weapon Inventory Map .

    Step3_3.png

  4. Please make sure that the new Map container matches the following properties, where the key is a String and the value is an Integer:

    Step3_4.png

    For illustrative purposes, you're creating a weapon inventory Blueprint Map container, where the key is the weapon name and the value is how much ammunication is available for the weapon.

  5. If you select your new Blueprint Map, the Default Value message, saying Please compile the blueprint , should be visible.

    Step3_5.png

    Click for full image.

  6. Go ahead and click the Compile button.

    Step3_6.png

    Click for full image.

  7. After compiling the Blueprint, you should see the Default Value disappear, making way for a default Map with no elements. Click the + (Add Element) button to add a single key-value pair.

    Step3_7.png

    Step3_7a.png

  8. At this point, the editor's Compiler Results window should also display the following warning:

    Step3_8.png

    Click for full image.

    UE4 emits this warning because you're duplicating Instruction Map , which is a Blueprint map having an Integer-String key-value property, to create a Weapon Inventory Map , which is a Blueprint Map having a String-Integer key-value property. During the duplication process, the engine parses key-value pairs belonging to Instruction Map , attempting to copy them into the key-value pairs for Weapon Inventory Map , which is undesired behavior.

    Step3_8Note.png

    Click for full image.

  9. Go ahead and fill your new Weapon Inventory Map container with the following key-value pairs:

    Step3_9.png

  10. Now, click the Compile button.

    Step3_10.png

    Click for full image.

  11. After filling the Weapon Inventory Map container with the appropriately typed key-value pairs, satisfying the new Blueprint Map's key-value property requirements, you should see the warning disappear.

    Step3_11.png

    Click for full image.

  12. Before you can add new logic to the existing Blueprint Event Graph, go ahead and drag the Weapon Inventory Map variable into the Blueprint, and select Get from the dropdown menu.

    Step3_12.png

    Click for full image.

Scripting the Logic

  1. To get started with building your new logic, drag off the Weapon Inventory Map node and add the Keys node from the Map Utilities interface.

    Step3_13.png

    Click for full image.

    The Keys node will output an Array of all keys that are present in your Weapon Inventory Map .

  2. Drag off the Array output pin belonging to the Keys node, search for, and add the ForEachLoop node.

    Step3_14.png

    Click for full image.

  3. Now, drag off the Array Element pin belonging to the ForEachLoop node, search for, and add the Print String node.

    Step3_15.png

    Click for full image.

  4. Right-click in the Blueprint Graph to open the Context Menu , where you'll search for and add Event ActorBeginOverlap .

    Step3_16.png

    Click for full image.

  5. Drag off the Other Actor pin of the Event ActorBeginOverlap node, search for, and add the Cast To FirstPersonProjectile node.

    Step3_17.png

    Click for full image.

  6. Now, connect the Cast To FirstPersonProjectile node to the Keys node.

    Step3_18.png

    Click for full image.

Displaying your Map's Keys

At this point, if you enter Play in Editor (PIE) mode, you'll be able to fire a projectile at the collision box for your Display Map Text Render Actor, where you'll be able to display an Array of keys that are contained in your Weapon Inventory Map .

Step3_DisplayingKeys.png

Click for full image.

Finishing the Script

  1. Now's the time to add a new key-value pair to your container. To do this, go ahead and drag the Weapon Inventory Map variable into the Blueprint.

    Step3_19.png

    Click for full image.

  2. Drag off the Weapon Inventory Map variable, adding the Add node from the Map Utilities interface.

    Step3_20.png

    Click for full image.

  3. Now, define the key-value pair that you'd like to add, defining Weapon 6 as the key and 60 as the value.

    Step3_21.png

  4. Drag off the Add node's output pin, search for, and add the Branch node.

    Step3_22.png

    Click for full image.

  5. Before you can set up the additional display logic showing your added key, you'll need to drag the Weapon Inventory Map variable into the Blueprint.

    Step3_23.png

    Click for full image.

  6. Now, drag off the Weapon Inventory Map variable, adding the Keys node from the Map Utilities interface.

    Step3_24.png

    Click for full image.

  7. Drag off the Array output pin belonging to the Keys node, search for, and add the ForEachLoop node.

    Step3_25.png

    Click for full image.

  8. Now, drag off the Array Element pin belonging to the ForEachLoop node, search for, and add the Print String node.

    Step3_26.png

    Click for full image.

  9. Click on the Text Color box to open the Color Picker menu.

    Step3_27.png

    Click for full image.

  10. Go ahead and set the color to the following values:

    Step3_28.png

  11. Again, before you can set up more display logic, showing your added value, you'll need to drag the Weapon Inventory Map variable into the Blueprint.

    Step3_29.png

    Click for full image.

  12. Now, drag off the Weapon Inventory Map variable, adding the Values node from the Map Utilities interface.

    Step3_30.png

    Click for full image.

  13. Drag off the Array output pin belonging to the Values node, search for, and add the ForEachLoop node.

    Step3_31.png

    Click for full image.

  14. Now, drag off the Execute Output pin belonging to the ForEachLoop node, search for, and add the Print String node.

    Step3_32.png

    Click for full image.

  15. Drag off the Array Element pin belonging to the ForEachLoop node, connecting it to the In String pin belonging to the Print String node.

    Step3_33.png

    Click for full image.

  16. Click on the Text Color box to open the Color Picker menu.

    Step3_34.png

    Click for full image.

  17. Go ahead and set the color to the following values:

    Step3_35.png

  18. Connect the Branch node's True pin to the Keys node.

    Step3_36.png

    Click for full image.

  19. Now, connect the Branch node's False pin to the Values node.

    Step3_37.png

    Click for full image.

  20. To complete the script's logic, go ahead and connect the Cast Failed pin of the Cast To FirstPersonProjectile node to the Add node.

    Step3_38.png

    Click for full image.

  21. After inspecting your completed script, go ahead and click the Compile button.

    Step3_39.png

    Click for full image.

  22. Finally, click the Save button before going back to the Editor's Viewport interface.

    Step3_40.png

    Click for full image.

  23. From the Editor's Viewport interface, click the Play button to see the updated script at work.

    Step3_41.png

    Click for full image.

End Result

As you can see from the video, when you initially fire a First Person Projectile the Display Map TextRender Actor's collision box, you'll see the original five keys being printed to the Viewport . Then, when you walk through the collision box, you'll see the new key being added, subsequently being printed. After backing out of the collision box, go ahead and fire another First Person Projectile to confirm the newly added key. Finally, when you walk through the collision box for a second time, you'll see all of the values being printed.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss