Walking The Actor Hierarchy

how to inspect and walk the Actor Hierarchy in a 3D Level / Editor World

This page covers how to walk the Actors in a 3D Level akin to the Outliner:

Understanding Spawned Vs Nested Actors

Before we get to the actor hierarchy it's important to be aware of how an actor was spawned in the 3D level. actors can spawn other actors. I'll be using the following terms to refer to the two possible ways in which an Actor is attached to another Actor:

  • Spawned Actors are Actors added to the 3D Level usually by an ActorComponent on a Blueprint Asset. They are very limited in what can be changed from the 3D level / Python. We cannot change display names or hierarchies as they are managed within the compiled Blueprint Asset that generated them. These Actors are owned by other Actors.

  • Nested Actors are actors in the 3D Level attached to each other in the 3D level. We can change displays names, hierarchies, and any exposed properties directly. These Actors are owned by the 3D Level.

Actors spawned by other Actors aren't as editable as Actors added directly to the 3D Level


Getting the Top-Most Level Actors

Building off of the get_all_actors() function from Expanded Options, we can use the following to get the list of top-most Actors in the 3D Level:

def get_root_actors():
    return [
        actor
        for actor in get_all_actors()
        if not actor.get_attach_parent_actor() 
        and not actor.get_parent_actor()
    ]

This will give us the top-most actors we can then walk through


Walking The Actor hierarchy

In order to walk the Actor Hierarchy we'll need a recursive function to step through the nested Actors.

This will rely on two functions in particular on the Actor Class:

  1. get_all_child_actors - this function gets the list of Actors spawned by the current Actor

  2. get_attached_actors - this function gets the list of Actors attached to the current Actor, which also includes actors spawned by the current Actor as well

We can use these two functions to get the separate lists of Spawned Actors and Nested Actors:

def walk_actor(actor, indent=0):
    """walk the given actor to print its hierarchy"""
    print(f"{'  ' * indent}{actor.get_actor_label()}")

    # separate the nested actors from the spawned actors:
    spawned_actors = actor.get_all_child_actors()
    nested_actors = [
        child 
        for child in actor.get_attached_actors()
        if child not in spawned_actors          
    ]
    
    # print the spawned actors
    for child in spawned_actors:
        print(f"{'  ' * (indent+2)}{child.get_actor_label()}  (SPAWNED)")
    
    # walk the nested actors
    for child in nested_actors:
        walk_actor(child, indent+2)

Results

The ordering may differ from the Outliner UI, but it is properly displaying which actors are Nested versus which actors are Spawned

Last updated