Pointer Types

Overview of UObject and "Smart" pointer types in Unreal

Updated about 2 years ago Edit Page Revisions

Unreal offers a library of several different types of pointers, some of which are Managed by Unreal's RTTI and garbage collection system, and some of which are Unmanaged and must be used carefully by the developer. Generally, UObjects should only ever be referenced with Managed pointers, whereas non-UObjects can be referenced with Unmanaged pointers.

Managed Pointers

These pointers work with Unreal's garbage collection system. These are the only pointer types that work with UObjects.

(see also Referencing Assets - Unreal Documentation)

Hard Object Pointer

UPROPERTY() UObject* Pointer = nullptr;

This pointer identifies the owner class as a “holder” or “dependent” of the referenced UObject. The garbage collection system will not destroy a UObject unless all hard pointers to the object become null, or Destroy is specifically called upon the target object, at which point all referencing hard pointers will be nulled automatically. Use IsValid(Pointer) to check for validity.

If an asset is assigned to the pointer in the class constructor or in the blueprint defaults, that asset will be loaded the first time an instance of that class is loaded.

Hard object pointers must be defined as non-static UClass member variables, or the GC system will not be able to track the pointer at runtime and establish the chain of dependencies - hard object pointers cannot be static or defined in non-UClasses.

Weak Object Pointer

TWeakObjectPtr<UObject> Pointer;

This pointer is used to reference UObjects without holding ownership on them. The garbage collection system has no awareness of Weak Object Pointers, so objects will be garbage collected regardless of whether they are still referenced by Weak Object Pointers.

Weak Object Pointers do not get nulled automatically when the referenced object is destroyed, so they perform additional work to ask the GC system whether the target object is still valid before resolving it. Weak Object Pointers are almost always more expensive at runtime than Hard Object Pointers.

Weak object pointers can be defined statically or in non-UClasses.

Soft Object Pointer

TSoftObjectPtr<UObject> Pointer;

These pointers are the same as weak object pointers, but they also contain a path to an object within an asset, and helper functionality to load that asset at runtime.

IsPending returns true if the asset path is valid and the instance pointer is not, indicating that the target asset is currently not loaded into memory. IsValid returns true if both members are valid, and IsNull returns true if both members are null.

Note that, like weak pointers, soft pointers will not prevent the target object from being garbage collected, so once loading is completed, it may be useful to 'pin' the object instance with a hard object pointer to keep the object instance in memory.

Unmanaged Pointers

These pointers work via simple reference-counting, and are not compatible with UObjects.

(See also Smart Pointer Library - Unreal Documentation)

Unique Pointer

TUniquePtr<FObject> Pointer;

This pointer indicates that the referencer is the sole owner of the target object. If this pointer is reassigned or nulled, the target object will be deleted immediately. Shared and Unique pointers may not reference the same object.

Shared Pointer

TSharedPtr<FObject> Pointer;

This pointer indicates that the holder may be one of many dependents on the target object. As the object gets assigned to shared pointers, the object keeps an internal count of the number of references. When the last shared pointer to the target object is nulled or reassigned, causing the number of references to become zero, the object is deleted. The object must inherit TSharedFromThis in order to be referenced by shared pointers. Shared and Unique pointers may not reference the same object.

Weak Pointer

TWeakPtr<FObject> Pointer;

This pointer indicates that the holder is not dependent on the target object. The IsValid method should be used to check for validity. The Pin method can be used to get a shared pointer to the target object. Weak pointers may reference the same objects as either shared or unique pointers.

Raw Pointer

FObject* Pointer = nullptr;

This pointer is not tracked by garbage collection or reference counting. There is little-to-no helper functionality to work with raw pointers in Unreal. Although this pointer may be used to reference objects that are also referenced by any of the above pointer types, it has no checks or guarantees of safety, so should be used carefully.

Warning: Do not use IsValid() on raw pointers. IsValid() is designed to work with Hard Object Pointers, and may naively try to call IsPendingKill() on the target object if the pointer is not null.

Additional Sources