In this lesson, you will learn how to use the Unreal Insights tool to track memory allocations and identify objects that are staying in memory longer than they should.
When we talk about memory leaks in Unreal, we are usually talking about objects that the Garbage Collector (GC) cannot destroy because something is still holding a "hard" reference to them. Even if you think an object is finished, a stray UPROPERTY reference will keep it alive indefinitely, leading to an ever-increasing memory footprint.
Setting up for Insight
To track this, you first need to enable the Memory Insights trace channel. When you run your game with the -trace=memory command-line argument, Unreal Insights captures a detailed timeline of every allocation and deallocation.
Identifying the Leak
Once you have your session open in the Unreal Insights application, focus on the Memory Insights tab. You are looking for two things:
- The Allocation Chart: If you see a "staircase" pattern that never levels off, your game is accumulating memory that isn't being freed.
- Snapshot Comparison: By taking a memory snapshot at two different times, you can compare them to see which specific classes are growing.
If you find that a specific UObject type is constantly growing, it is likely being spawned but never correctly cleaned up. Check your code for objects stored in persistent lists or containers:
// If this array is never cleared, the objects inside stay in memory
UPROPERTY()
TArray<UMyDataAsset*> PersistentList;
If you notice your object counts rising, search your codebase for any hard UPROPERTY references pointing to those objects. If you don't actually need to own the object, but just need to access it occasionally, remember to use a TWeakObjectPtr instead:
// Use a weak pointer to avoid preventing garbage collection
TWeakObjectPtr<UMyDataAsset> CachedReference;
By cross-referencing the "Object Count" in Insights with your reference management code, you can pinpoint exactly which class is failing to release its assets, allowing you to swap hard references for weak ones or manually clear your containers.
Key Takeaway: Use Unreal Insights to visualize rising memory graphs and identify which object types are failing to be garbage collected due to persistent references.