Skip to content

Get Component by Class / Get Components by Class

At a glance

Lives on: one Actor; Blueprint API / Actor - Searches: components owned by that Target Actor, matching the chosen class or a subclass - Singular return: the first matching component, or None - Plural return: an array of all matching component references, empty when none match - Side effects: none; these nodes do not create, register, cache, or replicate components - Official docs: Get Component by Class and Get Components By Class

The one-minute version

  • Both nodes search one Actor's owned components. They do not search the level, attached Actors, or every Actor of the same class.
  • The class test includes subclasses. Asking for Actor Component can match every component; asking for Scene Component can match meshes, cameras, and other scene-component subclasses; asking for your BP_HealthComponent narrows the result to that reusable behavior class and its subclasses.
  • Get Component by Class returns one reference or None. If several components match, it returns whichever matching component the Actor's component collection encounters first. Do not turn that incidental order into gameplay design.
  • Get Components by Class returns every match in an array, or [] when none match. Output order is not a stable identity or presentation order.
  • The real objects keep their runtime subclasses. A component selected through a base-class filter can still be a StaticMeshComponent, custom component, or another subclass.
  • Components inherited from a parent Blueprint and components added normally at runtime can be found once they belong to this Actor. A previous cached array does not update when later components are added or destroyed.
  • A Child Actor Component itself belongs to the parent Actor and can match. The components owned by the child Actor it spawned belong to that child, so query the child Actor separately.
  • A valid Actor with no match returns None or an empty array silently. A None Target is different: Blueprint cannot make the call and reports Accessed None.
  • For a stable designed component, use its direct typed reference. For runtime discovery, search once during setup, validate, and cache rather than scanning every Tick.

An Actor owns a collection of Actor Components. The collection includes plain Actor Components, Scene Components, Primitive Components, and their concrete subclasses:

BP_PlayerCharacter (Actor)
├─ CapsuleComponent          (CapsuleComponent -> PrimitiveComponent)
├─ Mesh                      (SkeletalMeshComponent -> PrimitiveComponent)
├─ CameraBoom                (SpringArmComponent -> SceneComponent)
├─ FollowCamera              (CameraComponent -> SceneComponent)
├─ CharacterMovement         (CharacterMovementComponent -> ActorComponent)
└─ BP_HealthComponent        (custom ActorComponent)

The nodes walk that Actor-local collection and apply an inheritance test:

pseudocode of the engine behavior - not engine source

function GetComponentByClass(TargetActor, RequestedClass):
    for each Component owned by TargetActor:
        if Component is RequestedClass or any subclass:
            return Component
    return None

function GetComponentsByClass(TargetActor, RequestedClass):
    Results = []
    for each Component owned by TargetActor:
        if Component is RequestedClass or any subclass:
            add Component reference to Results
    return Results

They do not inspect component names, tags, interfaces, activation, visibility, collision, or gameplay state. Class inheritance is the only filter.

Class filters include subclasses

The requested class is a base boundary, not an exact-class-only test.

Component Class input Example matches Example exclusions
Actor Component health, movement, audio, mesh, collision, every other Actor Component subclass non-component UObjects and Actors
Scene Component Spring Arm, Camera, Audio, Static Mesh, Skeletal Mesh, collision shapes plain Health/Inventory Actor Components with no transform
Primitive Component Static/Skeletal Mesh, Capsule, Box, Sphere Camera, Spring Arm, Audio, plain Actor Component
BP_HealthComponent that class and any child class derived from it unrelated Actor Components

Pick the narrowest class that expresses the contract. Asking for Actor Component and casting the first result is usually a hidden ordering bug. Ask for BP_HealthComponent when health is what you need.

Exact-class-only behavior requires an additional class equality check over the plural results. Most gameplay wants subclass inclusion because a specialized child component should still satisfy its base component contract.

What exactly comes back

Get Component by Class

The underlying C++ declaration returns an ActorComponent*, with Blueprint metadata that lets the output pin follow the selected Component Class. The runtime object is the actual matching component instance:

Component Class = BP_HealthComponent
Return Value = the BP_HealthComponent instance owned by this Actor

Component Class = SceneComponent
Return Value may actually be a CameraComponent or StaticMeshComponent

The return is a reference to the existing object, not a copy and not a newly created component. Calling a function through it changes that live component. It may become invalid later if the component or owning Actor is destroyed.

Get Components by Class

The engine's C++ wrapper is declared as an array of ActorComponent* and fills it with references to every match. Blueprint uses the Component Class metadata to specialize the connected pin where the graph can know the class; a generic class input can leave you working at the broader Actor Component type. In all cases, the runtime elements remain their real subclasses.

The output array itself is a snapshot of references at the time of the call:

  • adding another matching component later does not append to the old array;
  • removing a component later does not compact every array you previously stored;
  • reordering or replacing components does not update saved indices; and
  • an element reference can become invalid after the query.

An empty array is a successful search with zero matches, not an exception.

“First” is not a component identity

The singular node stops at the first match it encounters. That is only safe when your design enforces zero or one matching component.

Fragile pattern:

BP_Weapon has MuzzleAudio and ReloadAudio
Get Component by Class(AudioComponent)
-> assume result is MuzzleAudio

Both components satisfy the class. Component construction, inheritance, or a future edit can change which one is encountered first.

Stronger choices:

  • keep a direct MuzzleAudio component reference;
  • use Find Component by Tag with an enforced unique Muzzle Component Tag;
  • call Get Components by Class and select by an explicit property/tag; or
  • expose a typed GetMuzzleAudio() function from the Actor that owns the invariant.

Do not sort the returned array by component object name and call that a stable contract unless your project deliberately owns and validates those names.

When it returns None or an empty array

For a valid Target Actor, no match is quiet:

Cause Singular Plural What to check
Actor owns no component of that class/subclass None [] Components window and runtime actor instance
Class filter is too narrow or simply wrong None [] component inheritance family
You queried the wrong Actor None / unrelated first match empty / unrelated matches print Target display name and class
Runtime component has not been added yet None [] call timing and Add Component completion
Component was destroyed/removed before the search None [] component lifetime owner
Desired component belongs to a Child Actor or attached Actor None [] query that Actor instead

No-match does not log, branch to a Failed pin, add the missing component, try a parent/child Actor, or search the world.

A None Target is a different failure shape. Blueprint cannot call an Actor function on no object, so the call is skipped and editor/development output can report Accessed None. Validate the Target Actor first, then handle the node's own None/empty no-match result.

Designed, inherited, and runtime-added components

Designed and inherited components

Components created through the Blueprint Components window become owned parts of each runtime Actor instance. Components defined by a parent Blueprint are also part of the child instance, so these searches can find them after normal Actor construction.

Inside the Actor Blueprint that owns a designed component, dragging that named component from the Components panel into the graph is clearer and cheaper than searching for it by class.

Runtime-added components

Add Component by Class adds a component to an existing Actor and returns the new component directly. After the component has gone through the normal add/finish path and belongs to the Actor, later class searches can find it.

Prefer the returned reference:

Add Component by Class BP_ShieldComponent
-> Return Value
-> store ShieldComponent

Searching the Actor immediately afterward to rediscover the object you were just given is extra work and becomes ambiguous if several shields are allowed.

If components can appear and disappear dynamically, decide whether the owner updates a canonical typed reference/array as part of that lifecycle or whether consumers deliberately re-query at specific synchronization points. A cached BeginPlay result is not magically refreshed.

Child Actor Components and attachments

A Child Actor Component has two relevant objects:

Parent Actor
└─ ChildActorComponent       // component owned by Parent Actor
   └─ Spawned Child Actor    // separate Actor
      └─ Child's components  // owned by Child Actor

Searching the Parent can return the Child Actor Component itself when its class passes the filter. The ordinary Blueprint Get Component(s) by Class nodes do not recurse into the spawned Child Actor's owned components. Get the Child Actor from the Child Actor Component, validate it, then query that Actor.

Attaching one Actor to another also does not merge their component ownership. Attachment changes transform parenting; each Actor still answers for its own components.

C++ AActor::GetComponents overloads expose an explicit bIncludeFromChildActors choice for code that wants recursion. The Blueprint wrapper covered here does not expose that switch, which keeps its search scope to the Target Actor.

Tags, interfaces, and names are separate filters

Class answers “what kind of component is it?” Other nodes answer other questions:

Need one PrimitiveComponent tagged WeakPoint
-> Find Component by Tag

Need every component tagged DamageReceiver
-> Get Components by Tag

Need every component implementing BPI_InteractablePart
-> Get Components by Interface

Get Component(s) by Class ignores Component Tags and interfaces. A class can implement an interface and carry tags, but those facts are not part of this node's test.

Use class identity when the type itself owns the behavior you need. Use an interface when unrelated component classes share a callable contract. Use a plain Component Tag when several same-class parts need labels such as Muzzle, WeakPoint, or DamageReceiver.

Cost and caching

The singular query walks owned components until it finds a match. The plural query walks the collection and builds a new output array of references. The cost is local and usually tiny for setup on a normal Actor; it is still wasted work when repeated every Tick for a component that never changes.

Good setup pattern for an external consumer:

InitializeSource(NewActor):
    Is Valid(NewActor)
    -> Get Component by Class BP_HealthComponent
    -> Is Valid(Return Value)
       true: store HealthSource and bind events
       false: report/own the missing-component path

If the current Pawn can respawn or possession can change, re-run that setup when the Actor reference changes and unbind the old component. “Cache once” means once per relevant owner lifetime, not forever across replacement Actors.

For required components, a typed Actor function, interface, or construction invariant often communicates failure better than every consumer independently searching and silently accepting None.

Runtime destruction and object validity

The returned references are live UObject references. A component can be destroyed explicitly, removed as a temporary runtime component, or disappear with its owning Actor.

CachedComponents -> For Each
-> Is Valid(Component)
   true: use it
   false: remove/rebuild according to owner policy

An array slot and an object lifetime are separate facts. A stored array can still have Length 3 while one referenced component is no longer valid. The query does not promise future validity or subscribe the array to component lifetime changes.

Multiplayer boundary

These are local read-only queries. Each machine searches the components that exist on its local copy of the Target Actor.

  • They do not ask the server for a component.
  • They do not replicate a runtime-added component or its custom state.
  • They do not grant network authority through component ownership.
  • A server-only or client-local component can produce different results on different machines by design.

For shared gameplay, create/replicate the owning Actor and component state intentionally, mutate authority-owned state on the server, and use replicated state or RPCs for the result. A lookup is not synchronization.

The patterns everyone actually uses

Required reusable component on an arbitrary Actor

Target Actor
-> Is Valid
-> Get Component by Class BP_HealthComponent
-> Is Valid(Return Value)
   true: ApplyHealthDelta / bind OnHealthChanged
   false: Target does not satisfy this setup contract

If many callers need this, a Blueprint Interface such as GetHealthComponent can make the contract explicit and keep lookup policy in the Actor that owns it.

Configure every matching component once

BeginPlay
-> Get Components by Class PrimitiveComponent
-> For Each
-> Is Valid
-> apply shared collision/debug setting

Use a narrower class or tag when “every primitive” is broader than the actual design intent.

Runtime component creation

Add Component by Class BP_StatusEffectComponent
-> store returned typed reference
-> initialize it

later, diagnostic/setup code:
Get Components by Class BP_StatusEffectComponent
-> inspect all current effect components

Creation code should keep the direct return; plural lookup is useful when the Actor intentionally supports several independently added instances.

C++ twins

Original example code:

if (IsValid(TargetActor))
{
    if (UHealthComponent* Health =
            TargetActor->FindComponentByClass<UHealthComponent>())
    {
        Health->ApplyHealthDelta(-10.0f);
    }

    TInlineComponentArray<UPrimitiveComponent*> Primitives(TargetActor);
    for (UPrimitiveComponent* Primitive : Primitives)
    {
        // The array contains this Actor's matching components.
    }
}

For C++, Epic recommends the typed GetComponents overloads rather than the Blueprint-only K2_GetComponentsByClass wrapper. Those overloads can also state whether Child Actors should be included.

What these nodes do not do

They do not:

  • search all Actors in the world;
  • create or register a missing component;
  • require an exact class rather than accepting subclasses;
  • filter by Component Tag, interface, activation, visibility, or collision;
  • guarantee which match is “first” when several exist;
  • guarantee stable ordering of the plural result;
  • recurse into attached Actors or Child Actor instances in the ordinary Blueprint nodes;
  • keep an old result array synchronized with later additions/removals;
  • guarantee returned references remain valid; or
  • replicate, save, initialize, or authorize component state.

Lookalikes - which one do I want?

Node or reference Use when Watch out
Direct typed component reference The Actor Blueprint owns a known designed component. Rebind when the owning Actor instance changes.
Get Component by Class A valid Actor should have zero or one component satisfying a class contract. Multiple matches make “first” ambiguous.
Get Components by Class You need every owned component of a class/subclass. Empty is normal; order and later lifetime are not guaranteed.
Find Component by Tag Class plus one Component Tag identifies one owned part. Still ambiguous if the tag is not unique.
Get Components by Tag Class plus a Component Tag identifies a group. Returns only this Actor's owned components.
Get Components by Interface Unrelated component classes share a behavior contract. Output is still references that need lifetime handling.
Add Component by Class The Actor needs a new runtime component. Creation is a mutation; keep its return instead of re-searching.
Get All Actors Of Class You need world Actors, not parts of one known Actor. Much broader search and returns Actors, not their components.

Rule of thumb: direct reference for a designed part, singular class lookup for an enforced zero-or-one contract, plural lookup for an intentional group, and tag/interface lookup when class alone cannot identify the part.

Going deeper