[UE5] AActor 및 C++ 클래스 생성

AActor

AActor는 UObject를 확장(상속)한 클래스로 모든 액터의 베이스 클래스입니다.
StaticMeshActor나 CameraActor, PlayerStartActor가 액터입니다.

게임 플레이 코드(C++/BP)를 통해 월드에 생성 및 배치(Spawn) 할 수 있고, 소멸 또한 가능합니다.

실제 게임 세계에서 보이고 상호작용하는 캐릭터, 적 몬스터, 무기, 조명, 파티클 효과 등은 주로 AActor를 기반으로 제작합니다.

위치, 회전, 스케일과 같은 트랜스폼 정보를 가지고 있고, 여러 컴포넌트(메시, 파티클, 사운드)를 추가로 붙일 수 있습니다.

액터는 트랜스폼 데이터를 직접 저장하지 않고, 루트 컴포넌트에 대한 트랜스폼 데이터(있는 경우)를 대신 사용합니다.

AActor 생성

AActor를 상속 받는 새로운 C++ 클래스를 만들어 보겠습니다.

언리얼 에디터 상단 메뉴에서 “툴” > “새로운 C++ 클래스”를 선택합니다.

팝업 창이 뜨는데, 일반 클래스 탭에서 Actor를 선택한 뒤 다음 버튼을 누릅니다.

혹은 모든 클래스 탭에서 Actor를 검색하는 등 찾은 뒤 다음 버튼을 누릅니다.

그럼 창이 변경되며, 클래스 타입, 이름, 경로 등을 지정할 수 있습니다.
해당 부분을 원하는 대로 변경하며, 클래스 생성을 클릭하면 생성됩니다.

클래스 타입의 경우 다음과 같습니다.

Public으로 생성할 경우 .h가 Public 폴더에, .cpp가 Private 폴더에 생깁니다.
프로젝트의 다른 모듈에서 쉽게 #include할 수 있습니다.

Private로 생성할 경우 .h와 .cpp가 모두 Private 폴더에 저장됩니다.
해당 모듈에서만 접근 가능하게 되며 특정 로직이나 구현을 캡슐화해서 외부에 노출하고 싶지 않을 때 사용합니다.

잠시 후 자동 빌드가 진행되며, 완료 되면 비주얼 스튜디오에서 프로젝트가 변경되었다는 메시지가 뜰 수 있습니다.
여기서 Reload All을 선택합니다.

비주얼 스튜디오의 솔루션 탐색기를 살펴보면 다음과 같이 파일이 생성된 것을 확인 할 수 있습니다.
저의 경우 클래스 타입을 Public으로 설정했기 때문에 다음과 같은 구조가 됐습니다.

언리얼 에디터의 콘텐츠 브라우저에도 변화가 있는데, C++ 클래스 > 프로젝트명 폴더 아래에도 C++로 생성한 클래스가 나타나게 됩니다.

클래스 코드 구조 분석

언리얼 엔진에서 C++ 클래스를 새로 만들면, 일반적으로 헤더(.h)와 구현(.cpp)파일이 한 쌍으로 자동 생성됩니다.
여기에서 헤더와 구현부의 구조와 각 부분의 역할을 살펴보겠습니다.

.h

헤더의 상단 코드는 다음과 같습니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Item.generated.h"

#pragma once는 이 헤더 파일이 여러번 포함되더라도, 컴파일 시 단 한 번만 처리하도록 해주는 지시어입니다.

#include "CoreMinimal.h"은 언리얼 엔진에서 자주 사용하는 기본 타입(FString,TArray 등)과 매크로(UE_LOG등), 각종 유틸 함수들이 정의되어 있습니다.

#include "Item.generated.h"은 언리얼 엔진의 리플렉션 시스템에서 필요한 코드를 자동 생성하기 위한 매크로입니다.

헤더의 클래스 선언부 코드는 다음과 같습니다.

UCLASS()
class SPARTAPROJECT_API AItem : public AActor
{
	GENERATED_BODY()
	
public:	
	// 생성자
	AItem();

protected:
	// 액터가 월드에 배치된 후 시작시 한 번만 호출
	virtual void BeginPlay() override;

public:	
	// 매 프레임마다 자동으로 호출
	virtual void Tick(float DeltaTime) override;
};

UCLASS()는 이 클래스를 언리얼 엔진의 리플렉션 시스템에서 인식하도록 하는 매크로입니다.
언리얼 에디터에서 이 클래스를 블루프린트로 확장할 수 있게 하고, 에디터의 여러 기능과 연동하도록 합니다.

AItem : public AActor 부분은 AActor를 상속 받아 AItem를 정의한다는 의미입니다.

AItem은 Actor 계열이라는 의미에서 접두사 A가 붙습니다.
언리얼 엔진에서 클래스 이름에 점두사를 붙이는 컨벤션에 의해 붙습니다.
언리얼 엔진 코딩 표준/컨벤션

SPARTAPROJECT_API는 이 클래스를 모듈(여기서는 SpartaProject) 외부로 Export하기 위한 매크로입니다.
DLL 등으로 빌드할 때 필요한 선언입니다.

GENERATED_BODY()는 UCLASS()와 짝을 이루어, 엔진 리플렉션에 필요한 코드를 자동으로 생성해주는 매크로입니다.

AItem()는 생성자로 Actor객체가 메모리에 생성될 때 한 번 호출되며, 월드에 배치되기 전 단계일 수 있습니다.

BeginPlay()는 액터가 월드에 완전히 배치된 뒤, 게임이 플레이 상태로 시작 할 때 한 번 호출 됩니다.

Tick(float DeltaTime)은 매 프레임마다 자동으로 불리며, 주로 매 프레임 단위의 업데이트가 필요한 로직이 들어갑니다.

.cpp

// 자기 자신과 짝이 되는 헤더를 가장 먼저 include해야 함.
#include "Item.h"

// 생성자 구현부
AItem::AItem()
{
 	// 틱 함수가 매 프레임 작동되도록 하는 변수 값 설정입니다.
	PrimaryActorTick.bCanEverTick = true;
}

// BeginPlay() 구현부
void AItem::BeginPlay()
{
    // 부모 클래스(AActor)의 BeginPlay()를 먼저 호출
	Super::BeginPlay();
}

// Tick() 구현부
void AItem::Tick(float DeltaTime)
{
    // 부모 클래스(AActor)의 Tick() 먼저 호출
	Super::Tick(DeltaTime);
}

#include "Item.h"는 헤더 파일을 포함하는데, 다른 헤더 파일보다 가장 우선되어야 합니다.
그렇지 않을 경우 언리얼의 자동 생성 매크로(리플렉션)의 순서가 뒤섞여 컴파일 에러가 날 수 있습니다.

생성자 AItem()를 포함한 BeginPlay()와 Tick(float DeltaTime)같은 라이프사이클 관련 함수에서 구현 로직을 자유롭게 추가할 수 있습니다.

공식 문서

액터