Unreal Object Handling
- Automatic Property Initialization:
UObjectsare automatically zeroed on initialization, before the constructor is called. This happens for the whole class,UPropertiesand native members alike. - Automatic Updating of References: When an
AActororUActorComponentis destroyed or otherwise removed from play, all references to it that are visible to the reflection system (UPropertypointers and pointers stored in Unreal Engine container classes such asTArray) are automatically nulled. ... An Object reference stored in a raw pointer will be unknown to the Unreal Engine, and will not be automatically nulled, nor will it prevent garbage collection. ... consider usingTWeakObjectPtr... it will not prevent garbage collection, but it can be queried for validity before being accessed and will be set to null if the Object it points to is destroyed. - 'Force Delete' on an asset in the editor also nulls referencing UProperties; code operating on asset UObjects must handle these pointers becoming null.
- Serialization: all
UPropertyvalues are automatically written or read unless explicitly marked as "transient" or unchanged from the post-constructor default value. ... New properties get default values copied from the new CDO. Removed properties are silently ignored.UObject::Serializecan be overridden. - Updating of Property Values: When the CDO has changed ... if the updated variable's value matches the value in the old CDO, it will be updated to the value it holds in the new CDO. Otherwise preserved. (Example: AEnemy Health default 100 -> 150; Enemy_3 set to 500 stays 500.)
- Editor Integration: Editor can expose these values automatically for editing ... optionally including integration into Blueprint.
- RTTI and Casting: every
UObjectclass has a customSupertypedef set to its parent class.Cast<T>returns null if not of that class;IsAqueries class. - Garbage Collection: UObjects that are no longer referenced or have been explicitly flagged for destruction will be cleaned up at regular intervals. The engine builds a reference graph ... At the root of this graph is a set of
UObjectsdesignated as the "root set". AnyUObjectcan be added to the root set. ... Any unreferencedUObjects... will be removed. - You typically need to maintain a
UPROPERTYreference to any Object you wish to keep alive, whether a simple Object pointer or a container such asTArray<UObject*>. Actors and their Components are frequently an exception, since Actors are usually referenced by ... the Level, and Components are referenced by the Actor itself. Actors can be explicitly marked for destruction by callingDestroy. Components can be destroyed withDestroyComponent, but usually destroyed when their owning Actor is removed. - Built-in features: multithreaded reachability analysis; unhashing code optimized to remove Actors from containers quickly. Settings in Project Settings > Engine > Garbage Collection:
- Create Garbage Collector UObject Clusters (on by default): related Objects grouped so only the cluster needs to be checked; but items in a cluster are all unhashed and prepared for deletion in the same frame, potentially causing a hitch if the cluster is large.
- Merge GC Clusters: clusters join when an object in one references another; clearing the reference will not dissolve the merged cluster; any reference to any object in the cluster keeps the entire cluster alive.
- Actor Clustering Enabled: via
bCanBeInCluster/CanBeInCluster; off by default except Static Mesh Actors and Reflection Capture Components; useful for actors destroyed all at once (e.g. static meshes unloaded with a sublevel). - Blueprint Clustering Enabled: clusters the
UBlueprintGeneratedClassitself, not instances. - Time Between Purging Pending Kill Objects: shortening the time between collections decreases unreachable objects per pass and can avoid hitches.
- Network Replication: UProperties can be tagged to replicate (server change -> sent reliably to clients; optional callback). UFunctions can be tagged to execute remotely: "server" function called on a client runs on the server; "client" function called from the server runs on the owning client.