Recommendation
Use a hard reference when the dependency must already be loaded with its owner. Use a soft reference when loading needs to be deferred or controlled.
Compare the options
Hard Reference
Choose when
- The dependency is always required.
- Loading it with the owner is intentional.
- The reference cannot be unresolved during use.
Tradeoffs
- A hard reference creates a load dependency.
- Reference chains can pull more content into memory and cooked packages than expected.
- Blueprint
- Use an Object Reference or Class Reference variable.
- C++
- Use a reflected TObjectPtr<T> or TSubclassOf<T>.
Soft Reference
Choose when
- The asset is optional or large.
- A catalog selects the asset at runtime.
- Loading needs to happen only for a specific mode or screen.
Tradeoffs
- Callers must handle unloaded and missing assets.
- A loaded object needs a hard reference if it must stay resident.
- Blueprint
- Use a Soft Object Reference or Soft Class Reference with Async Load Asset or Async Load Class Asset.
- C++
- Use TSoftObjectPtr<T>, TSoftClassPtr<T>, FSoftObjectPath, and FStreamableManager::RequestAsyncLoad.
Requirements
Hard and soft references are built into CoreUObject. A soft reference doesn't load its target. Request the load and retain a hard reference while the asset must stay resident.
Example
Keep the player pawn skeletal mesh hard referenced when it is always required. Store optional cosmetic skins as soft references and stream the selected skin.