TMap in Unreal Engine 5: The Practical Guide

Table of Contents

Works in Unreal Engine 5. Tested on UE 5.8. Updated October 2026.

Quick answer: a TMap stores values by key, like a dictionary. The five calls you need:

TMap<FName, int32> ItemCounts;

ItemCounts.Add(TEXT("Potion"), 3);                          // add or replace
int32* Count = ItemCounts.Find(TEXT("Potion"));            // pointer, nullptr if missing
int32 Arrows = ItemCounts.FindRef(TEXT("Arrow"));          // copy, 0 if missing
bool bHasPotion = ItemCounts.Contains(TEXT("Potion"));     // true or false
ItemCounts.Remove(TEXT("Potion"));                          // remove the key

Avoid ItemCounts[Key] unless you’re sure the key exists. Unlike std::map, it never adds the key and crashes if the key is missing.

Add items to a TMap

Add inserts a key, or replaces the value if the key already exists. Each key appears only once.

				
					TMap<FName, int32> StartingItems = {
	{ TEXT("Potion"), 3 },
	{ TEXT("Arrow"), 20 }
};
				
			

Find a value: Find, FindRef or FindOrAdd

CallReturnsWhen the key is missing
Find(Key)A pointer you can changenullptr, so check it first
FindRef(Key)A copyA default value (0, empty string…)
FindOrAdd(Key)A reference you can changeAdds the key, then returns it
Map[Key]A referenceCrashes

Always check the pointer from Find before using it:

				
					if (int32* PotionCount = ItemCounts.Find(TEXT("Potion")))
{
	*PotionCount += 1;
}
				
			

FindOrAdd is the easy way to count things:

				
					int32& Quantity = ItemCounts.FindOrAdd(ItemName);
Quantity += Amount;
				
			

Loop over a TMap

				
					for (const auto& Pair : ItemCounts)
{
	UE_LOG(LogTemp, Log, TEXT("%s x%d"), *Pair.Key.ToString(), Pair.Value);
}
				
			

Pair.Key is the key and Pair.Value is the value. Use auto& Pair (without const) to change values in the loop.

The order is not guaranteed. A TMap does not keep items in the order you added them. If you need an order, sort it with KeySort or ValueSort, or copy the keys into an array with GenerateKeyArray.

Remove items while looping

Removing inside a normal for loop crashes. Use an iterator instead:

				
					for (auto PairIterator = ItemCounts.CreateIterator(); PairIterator; ++PairIterator)
{
	if (PairIterator.Value() <= 0)
	{
		PairIterator.RemoveCurrent();
	}
}
				
			

Good to know

  • FString keys ignore upper and lower case. “Alice” and “ALICE” are the same key.
  • Enum keys just work: TMap<EEquipmentSlot, FName> needs no extra code.
  • Your own struct as a key needs operator== and a GetTypeHash function. See custom struct as TMap key.
  • In Blueprints a TMap is called a Map. A UPROPERTY TMap can’t hold another container (like a TArray) as its value, and it doesn’t replicate in multiplayer. See this fix.

FAQ

Why does TMap operator[] crash?

In Unreal, Map[Key] expects the key to already exist and stops the game with an assertion if it doesn’t. Use Find or FindOrAdd instead. See TMap operator[] vs Find vs FindOrAdd for which one to use.

How do I get all the keys of a TMap?

Call ItemCounts.GenerateKeyArray(MyArray), or GenerateValueArray for the values.

What is the difference between Add and Emplace?

For everyday use, none. Both add or replace a value. Emplace can build the key and value in place, which can save a copy.

Can a key have more than one value?

Not in a TMap. Use TMultiMap for that.

Related tutorials