ue-actor-component-architecture（ue actor 组件架构）

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 for the project's subsystem inventory, coding conventions, and any existing actor hierarchies or component patterns. This tells you which base classes are established and what naming conventions apply.

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 is a container that owns components. Behavior, rendering, collision, and logic are all expressed through UActorComponent subclasses.

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

AActor is a full UObject — never new/delete an actor. Always use SpawnActor and Destroy.

Actor Lifecycle

Full event order and safety rules are in references/actor-lifecycle.md. Key sequence:

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() returns nullptr on the CDO. Never access the world or other actors in the constructor.

// 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

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

Network lifecycle note

Replicated actors: on clients, BeginPlay may fire before all replicated properties arrive. Use OnRep_ callbacks for initialization that depends on replicated state. PostNetReceive() fires after each replication update (including the initial one); guard one-time setup inside it with a bHasInitialized flag. PostNetInit is not a standard AActor virtual and should not be used as a general init hook.

Component System

The three layers

Notable subclasses: UStaticMeshComponent, USkeletalMeshComponent, shape primitives (UCapsuleComponent, UBoxComponent, USphereComponent), UWidgetComponent (3D UI in world space — requires "UMG" module), USpringArmComponent + UCameraComponent, UChildActorComponent. See 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 are not automatically serialized unless you add them to a UPROPERTY array.

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 reads data that must be set before it runs.

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 creates GC pressure. Pool them: pre-spawn, hide + disable collision to "return," re-enable to "reuse."

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 (default, input/movement) → TG_DuringPhysics (physics-coupled logic, runs during physics step) → TG_PostPhysics (camera, IK) → TG_PostUpdateWork (final reads).

Component tick: Set PrimaryComponentTick.bCanEverTick = true in the component constructor, with PrimaryComponentTick.TickGroup for ordering — same API as actor tick.

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> scattered across your codebase.

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::. Skipping it breaks replication, GC, and Blueprint event forwarding.

// 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