UE Actor-Component Architecture

You are an expert in Unreal Engine's Actor-Component architecture.

Project Context

Before responding, read

.agents/ue-project-context.md

Information Gathering

Clarify the developer's specific need before diving in:

• New actor from scratch, or adding behavior to an existing one?
• Logic-only (UActorComponent) or needs world position (USceneComponent)?
• Spawning requirement (deferred init, pooling, net-spawned)?
• Lifecycle bug (BeginPlay/Constructor confusion, component not initialized)?
• Cross-actor behavior via interfaces?

Core Architecture Mental Model

Unreal's Actor-Component system is composition over inheritance. An

AActor

UActorComponent

UObject
  └── AActor                         (placeable/spawnable world entity)
        └── owns N x UActorComponent (reusable behavior units)
              └── USceneComponent    (adds transform + attachment)
                    └── UPrimitiveComponent (adds collision + rendering)

AActor

UObject

new

delete

SpawnActor

Destroy

Actor Lifecycle

Full event order and safety rules are in

references/actor-lifecycle.md

Constructor                  → CreateDefaultSubobject, tick config, default values
PostActorCreated             → spawned actors only; before construction script
PostInitializeComponents     → all components initialized; world accessible
BeginPlay                    → game running; full logic OK; components BeginPlay fires here
Tick(DeltaTime)              → per-frame; each ticking component's TickComponent fires
EndPlay(EEndPlayReason)      → cleanup; ClearAllTimers; call Super
Destroyed                    → pre-GC; avoid complex logic

Constructor vs BeginPlay

Constructor runs first on the Class Default Object (CDO) — an archetype used for default values.

GetWorld()

nullptr

// CORRECT — constructor-time only
AMyActor::AMyActor()
{
    MeshComp = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    SetRootComponent(MeshComp);
    PrimaryActorTick.bCanEverTick = true;
    PrimaryActorTick.TickInterval = 0.1f;
}

// CORRECT — world-dependent code belongs in BeginPlay
void AMyActor::BeginPlay()
{
    Super::BeginPlay(); // Required — always call Super
    GetWorld()->SpawnActor<AProjectile>(...);
}

PostInitializeComponents

Called before BeginPlay; components are initialized; world exists. Use it to bind delegates to own components.

void AMyCharacter::PostInitializeComponents()
{
    Super::PostInitializeComponents();
    HealthComponent->OnDeath.AddDynamic(this, &AMyCharacter::HandleDeath);
}

EndPlay — reasons matter

Destroyed

Actor->Destroy()

LevelTransition

EndPlayInEditor

RemovedFromWorld

Quit

void AMyActor::EndPlay(const EEndPlayReason::Type EndPlayReason)
{
    GetWorld()->GetTimerManager().ClearAllTimersForObject(this);
    Super::EndPlay(EndPlayReason);
}

Network lifecycle note

Replicated actors: on clients,

BeginPlay

OnRep_

PostNetReceive()

bHasInitialized

PostNetInit

AActor

Component System

The three layers

UActorComponent

USceneComponent

UPrimitiveComponent

Notable subclasses:

UStaticMeshComponent

USkeletalMeshComponent

UCapsuleComponent

UBoxComponent

USphereComponent

UWidgetComponent

"UMG"

USpringArmComponent

UCameraComponent

UChildActorComponent

references/component-types.md

Component creation

In the constructor (for default components that appear in the Details panel):

AMyActor::AMyActor()
{
    // CreateDefaultSubobject registers the component as a subobject —
    // it is serialized with the actor and visible in Blueprint editors.
    MeshComp = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    SetRootComponent(MeshComp);

    ArrowComp = CreateDefaultSubobject<UArrowComponent>(TEXT("Arrow"));
    ArrowComp->SetupAttachment(MeshComp); // Parent set here; no world needed

    HealthComp = CreateDefaultSubobject<UHealthComponent>(TEXT("Health"));
    // Logic-only components need no attachment
}

At runtime (dynamic addition):

void AMyActor::AddLight()
{
    // NewObject creates but does NOT register with the world
    UPointLightComponent* Light = NewObject<UPointLightComponent>(this,
        UPointLightComponent::StaticClass(), TEXT("DynamicLight"));

    Light->SetupAttachment(GetRootComponent());
    Light->RegisterComponent(); // Gives it world presence (render proxy, physics)
    Light->SetIntensity(5000.f);
}

void AMyActor::RemoveLight(UActorComponent* Comp)
{
    Comp->DestroyComponent(); // Unregisters and marks for GC
}

// UnregisterComponent() removes a component from the world without destroying it (reversible).
// DestroyComponent() marks it for GC — irreversible. Use Unregister when you may re-enable it later.

Why this distinction matters: constructor-created components are owned subobjects and participate in the actor's GC root. Runtime components via

NewObject

UPROPERTY

Attachment

// Constructor (SetupAttachment — no world required)
SpringArmComp->SetupAttachment(RootComponent);
CameraComp->SetupAttachment(SpringArmComp);

// Runtime (AttachToComponent — world must exist)
WeaponMesh->AttachToComponent(
    CharMesh,
    FAttachmentTransformRules::SnapToTargetNotIncludingScale,
    TEXT("WeaponSocket")  // Named socket on the skeletal mesh
);

WeaponMesh->DetachFromComponent(FDetachmentTransformRules::KeepWorldTransform);

Activation

// In constructor — opt out of auto-activation for optional components
SoundComp->bAutoActivate = false;

// Runtime — Activate() checks ShouldActivate() internally
SoundComp->Activate();
SoundComp->Deactivate();
SoundComp->SetActive(true, /*bReset=*/false);

Spawning

Standard spawn

FActorSpawnParameters Params;
Params.Owner = this;
Params.Instigator = GetInstigator();
Params.SpawnCollisionHandlingOverride =
    ESpawnActorCollisionHandlingMethod::AdjustIfPossibleButAlwaysSpawn;
Params.Name = FName("Enemy_Boss");  // deterministic name for replication (must be unique)

AEnemy* Enemy = GetWorld()->SpawnActor<AEnemy>(
    AEnemy::StaticClass(), Location, Rotation, Params);

Deferred spawning — configure before BeginPlay

Use when the actor's

BeginPlay

AEnemy* Enemy = GetWorld()->SpawnActorDeferred<AEnemy>(
    AEnemy::StaticClass(), SpawnTransform, Owner, Instigator,
    ESpawnActorCollisionHandlingMethod::AlwaysSpawn);

if (Enemy)
{
    Enemy->SetEnemyData(EnemyDataAsset); // Set BEFORE BeginPlay
    Enemy->FinishSpawning(SpawnTransform);
    // FinishSpawning triggers PostInitializeComponents then BeginPlay
}

Object pooling

For high-frequency actors (projectiles, shell casings), repeated

SpawnActor

Destroy

AProjectile* AProjectilePool::Get()
{
    for (AProjectile* P : Pool)
    {
        // IsHidden() reflects the pool's "inactive" state set on return.
        // IsActive() exists only on UActorComponent, not on AActor.
        if (P->IsHidden())
        {
            P->SetActorHiddenInGame(false);
            P->SetActorEnableCollision(true);
            return P;
        }
    }
    AProjectile* New = GetWorld()->SpawnActor<AProjectile>(ProjectileClass, ...);
    Pool.Add(New);
    return New;
}

Ticking

Setup

AMyActor::AMyActor()
{
    PrimaryActorTick.bCanEverTick = true;
    PrimaryActorTick.bStartWithTickEnabled = false; // Enable in BeginPlay
    PrimaryActorTick.TickInterval = 0.1f;           // ~10 Hz throttle
    PrimaryActorTick.TickGroup = TG_PostPhysics;    // After physics settles
}

Tick groups:

TG_PrePhysics

TG_DuringPhysics

TG_PostPhysics

TG_PostUpdateWork

Component tick: Set

PrimaryComponentTick.bCanEverTick = true

PrimaryComponentTick.TickGroup

Tick dependencies

// ActorA ticks after ActorB completes
ActorA->AddTickPrerequisiteActor(ActorB);
ComponentA->AddTickPrerequisiteComponent(ComponentB);

When NOT to tick

Tick has per-frame cost even when nothing changes. Prefer:

// Delayed/repeating events → FTimerHandle
GetWorld()->GetTimerManager().SetTimer(TimerHandle, this,
    &AMyActor::OnTimerFired, 2.0f, /*bLoop=*/true);

// State changes → delegates / multicast delegates
HealthComp->OnDeath.AddDynamic(this, &AMyActor::HandleDeath);

// Collision events → OnComponentBeginOverlap / OnActorBeginOverlap

Only tick for true per-frame needs: smooth interpolation, physics sub-stepping, streaming queries.

Interfaces (UINTERFACE Pattern)

Interfaces let unrelated actor types respond to the same message without coupling through inheritance. This replaces

Cast<ASpecificType>

Declaration

// IInteractable.h
UINTERFACE(MinimalAPI, Blueprintable)
class UInteractable : public UInterface { GENERATED_BODY() };

class MYGAME_API IInteractable
{
    GENERATED_BODY()
public:
    // BlueprintNativeEvent: C++ default + Blueprint can override
    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category="Interaction")
    void OnInteract(AActor* Instigator);
};

Implementation

// AChest.h
UCLASS()
class AChest : public AActor, public IInteractable
{
    GENERATED_BODY()
public:
    virtual void OnInteract_Implementation(AActor* Instigator) override;
};

Calling through the interface

// No cast needed — works on any actor or component
if (Target->Implements<UInteractable>())
{
    // Execute_ prefix required for Blueprint-callable interface functions
    IInteractable::Execute_OnInteract(Target, GetPawn());
}

Interface vs component: use an interface for a capability declaration ("this can be interacted with") especially when Blueprint classes need to implement it. Use a component when the behavior has its own state, needs ticking, or is reused identically by many actor types.

Composition Patterns

Favor components over deep inheritance

// Wrong: inheritance hierarchy collapses under varied requirements
ACharacter → AHero → ASwordHero → AFireSwordHero

// Right: flat base + composed components
ABaseCharacter
  + UHealthComponent     (HP, damage, death event)
  + UInventoryComponent  (items, equipment)
  + UAbilityComponent    (skill execution)
  + UStatusComponent     (buffs/debuffs)

Component-to-component communication

Components should not hold raw pointers to siblings. Query through the owner or use delegates:

// Query approach
UHealthComponent* Health = GetOwner()->FindComponentByClass<UHealthComponent>();

// Delegate approach — total decoupling
HealthComp->OnDeath.AddDynamic(AbilityComp, &UAbilityComponent::OnOwnerDied);

Data-driven composition

// UEnemyData (UDataAsset) — varies per enemy type
// AEnemy reads configuration at BeginPlay or via SpawnActorDeferred

void AEnemy::Initialize(UEnemyData* Data)
{
    HealthComp->SetMaxHealth(Data->MaxHealth);

    for (TSubclassOf<UActorComponent> CompClass : Data->AdditionalComponents)
    {
        UActorComponent* Comp = NewObject<UActorComponent>(this, CompClass);
        Comp->RegisterComponent();
    }
}

Common Mistakes and Anti-Patterns

Inheritance abuse

// Wrong — one class per variant
UCLASS() class AFireEnemy : public AEnemy { };
UCLASS() class AIceEnemy  : public AEnemy { };

// Right — one class, multiple DataAssets
// UEnemyData_Fire.uasset, UEnemyData_Ice.uasset → AEnemy reads at BeginPlay

Tick polling instead of events

// Wrong — checked every frame
void AMyActor::Tick(float DeltaTime)
{
    if (HealthComp->IsDead()) { HandleDeath(); }
}

// Right — event-driven, zero per-frame cost
void AMyActor::BeginPlay()
{
    Super::BeginPlay();
    HealthComp->OnDeath.AddDynamic(this, &AMyActor::HandleDeath);
    SetActorTickEnabled(false);
}

Forgetting Super in lifecycle overrides

Every lifecycle override must call

Super::

// Always
void AMyActor::BeginPlay()  { Super::BeginPlay(); ... }
void AMyActor::EndPlay(...) { ...; Super::EndPlay(EndPlayReason); }
void AMyActor::PostInitializeComponents() { Super::PostInitializeComponents(); ... }

Storing raw actor pointers

// Wrong — crashes when the actor is destroyed
AActor* CachedTarget;

// Right — use TWeakObjectPtr and check IsValid before use
TWeakObjectPtr<AActor> CachedTarget;
if (CachedTarget.IsValid()) { CachedTarget->DoSomething(); }

Related Skills

• ue-cpp-foundations

  — UCLASS, UPROPERTY, UFUNCTION macros underpinning all patterns above

• ue-gameplay-framework

  — GameMode, PlayerController, Pawn layered on top of this system

• ue-physics-collision

  — UPrimitiveComponent channels, sweeps, overlap events

Quick Reference

Constructor          CreateDefaultSubobject, SetRootComponent, tick config
PostInitialize       Bind delegates to own components; world accessible
BeginPlay            Full game logic; SpawnActor; timer setup
Tick                 Per-frame only; prefer timers/events
EndPlay              ClearAllTimers; Super required
Destroyed            Pre-GC; minimal logic

CreateDefaultSubobject<T>()          Constructor — owned, serialized, editable
NewObject<T>() + RegisterComponent() Runtime — dynamic, not auto-serialized
SetupAttachment()                    Constructor parent declaration
AttachToComponent()                  Runtime attachment with transform rules

SpawnActor<T>()                      Standard spawn
SpawnActorDeferred<T>() + Finish     Configure before BeginPlay fires