icon안동민 개발노트

기본 헤더 파일과 매크로 이해하기

 언리얼 엔진 프로젝트에서 효율적인 C++ 개발을 위해서는 기본 헤더 파일과 매크로에 대한 이해가 필수적입니다.

 이 절에서는 주요 헤더 파일과 매크로들을 살펴보고 그 사용법과 중요성에 대해 알아보겠습니다.

주요 헤더 파일

 1. CoreMinimal.h

 CoreMinimal.h는 언리얼 엔진의 가장 기본적인 기능들을 포함하는 헤더 파일입니다.

  • 역할 : 기본 데이터 타입, 템플릿, 매크로 등 핵심 기능 제공
  • 사용 시기 : 대부분의 언리얼 C++ 클래스에서 기본적으로 포함
  • 예시
##include "CoreMinimal.h"
 
UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()
};

 2. Engine.h

 Engine.h는 언리얼 엔진의 주요 기능들을 포함하는 큰 헤더 파일입니다.

  • 역할 : 엔진의 대부분의 기능에 대한 헤더 포함
  • 사용 시기 : 엔진의 다양한 기능을 사용해야 할 때 (단, 컴파일 시간이 증가할 수 있음)
  • 예시
##include "Engine.h"
 
void AMyGameMode::StartPlay()
{
    Super::StartPlay();
    UGameplayStatics::GetAllActorsOfClass(GetWorld(), APlayerController::StaticClass(), FoundActors);
}

 3. 특정 기능 헤더

 특정 기능만 필요한 경우, 해당 기능의 헤더만 포함하는 것이 좋습니다.

  • 예 : GameFramework/Actor.h, Components/StaticMeshComponent.h
  • 사용 시기 : 특정 클래스나 기능만 필요할 때
  • 예시
##include "GameFramework/Actor.h"
##include "Components/StaticMeshComponent.h"
 
UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()
    
public:
    UPROPERTY(VisibleAnywhere)
    UStaticMeshComponent* Mesh;
};

주요 매크로

 1. UCLASS()

 UCLASS() 매크로는 클래스를 언리얼 엔진의 타입 시스템에 등록합니다.

  • 역할 : 리플렉션, 가비지 컬렉션, 직렬화 등의 기능 활성화
  • 사용법
UCLASS(Blueprintable, BlueprintType)
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()
};
  • 주요 지정자

 Blueprintable : 블루프린트로 상속 가능

 BlueprintType : 변수 타입으로 사용 가능

 Abstract : 추상 클래스 지정

 2. UPROPERTY()

 UPROPERTY() 매크로는 클래스의 멤버 변수를 언리얼 엔진의 프로퍼티 시스템에 등록합니다.

  • 역할 : 에디터 노출, 네트워크 리플리케이션, 직렬화 등의 기능 제공
  • 사용법
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Character Stats")
float Health;
  • 주요 지정자

 EditAnywhere: 인스턴스와 아키타입 모두에서 편집 가능

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

 Replicated: 네트워크 상에서 복제됨

 3. UFUNCTION()

 UFUNCTION() 매크로는 클래스의 멤버 함수를 언리얼 엔진의 함수 시스템에 등록합니다.

  • 역할 : 블루프린트 노출, RPC(Remote Procedure Call) 등의 기능 제공
  • 사용법 
    UFUNCTION(BlueprintCallable, Category="Character Actions")
void Attack();
  • 주요 지정자

 BlueprintCallable : 블루프린트에서 호출 가능

 Server : 서버에서만 실행

 NetMulticast : 모든 클라이언트에서 실행

 4. GENERATED_BODY()

 GENERATED_BODY() 매크로는 언리얼 헤더 툴(UHT)에 의해 생성되는 보일러플레이트 코드를 삽입합니다.

  • 역할 : 리플렉션, 직렬화 등에 필요한 메타데이터 및 도우미 함수 생성
  • 사용법 : 클래스 선언부 바로 아래에 위치
UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()
 
public:
    // 클래스 멤버들...
};

헤더 파일 관리와 매크로 사용 시 주의사항

 1. 최소한의 헤더 포함

  • 필요한 헤더만 포함하여 컴파일 시간 단축
  • 전방 선언(forward declaration) 활용

 2. 순환 의존성 방지

  • 헤더 파일 간 상호 포함 피하기
  • 인터페이스나 전방 선언 사용

 3. 프리컴파일드 헤더(PCH) 활용

  • 자주 사용되는 헤더를 PCH에 포함하여 컴파일 시간 단축

 4. 매크로 사용 시 일관성 유지

  • 프로젝트 전체에서 일관된 매크로 사용 규칙 적용

 5. UPROPERTY와 UFUNCTION의 적절한 사용

  • 필요한 경우에만 사용하여 불필요한 오버헤드 방지

효율적인 사용을 위한 팁

 1. 모듈별 헤더 조직화

  • 관련 헤더들을 모듈별로 그룹화하여 관리

 2. 언리얼 엔진 코딩 표준 준수

  • 언리얼 엔진의 명명 규칙과 코딩 스타일 가이드 따르기

 3. 자동 완성 활용

  • IDE의 자동 완성 기능을 활용하여 매크로와 지정자 입력 시 오류 방지

 4. 주석 활용

  • 복잡한 매크로 사용 시 주석으로 의도 명확히 설명

 5. 헤더 가드 사용

  • ##pragma once를 사용하여 중복 포함 방지

 언리얼 엔진의 헤더 파일과 매크로 시스템은 강력한 기능을 제공하지만 올바르게 사용하기 위해서는 주의와 이해가 필요합니다.

 기본 헤더 파일들의 역할을 이해하고 적절히 선택하여 사용함으로써 컴파일 시간을 최적화할 수 있습니다.

 또한, UCLASS, UPROPERTY, UFUNCTION 등의 매크로를 효과적으로 활용하면 언리얼 엔진의 강력한 리플렉션 시스템과 기타 기능들을 쉽게 활용할 수 있습니다.

 이러한 도구들을 잘 이해하고 사용하는 것은 효율적이고 유지보수가 용이한 언리얼 엔진 C++ 프로젝트를 개발하는 데 핵심적인 역할을 합니다.

이전으로다음으로