Actor Lifecycle
Overview
This document is a high level overview of the lifecycle of an Actor: how an Actor is instantiated (Spawned) into the level and then how it is removed (Destroyed).
The flow graph below shows the three primary paths for how an Actor is instanced. No matter how an Actor is created, they all follow the same path to their destruction.
Lifecycle Break Down
Load from Disk
This path occurs for any Actor that is already in the level, like when LoadMap occurs, or AddToWorld (from streaming or sub levels) is called.
Actors in a package/level are loaded from disk.
PostLoad - is called by serialized Actor after they have finished loading from disk. Any custom versioning and fixup behavior should go here. PostLoad is mutually exclusive with PostActorCreated.
InitializeActorsForPlay
RouteActorInitialize for any non-initialized Actors (covers seamless travel carry over)
PreInitializeComponents - Called before InitializeComponent is called on the Actor's components
InitializeComponent - Helper function for the creation of each component defined on the Actor
PostInitializeComponents - Called after the Actor's components have been initialized
BeginPlay - Called when the level is started
Play in Editor
The Play in Editor path is mostly the same as Load from Disk, however the Actors are never loaded from disk, they are copied from the Editor.
Actors in the Editor are duplicated into a new World
PostDuplicate is called
InitializeActorsForPlay
RouteActorInitialize for any non-initialized Actors (covers seamless travel carry over)
PreInitializeComponents - Called before InitializeComponent is called on the Actor's components
InitializeComponent - Helper function for the creation of each component defined on the Actor
PostInitializeComponents - Called after the Actor's components have been initialized
BeginPlay - Called when the level is started
Spawning
When spawning (instancing) an Actor, this is the path that will be followed.
SpawnActor called
PostSpawnInitialize
PostActorCreated - called for spawned Actors after its creation, constructor like behavior should go here. PostActorCreated is mutually exclusive with PostLoad.
ExecuteConstruction:
OnConstruction - The construction of the Actor, this is where Blueprint Actors have their components created and blueprint variables are initialized
PostActorConstruction:
PreInitializeComponents - Called before InitializeComponent is called on the Actor's components
InitializeComponent - Helper function for the creation of each component defined on the Actor
PostInitializeComponents - Called after the Actor's components have been initialized
OnActorSpawned broadcast on UWorld
BeginPlay is called.
Deferred Spawn
An Actor can be Deferred Spawned by having any properties set to "Expose on Spawn."
SpawnActorDeferred - meant to spawn procedural Actors, allows additional setup before Blueprint construction script
Everything in SpawnActor occurs, but after PostActorCreated the following occurs:
Do setup / call various "initialization functions" with a valid but incomplete Actor instance
FinishSpawningActor - called to Finalize the Actor, picks up at ExecuteConstruction in the Spawn Actor line.
Coming to the End of Life
Actors can be destroyed in a number of ways, but the way they end their existence is always the same.
During Gameplay
These are completely optional, as many Actors will not actually die during play.
Destroy - is called manually by game any time an Actor is meant to be removed, but gameplay is still occurring. The Actor is marked pending kill and removed from Level's array of Actors.
EndPlay - Called in several places to guarantee the life of the Actor is coming to an end. During play, Destroy will fire this, as well Level Transitions, and if a streaming level containing the Actor is unloaded. All the places EndPlay is called from:
Explicit call to Destroy
Play in Editor Ended
Level Transition (seamless travel or load map)
A streaming level containing the Actor is unloaded
The lifetime of the Actor has expired
Application shut down (All Actors are Destroyed)
Regardless of how this happens, the Actor will be marked RF_PendingKill so during the next garbage collection cycle it will be deallocated. Also, rather than checking for pending kill manually, consider using an FWeakObjectPtr as it is cleaner.
OnDestroy - This is a legacy response to Destroy. You should probably move anything here to EndPlay as it is called by level transition and other game cleanup functions.
Garbage Collection
Some time after an Actor has been marked for destruction, Garbage Collection will occur to actually remove the Actor from memory, freeing any resources it was using.
BeginDestroy - This is the Actor's chance to free up memory and handle other multithreaded resources (ie: graphics thread proxy objects).
IsReadyForFinishDestroy - This lets the garbage collection know when it is ready to be deallocated permanently.
FinishDestroy - Finally, the Actor is really going to be destroyed, and this is another chance to free up internal data structures. This is the last call before memory is freed.