AGENT SKILL

unreal-engine-cpp-blueprints

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.

License 许可
MIT
最近更新
2026-10-17
Stars
★ 8
Forks
1

01 前言 Front Matter

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.

03 SKILL.md 正文

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.

04 同仓库更多 Skills

hamzabellouch
hamzabellouch/agent-skills

security-audit

Comprehensive security guidance, source code audit, vulnerability assessment, and penetration test review for codebases, APIs, microservices, CLI tools, libraries, and LLM-backed applications. Triggers on requests to audit a codebase, conduct security reviews, find vulnerabilities or flaws, pen-test source code, or when the user asks in Arabic (فحص أمني، تدقيق الكود أمنياً، مراجعة الثغرات، فحص أمان المشروع). Supports Guidance mode (focused review) and Full Audit mode (deterministic 6-phase harness).

★ 8
hamzabellouch
hamzabellouch/agent-skills

malware-analysis-reversing

Production malware analysis workflows, reverse engineering methodologies, isolated sandbox triage, static/dynamic binary analysis, memory forensics, and YARA detection rule authoring.

★ 8
hamzabellouch
hamzabellouch/agent-skills

application-security-pentesting

Production Application Security (AppSec) standards, OWASP Top 10 vulnerability remediation, SAST/DAST pipeline integration, secure code review, threat modeling, and defensive security posture.

★ 8
hamzabellouch
hamzabellouch/agent-skills

oauth2-oidc-security-flows

Implement enterprise OAuth 2.1 and OpenID Connect (OIDC) authorization code flow with Proof Key for Code Exchange (PKCE), state and nonce verification, refresh token rotation, token revocation, and centralized IdP federation (Keycloak, Auth0, Okta). Trigger when building secure authentication, single sign-on (SSO), or third-party delegated authorization.

★ 8
hamzabellouch
hamzabellouch/agent-skills

jwt-session-management-hardening

Harden JWT-based authentication and session lifecycles using asymmetric signing (RS256/EdDSA), JWKS rotation, strict claims validation, Redis-backed sliding window sessions, revocation lists, and secure HttpOnly cookie storage. Trigger when implementing token validation, session revocation, or hardening API authentication.

★ 8
hamzabellouch
hamzabellouch/agent-skills

soc2-compliance-automation

Best practices for implementing SOC 2 Type II compliance controls, continuous evidence collection, infrastructure policy-as-code, and automated security monitoring. Use when automating Trust Services Criteria (Security, Availability, Confidentiality, Processing Integrity, Privacy), audit logging, IAM least privilege, or CI/CD security gates.

★ 8