unreal-engine-cpp-blueprints

name	unreal-engine-cpp-blueprints
description	Production guidance for Unreal Engine C++ and Blueprints hybrid architecture, UObject memory management, Unreal Smart Pointers, Gameplay Ability System (GAS), Subsystems, Task Graph multithreading, and performance optimization.

Unreal Engine C++ & Blueprints Architecture

This skill guide provides production-grade architectural patterns, memory management protocols, C++/Blueprint boundary rules, frame budget optimization techniques, and multi-threading patterns for Unreal Engine applications.

---

1. C++ vs. Blueprint Architectural Boundaries

1.1 Division of Responsibilities

To maintain performance and maintainability in large scale AAA codebases, follow strict layer isolation:

+-------------------------------------------------------------------+
|                        Blueprint Layer                            |
|  - Visual Tweaking & Cosmetic Properties (Materials, FX, Audio)   |
|  - UI Widget Event Hooks (UMG Data Bindings)                      |
|  - Level-Specific Scripting & Animation Blueprint Blending        |
+-------------------------------------------------------------------+
                                  ^
                                  | Exposes UPROPERTY / UFUNCTION
                                  v
+-------------------------------------------------------------------+
|                           C++ Engine Layer                        |
|  - Math & Heavy Computations (Spatial Queries, Pathing, Physics)  |
|  - Core Data Structures & Base Classes (ACharacter, UActorComponent)|
|  - Networking & RPC Serialization (Replication Logic)             |
|  - Subsystems, GAS AttributeSets, and Task Graph Multithreading   |
+-------------------------------------------------------------------+

1.2 Subsystem Architecture

Unreal Engine Subsystems (UGameInstanceSubsystem, UWorldSubsystem, ULocalPlayerSubsystem) provide managed singletons tied automatically to object lifecycles without manual instance creation or teardown.

1.3 Gameplay Ability System (GAS) Setup

Keep GAS core logic strictly in C++:

• UAbilitySystemComponent: Attach via base C++ classes (ACharacter).
• UAttributeSet: Define all attributes, clamping logic (PreAttributeChange, PostGameplayEffectExecute), and network replication macros in C++.
• UGameplayAbility: Implement complex execution calculations in C++; subclass in Blueprints only for montage timing and FX triggers.

---

2. Memory Management & Garbage Collection

2.1 UObject Ownership & UPROPERTY() GC Sweeps

Unreal Engine uses a reflection-driven Garbage Collection system. Any UObject raw pointer must be tracked by the GC framework, otherwise it risks premature collection or dangling pointer crashes.

// CRITICAL: Prevent GC sweep of instantiated UObject
UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Inventory")
TObjectPtr<UInventoryItemAsset> CachedItem;

2.2 Unreal Smart Pointers vs UObject Weak References

Pointer Type	Target Object Type	Use Case	GC Tracked?
TObjectPtr<T>	UObject subclasses	Standard member variables in headers.	Yes (UPROPERTY)
TWeakObjectPtr<T>	UObject subclasses	Non-owning reference to UObjects (prevents circular retention).	No (GC-safe query)
TSharedPtr<T>	Non-UObject C++ structs	Engine-agnostic C++ data structures.	Ref-counted
TSharedRef<T>	Non-UObject C++ structs	Non-nullable shared pointer reference.	Ref-counted
TUniquePtr<T>	Non-UObject C++ structs	Exclusive ownership raw C++ memory management.	Manual / Scope

2.3 Container Allocation Strategy & Slack Management

Unreal's TArray<T> dynamically reallocates memory upon expansion. Avoid heap fragmentation during execution loops:

// Reserve slack before populating large arrays
TArray<FVector> PathNodes;
PathNodes.Reserve(1000); // Allocates memory block upfront

// Fast clear without freeing allocated memory block for frame reuse
PathNodes.Reset(); // Keeps memory slack intact
// PathNodes.Empty(); // WRONG: Frees memory block to heap!

---

3. Frame Budget & Multithreading

3.1 Tick Management & Optimization Rules

By default, AActor::Tick is enabled, causing high overhead across thousands of actors.

1. Disable Unnecessary Ticks: Set PrimaryActorTick.bCanEverTick = false; in constructor.
2. Tick Interval: For non-critical logic, set PrimaryActorTick.TickInterval = 0.1f; (10Hz instead of frame-rate).
3. Tick Groups: Assign tick dependency groups (TG_PrePhysics, TG_DuringPhysics, TG_PostPhysics) to ensure data availability without frame stalls.

3.2 Threading with Task Graph & ParallelFor

For heavy compute tasks (e.g., procedural mesh generation, pathing algorithms), offload work from the Game Thread:

// Multi-threaded loop execution across CPU worker threads
ParallelFor(1000, [](int32 Index)
{
    // Thread-safe math operations on non-UObject data arrays
    ProcessRaycastPoint(Index);
});

---

4. Production Code Examples

4.1 Production UGameInstanceSubsystem with Async Soft Loading

A production manager tracking game state and asynchronously loading data assets using soft object references (TSoftObjectPtr):

InventorySubsystem.h

#pragma once

#include "CoreMinimal.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "Engine/StreamableManager.h"
#include "InventorySubsystem.generated.h"

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnItemLoadedDelegate, UPrimaryDataAsset*, LoadedAsset);

UCLASS()
class GAMEENGINE_API UInventorySubsystem : public UGameInstanceSubsystem
{
    GENERATED_BODY()

public:
    virtual void Initialize(FSubsystemCollectionBase& Collection) override;
    virtual void Deinitialize() override;

    UFUNCTION(BlueprintCallable, Category = "Inventory")
    void RequestAsyncAssetLoad(TSoftObjectPtr<UPrimaryDataAsset> AssetToLoad);

    UPROPERTY(BlueprintAssignable, Category = "Inventory")
    FOnItemLoadedDelegate OnItemLoaded;

private:
    void OnAssetLoadComplete(TSoftObjectPtr<UPrimaryDataAsset> LoadedSoftPtr);

    FStreamableManager StreamableManager;
};

InventorySubsystem.cpp

#include "InventorySubsystem.h"
#include "Engine/AssetManager.h"

void UInventorySubsystem::Initialize(FSubsystemCollectionBase& Collection)
{
    Super::Initialize(Collection);
}

void UInventorySubsystem::Deinitialize()
{
    Super::Deinitialize();
}

void UInventorySubsystem::RequestAsyncAssetLoad(TSoftObjectPtr<UPrimaryDataAsset> AssetToLoad)
{
    if (AssetToLoad.IsNull())
    {
        return;
    }

    if (AssetToLoad.IsValid())
    {
        // Already in memory
        OnItemLoaded.Broadcast(AssetToLoad.Get());
        return;
    }

    // Initiate async streamable load
    FSoftObjectPath AssetPath = AssetToLoad.ToSoftObjectPath();
    StreamableManager.RequestAsyncLoad(
        AssetPath,
        FStreamableDelegate::CreateUObject(this, &UInventorySubsystem::OnAssetLoadComplete, AssetToLoad)
    );
}

void UInventorySubsystem::OnAssetLoadComplete(TSoftObjectPtr<UPrimaryDataAsset> LoadedSoftPtr)
{
    if (LoadedSoftPtr.IsValid())
    {
        OnItemLoaded.Broadcast(LoadedSoftPtr.Get());
    }
}

4.2 Thread-Safe C++ Task Graph Execution

Scheduling background jobs using FFunctionGraphTask:

#include "Async/TaskGraphInterfaces.h"

void AGameSpatialGrid::ComputeGridAsync()
{
    // Capture data by value/shared ptr for thread safety
    TSharedPtr<TArray<FVector>, ESPMode::ThreadSafe> InputData = MakeShared<TArray<FVector>, ESPMode::ThreadSafe>();
    InputData->Reserve(5000);

    FFunctionGraphTask::CreateAndDispatchWhenReady([InputData]()
    {
        // Executed on Background Worker Thread
        for (int32 i = 0; i < 5000; ++i)
        {
            InputData->Add(FVector(i * 10.0f, i * 20.0f, 0.0f));
        }

        // Return back to Game Thread for application to UObjects
        FFunctionGraphTask::CreateAndDispatchWhenReady([InputData]()
        {
            // Executed back on Main Game Thread
            GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Green, 
                FString::Printf(TEXT("Async Compute Complete: %d elements"), InputData->Num()));
        }, TStatId(), nullptr, ENamedThreads::GameThread);

    }, TStatId(), nullptr, ENamedThreads::AnyBackgroundThreadNormalTask);
}

4.3 Robust C++ Base Class with Blueprint Native Events

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "InteractableInterface.h"
#include "BaseInteractable.generated.h"

UCLASS(Abstract, Blueprintable)
class GAMEENGINE_API ABaseInteractable : public AActor, public IInteractableInterface
{
    GENERATED_BODY()
    
public:	
    ABaseInteractable();

    // BlueprintNativeEvent provides C++ default implementation with Blueprint override capability
    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "Interaction")
    bool ExecuteInteraction(APawn* InteractingPawn);
    virtual bool ExecuteInteraction_Implementation(APawn* InteractingPawn);

protected:
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Interaction")
    FText InteractionPrompt;
};

---

5. Anti-Patterns & Critical Pitfalls

❌ Anti-Pattern 1: Un-Reflected UObject Raw Pointers

// WRONG: Missing UPROPERTY() causes Garbage Collector to delete object mid-gameplay
class AMyCharacter : public ACharacter
{
    UEnemyManager* EnemyManager; // Raw un-tracked pointer! DANGER!
};

// RIGHT: Always wrap with UPROPERTY() or TWeakObjectPtr
class AMyCharacter : public ACharacter
{
    UPROPERTY()
    TObjectPtr<UEnemyManager> EnemyManager;
};

❌ Anti-Pattern 2: Hard Object References in Class Headers

// WRONG: Hard asset references cause full dependency trees to load synchronously into memory
UPROPERTY(EditAnywhere)
UTexture2D* HeavyBossTexture; // Synchronously loaded on parent load!

// RIGHT: Use TSoftObjectPtr for lazy/async loading
UPROPERTY(EditAnywhere)
TSoftObjectPtr<UTexture2D> HeavyBossTexture;

❌ Anti-Pattern 3: Heavy Logic inside Blueprint Tick

Placing raycasts, string operations, or GetAllActorsOfClass in Blueprint Event Tick will ruin frame performance. Migrate heavy logic to C++ async tasks, custom timers (FTimerManager), or event-driven delegates.