Iterators: Object & Actor Iterators, Optional Class Scope For Faster Search

Overview

Author ()

Contributing Author ()

Dear Community,

In the UE4 engine two of the most powerful tools I use constantly are the Object and the Actor Iterators.

You can use these functions to search for all Run-Time instances of actors and objects, or only specific classes!

The advantage of using the UE4 iterators is that they are always accurate!

You dont have to maintain dynamic arrays of actors, and then remember to remove actors when they are destroyed!

The Actor and Object Iterators always give you the real and accurate list of all actors / objects currently still active in your game world

Yay!

Technical

These functions can be used to search for all instances of actors and objects, or only specific sub-classes, at runtime, removing the need to maintain dynamic arrays of actors and having to remember to remove actors upon destruction.

As with all other instance iterators in UE4, both the Object and the Actor Iterators are capable of limiting the scope of search to a chosen UClass.

Include

Both functions are global and can be included in your code through:

'''#include "EngineUtils.h"

Object Iterator

for ( TObjectIterator Itr; Itr; ++Itr )
{
    // Access the subclass instance with the * or -> operators.
    USkeletalMeshComponent *Component = *Itr;
    ClientMessage(Itr->GetName());
}

Actor Iterator

Note that GetWorld() will have to be somehow provided, it is not a global function.

for (TActorIterator ActorItr(GetWorld()); ActorItr; ++ActorItr)
{
    // Same as with the Object Iterator, access the subclass instance with the * or -> operators.
    AStaticMeshActor *Mesh = *ActorItr;
    ClientMessage(ActorItr->GetName());
    ClientMessage(ActorItr->GetActorLocation().ToString());
}

Object Iterator & Actor Iterator Comparison

Because AActor extends UObject, the Object Iterator can search for AActors while the Actor Iterator cannot search for instances of UObjects that do not extend AActor at some point. Thus the Object Iterator can search for all UStaticMeshComponents as well as all ACharacters:

TObjectIterator Itr;
TObjectIterator Itr;

Generally the Actor Iterator can be seen as a specialized case of the Object Iterator which can only iterate over AActors of a specific UWorld*.

A Caveat regarding the Object Iterator

Unlike the Actor Iterator, the Object iterator can iterate over objects in the Pre-PIE world / the Editor World. This can lead to unexpected results.

I recommend using the ActorIterator anywhere you can because it provides the safety of not accessing actors that are pending kill in the UE4 ObjectArray and guarantees the actors are in the same world as your calling context (the UWorld you supply to the Iterator). - ()

Advantage of Actor Iterator

As noted above the Actor Iterator is a special case Object Iterator. Given a UWorld* context it saves you checking the world of the actors as one would need to when using the Object Iterator directly:

TActorIterator ActorItr(GetWorld());

Examples

World Filter with Object Iterator to Mimic Actor Iterator

The Object Iterator can and will return editor-instance / default objects. The editor uses these defaults objects to copy default values over to new instances of the class and thus should not be edited at runtime. To filter out such objects a world check can be performed.

UWorld* YourGameWorld = nullptr; // Set this somehow from another UObject or pass it in as an argument or parameter

for (TObjectIterator Itr; Itr; ++Itr)
{
    // Filter out objects not contained in the target world.
    if (Itr->GetWorld() != YourGameWorld)
    {
       continue;
    }
    // Do stuff
}

Conclusion

I have now shared with you two of my absolute favorite tools in the UE4 Engine!

With ActorIterator and ObjectIterator you can accurately lookup and modify actors or objects anywhere in your game world at any time!

\