icon안동민 개발노트

UPROPERTY, UFUNCTION

 UPROPERTY와 UFUNCTION은 언리얼 엔진의 핵심 매크로로, 클래스의 속성과 함수를 엔진의 리플렉션 시스템에 등록하고 다양한 기능을 제공합니다.

UPROPERTY 매크로

 UPROPERTY 매크로는 클래스의 멤버 변수에 사용되며 다음과 같은 기능을 제공합니다.

  1. 에디터 노출
  2. 네트워크 리플리케이션
  3. 가비지 컬렉션
  4. 시리얼라이제이션

 기본 문법

UPROPERTY([specifier1, specifier2, ...])
Type VariableName;

 주요 Specifiers

 1. 에디터 노출 관련

  • EditAnywhere : 에디터의 모든 인스턴스에서 편집 가능
  • EditDefaultsOnly : 블루프린트 편집기에서만 편집 가능
  • EditInstanceOnly : 레벨에 배치된 인스턴스에서만 편집 가능
  • VisibleAnywhere : 읽기 전용으로 표시

 2. 블루프린트 관련

  • BlueprintReadWrite : 블루프린트에서 읽기/쓰기 가능
  • BlueprintReadOnly : 블루프린트에서 읽기만 가능

 3. 리플리케이션 관련

  • Replicated : 네트워크 상에서 복제됨
  • ReplicatedUsing=FunctionName : 복제 시 지정된 함수 호출

 4. 카테고리 및 메타데이터

  • Category="CategoryName" : 에디터에서의 분류
  • meta=(Key="Value") : 추가 메타데이터 지정

 예시

UCLASS()
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()
 
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stats")
    float Health;
 
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Components")
    UStaticMeshComponent* WeaponMesh;
 
    UPROPERTY(Replicated, BlueprintReadOnly, Category="Multiplayer")
    bool bIsInvincible;
};

UFUNCTION 매크로

 UFUNCTION 매크로는 클래스의 멤버 함수에 사용되며 다음과 같은 기능을 제공합니다.

  1. 블루프린트 노출
  2. 네트워크 RPC (Remote Procedure Call)
  3. 이벤트 시스템 연동

 기본 문법

UFUNCTION([specifier1, specifier2, ...])
ReturnType FunctionName(Parameters...);

 주요 Specifiers

 1. 블루프린트 관련

  • BlueprintCallable : 블루프린트에서 호출 가능
  • BlueprintPure : 사이드 이펙트 없는 순수 함수
  • BlueprintImplementableEvent : 블루프린트에서 구현 가능한 이벤트
  • BlueprintNativeEvent : C++에서 기본 구현을 제공하고 블루프린트에서 오버라이드 가능

 2. 네트워크 관련

  • Server : 서버에서 실행되는 함수
  • Client : 특정 클라이언트에서 실행되는 함수
  • NetMulticast : 모든 클라이언트에서 실행되는 함수

 3. 기타

  • Exec : 콘솔 명령어로 실행 가능한 함수
  • Category="CategoryName" : 블루프린트 에디터에서의 분류

 예시

UCLASS()
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()
 
public:
    UFUNCTION(BlueprintCallable, Category="Combat")
    void Attack();
 
    UFUNCTION(Server, Reliable, WithValidation)
    void ServerMove(FVector NewLocation);
 
    UFUNCTION(BlueprintImplementableEvent, Category="Events")
    void OnHealthChanged(float NewHealth);
 
    UFUNCTION(BlueprintNativeEvent, Category="Interaction")
    void Interact(AActor* OtherActor);
};

리플렉션 시스템과의 연관성

 UPROPERTY와 UFUNCTION 매크로는 언리얼 엔진의 리플렉션 시스템과 밀접하게 연관되어 있습니다.

 이 매크로들은 컴파일 시간에 언리얼 헤더 툴(UHT)에 의해 처리되어 리플렉션 정보를 생성합니다.

 이를 통해 런타임에 속성과 함수에 대한 메타데이터에 접근할 수 있게 됩니다.

for (TFieldIterator<FProperty> PropIt(GetClass()); PropIt; ++PropIt)
{
    FProperty* Property = *PropIt;
    UE_LOG(LogTemp, Log, TEXT("Property: %s"), *Property->GetName());
}

가비지 컬렉션 및 시리얼라이제이션

 UPROPERTY로 선언된 UObject 포인터는 자동으로 가비지 컬렉션 시스템에 의해 관리됩니다.

 또한 UPROPERTY로 선언된 변수들은 자동으로 시리얼라이제이션 과정에 포함됩니다.

UPROPERTY()
UObject* ManagedObject; // 가비지 컬렉션에 의해 관리됨
 
UObject* UnmanagedObject; // 가비지 컬렉션에 의해 관리되지 않음

효과적인 활용 방법

 1. 적절한 접근 제어

UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Components", meta=(AllowPrivateAccess="true"))
UStaticMeshComponent* MeshComponent;

 이 방식은 변수를 private으로 유지하면서도 에디터와 블루프린트에서 접근 가능하게 합니다.

 2. 조건부 편집

UPROPERTY(EditAnywhere, Category="Weapon", meta=(EditCondition="bHasWeapon"))
float WeaponDamage;

 bHasWeapon이 true일 때만 WeaponDamage를 편집할 수 있습니다.

 3. 커스텀 UFUCTION 파라미터

UFUNCTION(BlueprintCallable, Category="Inventory", meta=(ToolTip="Add item to inventory"))
void AddItem(UPARAM(ref) FInventoryItem& Item);

 UPARAM 매크로를 사용하여 함수 파라미터에 추가 정보를 제공할 수 있습니다.

주의사항

  1. 성능 고려 : UPROPERTY와 UFUNCTION은 약간의 오버헤드를 동반합니다. 성능이 중요한 경우 과도한 사용을 피해야 합니다.
  2. 네트워크 부하 : Replicated 속성과 RPC 함수는 네트워크 대역폭을 소비합니다. 필요한 경우에만 사용해야 합니다.
  3. 가시성 주의 : EditAnywhere와 같은 지정자를 사용할 때 의도치 않게 중요한 속성이 노출될 수 있으므로 주의해야 합니다.

Best Practices

 1. 명확한 카테고리 사용

  • 속성과 함수를 논리적인 카테고리로 그룹화하여 에디터에서의 가독성을 높입니다.

 2. 토글 가능한 기능

UPROPERTY(EditAnywhere, Category="Debug")
bool bShowDebugInfo;
 
UFUNCTION(BlueprintCallable, Category="Debug", meta=(DevelopmentOnly))
void ToggleDebugInfo();

 개발 중에만 사용되는 기능을 쉽게 토글할 수 있게 합니다.

 3. 문서화

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stats", meta=(ClampMin="0.0", ClampMax="100.0", ToolTip="Character's health between 0 and 100"))
float Health;

 ToolTip 메타 태그를 사용하여 속성과 함수에 대한 설명을 제공합니다.

 4. 유효성 검사

UFUNCTION(BlueprintCallable, Category="Inventory")
bool AddItem(UItem* Item);
 
UFUNCTION(BlueprintCallable, Category="Inventory")
int32 GetItemCount() const;

 함수의 반환 값을 통해 작업의 성공 여부나 현재 상태를 전달합니다.

 UPROPERTY와 UFUNCTION 매크로는 언리얼 엔진에서 C++ 코드와 엔진의 다양한 시스템(에디터, 네트워크, 블루프린트 등) 간의 상호작용을 가능하게 하는 핵심 도구입니다.

 이들을 효과적으로 활용함으로써 강력하고 유연한 게임플레이 시스템을 구축할 수 있습니다.

이전으로다음으로