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 StartingItems = {
{ TEXT("Potion"), 3 },
{ TEXT("Arrow"), 20 }
};
Find a value: Find, FindRef or FindOrAdd
| Call | Returns | When the key is missing |
|---|---|---|
Find(Key) | A pointer you can change | nullptr, so check it first |
FindRef(Key) | A copy | A default value (0, empty string…) |
FindOrAdd(Key) | A reference you can change | Adds the key, then returns it |
Map[Key] | A reference | Crashes |
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 aGetTypeHashfunction. See custom struct as TMap key. - In Blueprints a TMap is called a Map. A
UPROPERTYTMap 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.