DevCol (Development Collaboration)

파티클과 사운드로 게임 효과 연출하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Fri, 12 Jun 2026 17:03:12 +0900

파티클과 사운드로 게임 효과 연출하기

파티클 시각 효과 추가하기

1️⃣ 파티클 시스템 (Particla System) 기본 개념 이해하기

파티클 시스템이란?
- 파티클 시스템 (Particle System)은 게임 내에서 불꽃, 연기, 폭발, 먼지 등 다양한 시각적 효과를 구현하기 위한 도구입니다.
- 파티클은 다수의 작은 ‘입자’ (Particle)들이 모여 움직이면서 특정한 모양, 색상, 혹은 애니메이션 효과를 만들어냅니다.
- 언리얼 엔진에서는 파티클 시스템을 사용해 효과적인 VFX (Visual Effects) 를 구현할 수 있도록 풍부한 기능을 제공합니다.
Cascade vs. Niagara
- Cascade: 언리얼 엔진 3 시절부터 제공된 오래된 파티클 편집 툴입니다. 언리얼 엔진 4, 5에서도 여전히 호환되지만, 신규 기능 업데이트는 주로 Niagara 위주로 이루어지고 있습니다.
  - 초급자가 배우기에 상대적으로 간단하고 빠르게 결과를 볼 수 있음
  - 레거시 프로젝트나 기존 아티스트 툴체인에서 많이 사용
  - 복잡하거나 고급스러운 VFX 연출에는 한계
  - 아직까지 그래도 사용되는 부분이 꽤 있기 때문에 어느 정도 알고는 있어야 함.
- Niagara: 언리얼 엔진 4 후반부터 새롭게 도입된 차세대 파티클 시스템입니다. 언리얼 엔진 5에서는 Niagara가 공식적으로 권장되는 방식입니다.
  - 모듈 단위로 다양한 파티클 동작을 정교하게 제어 가능
  - 블루프린트나 머티리얼, 스크립팅과 유기적으로 연동되어 고급 VFX를 쉽게 만들 수 있음
  - GPU 파티클, 신규 기능 업데이트가 빠르게 적용
- 만약 언리얼 엔진을 처음 접하거나, 파티클 효과를 빠르게 만들어봐야 한다면 Cascade부터 익히는 것도 좋은 방법입니다. 하지만, 새 프로젝트를 계획 중이고 고급 이펙트를 구현하고 싶다면 Niagara 학습을 권장합니다.
이름 앞에 P_ 또는 Niagara_ 와 같은 접두어를 붙여두면, 프로젝트 내에서 파티클 에셋을 쉽게 구분할 수 있습니다.

나이아가라 UE 공식 문서: https://dev.epicgames.com/documentation/unreal-engine/getting-started-in-niagara-effects-for-unreal-engine?lang=ko

Getting Started in Niagara Effects for Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

This page collects all the getting started learning materials for Niagara.

dev.epicgames.com

캐스케이드 UE 공식 문서: https://dev.epicgames.com/documentation/unreal-engine/cascade-particle-editor-reference?application_version=4.27

Designing Visuals, Rendering, and Graphics with Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Rendering subsystem including lighting and shadowing, materials and textures, visual effects, and post processing in Unreal Engine.

dev.epicgames.com

2️⃣ 아이템 획득에 파티클 적용하기

모든 아이템은 상호작용 시 ActivateItem 함수를 실행하도로 설계를 했습니다. 여기에 파티클을 붙인다면 BaseItem을 상속받는 아이템들 모두에서 파티클을 설정할 수 있습니다.
또한, 파티클 이펙트가 발생한 후 2초 뒤 이펙트가 사라지도록 설정을 해야 합니다. 이 부분까지도 고려해서 꼼꼼하게 코드를 수정해 보도록 합시다.
빌드를 하고 에디터로 돌아가서, 파티클을 붙여줄 아이템 Blueprint를 (예를 들어, 지뢰 아이템) 열어봅니다. Details 창을 보면 Item 카테고리 아래에 Effects라는 카테고리가 생겼고, 여기서 파티클 이펙트를 설정할 수 있습니다. 리소스에 있는 파티클 중 맘에 드는 것으로 이펙트를 할당하고 컴파일 후 저장해 줍니다.
- 각 아이템에 파티클 & 사운드 추가해 줍시다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ItemInterface.h"  // 만들어둔 인터페이스 헤더 포함

#include "BaseItem.generated.h"

class USphereComponent;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API ABaseItem : public AActor, public IItemInterface
{
	GENERATED_BODY()
	
public:	
	// Sets default values for this actor's properties
	ABaseItem();

protected:
	// 아이템 유형(타입)을 편집 가능하게 지정
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
	FName ItemType;
	
	// 루트 컴포넌트 (씬)
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	USceneComponent* Scene;
	// 충돌 컴포넌트 (플레이어 진입 범위 감지용)
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	USphereComponent* Collision;
	// 아이템 시각 표현용 스태틱 메시
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	UStaticMeshComponent* StaticMesh;
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
	UParticleSystem* PickupParticle;
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
	USoundBase* PickupSound;
	
	virtual void OnItemOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex,
			bool bFromSweep,
			const FHitResult& SweepResult) override;
	
	virtual void OnItemEndOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex) override;
	
	virtual void ActivateItem(AActor* Activator) override;
	virtual FName GetItemType() const override;
	
	// 아이템을 제거하는 공통 함수 (추가 이펙트나 로직을 넣을 수 있음)
	virtual void DestroyItem();
	
private:
	const FName CollisionProfile_OverlapAllDynamic = TEXT("OverlapAllDynamic");

};

#include "BaseItem.h"
#include "Components/SphereComponent.h"
#include "Kismet/GameplayStatics.h"
#include "Particles/ParticleSystemComponent.h"


ABaseItem::ABaseItem()
{
	PrimaryActorTick.bCanEverTick = false;

	// 루트 컴포넌트 생성 및 설정
	Scene = CreateDefaultSubobject<USceneComponent>(TEXT("Scene"));
	SetRootComponent(Scene);

	// 충돌 컴포넌트 생성 및 설정
	Collision = CreateDefaultSubobject<USphereComponent>(TEXT("Collision"));
	// 겹침만 감지하는 프로파일 설정
	//Collision->SetCollisionProfileName(TEXT("OverlapAllDynamic"));
	Collision->SetCollisionProfileName(CollisionProfile_OverlapAllDynamic);
	// 루트 컴포넌트로 설정
	Collision->SetupAttachment(Scene);

	// 스태틱 메시 컴포넌트 생성 및 설정
	StaticMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("StaticMesh"));
	StaticMesh->SetupAttachment(Collision);
	// 메시가 불필요하게 충돌을 막지 않도록 하기 위해, 별도로 NoCollision 등으로 설정할 수 있음.

	// Overlap 이벤트 바인딩
	Collision->OnComponentBeginOverlap.AddDynamic(this, &ABaseItem::OnItemOverlap);
	Collision->OnComponentEndOverlap.AddDynamic(this, &ABaseItem::OnItemEndOverlap);
}

void ABaseItem::OnItemOverlap(
	UPrimitiveComponent* OverlappedComp,
	AActor* OtherActor,
	UPrimitiveComponent* OtherComp,
	int32 OtherBodyIndex,
	bool bFromSweep,
	const FHitResult& SweepResult)
{
	/*
	추가 팁: 인터페이스(Interface) 활용하기만약 플레이어뿐만 아니라 '데미지를 입을 수 있는 모든 대상'을 판별하고 싶다면, 
	Cast 대신 언리얼 인터페이스(UInterface)를 사용해 OtherActor->Implements<UMyDamageInterface>() 형태로 판별하는 것이 아키텍처 관점에서 훨씬 깔끔합니다.
	
	// 싱글 플레이어 게임이거나 0번 로컬 플레이어를 판별할 때 가장 간단하고 직관적인 방법입니다. 충돌한 액터가 현재 월드의 플레이어 폰과 같은지 메모리 주소를 직접 비교합니다.
	// 단점: 멀티플레이어 환경(다른 클라이언트의 플레이어 캐릭터)에서는 작동하지 않을 수 있습니다.
	if (OtherActor && OtherActor == GetWorld()->GetFirstPlayerController()->GetPawn())
	{		
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Blue, FString::Printf(TEXT("플레이어가 충돌했습니다!!!")));
	}  
	
	// 멀티플레이어 환경에서 적 플레이어, 아군 플레이어 구분 없이 '유저가 잡고 있는 캐릭터'를 모두 판별해 냅니다. 
	// AI 캐릭터(IsBotControlled)는 자동으로 걸러집니다.
	// #include "GameFramework/Pawn.h" // 다른 곳에서 선언된거랑 가능한한 여기서도 선언해두자
	if (OtherActor)
	{
		// 우선 APawn으로 캐스팅 (모든 캐릭터는 폰의 일종입니다)
		APawn* TouchedPawn = Cast<APawn>(OtherActor);
		
		// 폰이 맞고, 현재 플레이어 컨트롤러가 빙의(Possess)한 상태인지 확인
		if (TouchedPawn && TouchedPawn->IsPlayerControlled())
		{
			GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("플레이어가 조종 중인 액터입니다!!!")));
		}
	}	
	
	// 플레이어와 AI를 동시에 분기 처리하기
	// 하나의 충돌 함수 안에서 플레이어와 AI를 나누어 각각 다른 로직
	// (예: 플레이어면 UI 연출, AI면 데미지만 처리)을 실행하고 싶다면 다음과 같이 작성합니다.
	
	if (OtherActor)
	{
		APawn* TouchedPawn = Cast<APawn>(OtherActor);
			if (TouchedPawn)
			{
				if (TouchedPawn->IsPlayerControlled())
				{
					// 실제 플레이어 전용 로직
					UE_LOG(LogTemp, Log, TEXT("플레이어 충돌"));
				}
				else if (TouchedPawn->IsBotControlled())
				{
					//  AI 봇 전용 로직
					UE_LOG(LogTemp, Log, TEXT("AI 캐릭터 충돌"));
				}
			}
	}

	 */


	// OtherActor가 플레이어인지 확인 ("Player" 태그 활용)
	if (OtherActor && OtherActor->ActorHasTag("Player"))
	{
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Overlap!!!")));
		// 아이템 사용 (획득) 로직 호출
		ActivateItem(OtherActor);
	}
}

void ABaseItem::OnItemEndOverlap(
	UPrimitiveComponent* OverlappedComp,
	AActor* OtherActor,
	UPrimitiveComponent* OtherComp,
	int32 OtherBodyIndex)
{
}

void ABaseItem::ActivateItem(AActor* Activator)
{	
	
	//GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Overlap!!")));

	UParticleSystemComponent* Particle = nullptr;
	
	// PickupParticle == BP 에서 지정해둔 에셋
	if (PickupParticle)
	{
		Particle = UGameplayStatics::SpawnEmitterAtLocation(
			GetWorld(),
			PickupParticle,
			GetActorLocation(),
			GetActorRotation(),
			true
		);
	}

	if (PickupSound)
	{
		UGameplayStatics::PlaySoundAtLocation(
			GetWorld(),
			PickupSound,
			GetActorLocation()
		);
		
		/*FTimerHandle DestroyParticleTimerHandle;
		TWeakObjectPtr<UParticleSystemComponent> WeakParticle = Particle;

		GetWorld()->GetTimerManager().SetTimer(
			DestroyParticleTimerHandle,
			[WeakParticle]()
			{
			     if (WeakParticle.IsValid())
				{
					WeakParticle->DestroyComponent();
							
				}
			},
			2.0f,
			false
		);*/
		
		
	}
}

FName ABaseItem::GetItemType() const
{
	return ItemType;
}

void ABaseItem::DestroyItem()
{
	Destroy();
}

다른 아이템 클래스들의 ActivateItem 함수에 BaseItem 을 상속받는 코드도 추가해줘야 합니다.
- Super::ActivateItem(Activator);

예:

void AMineItem::ActivateItem(AActor* Activator)
{
	Super::ActivateItem(Activator);
	
	// ExplosionDelay 후 폭발 실행
	GetWorld()->GetTimerManager().SetTimer(ExplosionTimerHandle, this, &AMineItem::Explode, ExplosionDelay);
}

현재 Particle 들이 생성 후 안 사라지기 때문에 따로 관리를 해줘야 합니다.

UParticleSystemComponent* Particle = nullptr;
	
	if (ExplosionParticle)
	{
		Particle = UGameplayStatics::SpawnEmitterAtLocation(
			GetWorld(),
			ExplosionParticle,
			GetActorLocation(),
			GetActorRotation(),
			//true // 여기서 true 면 auto destroy 되어야하는데 안된다면, particle이 loop 형신인거라 다른 추가 조치를 해주어야 합니다.
			false // 그래서 loop 나 세밀한 조정을 원한경우 따로 destroy 구현합니다
		);
	}
	
	if (ExplosionSound)
	{		
		UGameplayStatics::PlaySoundAtLocation(
			GetWorld(),
			ExplosionSound,
			GetActorLocation(),
			GetActorRotation(),
			true 
		);
		
	}

하지만 여기서 만들어진 sound는 particle 과는 다르게 따로 destroy 안 해줍니다.

UGameplayStatics::PlaySoundAtLocation()로 재생한 사운드는 보통 따로 Destroy 해주지 않아도 되는 이유는 PlaySoundAtLocation()은 Fire and Forget 방식입니다.

즉,

“이 위치에서 이 소리 한 번 재생해 줘”
라고 엔진에 요청하고, 이후 관리는 엔진이 처리해요.

그래서 아이템 획득음, 폭발음처럼 짧게 한 번 재생되는 효과음은 따로 Destroy가 필요 없습니다.

그럼 언제 사운드를 직접 관리하나요?

다음 같은 경우에는 PlaySoundAtLocation()보다 AudioComponent를 사용하는 경우가 많아요.

배경음악처럼 오래 재생되는 사운드
중간에 Stop 해야 하는 사운드
볼륨을 실시간으로 조절해야 하는 사운드
루프 사운드
특정 Actor에 붙어서 따라다녀야 하는 사운드

이런 경우에는 SpawnSoundAtLocation() 또는 SpawnSoundAttached()로 컴포넌트를 받아서 관리할 수 있어요.

정리

현재 코드처럼 아이템 획득 사운드라면:

cpp

UGameplayStatics::PlaySoundAtLocation(
    GetWorld(),
    PickupSound,
    GetActorLocation()
);

이렇게만 해도 충분합니다.

반대로 파티클은 특히 Looping 파티클이면 화면에 계속 남을 수 있어서, 필요하면 타이머로 DestroyComponent()를 해주는 어야 합니다.

짧은 효과음은 자동 정리
루프 파티클이나 오래 남는 컴포넌트는 직접 정리 고려

Item 관련 C++ 클래스 코드들

BaseItem.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ItemInterface.h"  // 만들어둔 인터페이스 헤더 포함

#include "BaseItem.generated.h"

class USphereComponent;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API ABaseItem : public AActor, public IItemInterface
{
	GENERATED_BODY()
	
public:	
	// Sets default values for this actor's properties
	ABaseItem();

protected:
	// 아이템 유형(타입)을 편집 가능하게 지정
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
	FName ItemType;
	
	// 루트 컴포넌트 (씬)
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	USceneComponent* Scene;
	// 충돌 컴포넌트 (플레이어 진입 범위 감지용)
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	USphereComponent* Collision;
	// 아이템 시각 표현용 스태틱 메시
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	UStaticMeshComponent* StaticMesh;
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
	UParticleSystem* PickupParticle;
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
	USoundBase* PickupSound;
	
	virtual void OnItemOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex,
			bool bFromSweep,
			const FHitResult& SweepResult) override;
	
	virtual void OnItemEndOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex) override;
	
	virtual void ActivateItem(AActor* Activator) override;
	virtual FName GetItemType() const override;
	
	// 아이템을 제거하는 공통 함수 (추가 이펙트나 로직을 넣을 수 있음)
	virtual void DestroyItem();
	
private:
	const FName CollisionProfile_OverlapAllDynamic = TEXT("OverlapAllDynamic");

};

BaseItem.Cpp

#include "BaseItem.h"
#include "Components/SphereComponent.h"
#include "Kismet/GameplayStatics.h"
#include "Particles/ParticleSystemComponent.h"


ABaseItem::ABaseItem()
{
	PrimaryActorTick.bCanEverTick = false;

	// 루트 컴포넌트 생성 및 설정
	Scene = CreateDefaultSubobject<USceneComponent>(TEXT("Scene"));
	SetRootComponent(Scene);

	// 충돌 컴포넌트 생성 및 설정
	Collision = CreateDefaultSubobject<USphereComponent>(TEXT("Collision"));
	// 겹침만 감지하는 프로파일 설정
	//Collision->SetCollisionProfileName(TEXT("OverlapAllDynamic"));
	Collision->SetCollisionProfileName(CollisionProfile_OverlapAllDynamic);
	// 루트 컴포넌트로 설정
	Collision->SetupAttachment(Scene);

	// 스태틱 메시 컴포넌트 생성 및 설정
	StaticMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("StaticMesh"));
	StaticMesh->SetupAttachment(Collision);
	// 메시가 불필요하게 충돌을 막지 않도록 하기 위해, 별도로 NoCollision 등으로 설정할 수 있음.

	// Overlap 이벤트 바인딩
	Collision->OnComponentBeginOverlap.AddDynamic(this, &ABaseItem::OnItemOverlap);
	Collision->OnComponentEndOverlap.AddDynamic(this, &ABaseItem::OnItemEndOverlap);
}

void ABaseItem::OnItemOverlap(
	UPrimitiveComponent* OverlappedComp,
	AActor* OtherActor,
	UPrimitiveComponent* OtherComp,
	int32 OtherBodyIndex,
	bool bFromSweep,
	const FHitResult& SweepResult)
{
	/*
	추가 팁: 인터페이스(Interface) 활용하기만약 플레이어뿐만 아니라 '데미지를 입을 수 있는 모든 대상'을 판별하고 싶다면, 
	Cast 대신 언리얼 인터페이스(UInterface)를 사용해 OtherActor->Implements<UMyDamageInterface>() 형태로 판별하는 것이 아키텍처 관점에서 훨씬 깔끔합니다.
	
	// 싱글 플레이어 게임이거나 0번 로컬 플레이어를 판별할 때 가장 간단하고 직관적인 방법입니다. 충돌한 액터가 현재 월드의 플레이어 폰과 같은지 메모리 주소를 직접 비교합니다.
	// 단점: 멀티플레이어 환경(다른 클라이언트의 플레이어 캐릭터)에서는 작동하지 않을 수 있습니다.
	if (OtherActor && OtherActor == GetWorld()->GetFirstPlayerController()->GetPawn())
	{		
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Blue, FString::Printf(TEXT("플레이어가 충돌했습니다!!!")));
	}  
	
	// 멀티플레이어 환경에서 적 플레이어, 아군 플레이어 구분 없이 '유저가 잡고 있는 캐릭터'를 모두 판별해 냅니다. 
	// AI 캐릭터(IsBotControlled)는 자동으로 걸러집니다.
	// #include "GameFramework/Pawn.h" // 다른 곳에서 선언된거랑 가능한한 여기서도 선언해두자
	if (OtherActor)
	{
		// 우선 APawn으로 캐스팅 (모든 캐릭터는 폰의 일종입니다)
		APawn* TouchedPawn = Cast<APawn>(OtherActor);
		
		// 폰이 맞고, 현재 플레이어 컨트롤러가 빙의(Possess)한 상태인지 확인
		if (TouchedPawn && TouchedPawn->IsPlayerControlled())
		{
			GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("플레이어가 조종 중인 액터입니다!!!")));
		}
	}	
	
	// 플레이어와 AI를 동시에 분기 처리하기
	// 하나의 충돌 함수 안에서 플레이어와 AI를 나누어 각각 다른 로직
	// (예: 플레이어면 UI 연출, AI면 데미지만 처리)을 실행하고 싶다면 다음과 같이 작성합니다.
	
	if (OtherActor)
	{
		APawn* TouchedPawn = Cast<APawn>(OtherActor);
			if (TouchedPawn)
			{
				if (TouchedPawn->IsPlayerControlled())
				{
					// 실제 플레이어 전용 로직
					UE_LOG(LogTemp, Log, TEXT("플레이어 충돌"));
				}
				else if (TouchedPawn->IsBotControlled())
				{
					//  AI 봇 전용 로직
					UE_LOG(LogTemp, Log, TEXT("AI 캐릭터 충돌"));
				}
			}
	}

	 */


	// OtherActor가 플레이어인지 확인 ("Player" 태그 활용)
	if (OtherActor && OtherActor->ActorHasTag("Player"))
	{
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Overlap!!!")));
		// 아이템 사용 (획득) 로직 호출
		ActivateItem(OtherActor);
	}
}

void ABaseItem::OnItemEndOverlap(
	UPrimitiveComponent* OverlappedComp,
	AActor* OtherActor,
	UPrimitiveComponent* OtherComp,
	int32 OtherBodyIndex)
{
}

void ABaseItem::ActivateItem(AActor* Activator)
{	
	
	//GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Overlap!!")));

	
	UParticleSystemComponent* Particle = nullptr;
	
	// PickupParticle == BP 에서 지정해둔 에셋
	if (PickupParticle)
	{
		Particle = UGameplayStatics::SpawnEmitterAtLocation(
			GetWorld(),
			PickupParticle,
			GetActorLocation(),
			GetActorRotation(),
			true
		);
	}

	if (PickupSound)
	{
		UGameplayStatics::PlaySoundAtLocation(
			GetWorld(),
			PickupSound,
			GetActorLocation()
		);

	}
	
	if (Particle)
	{
		if (GEngine)
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("ActivateItem from Base Item")));
		
		FTimerHandle DestroyParticleTimerHandle;
		TWeakObjectPtr<UParticleSystemComponent> WeakParticle = Particle;

		GetWorld()->GetTimerManager().SetTimer(
			DestroyParticleTimerHandle,
			[WeakParticle]()
			{
				 if (WeakParticle.IsValid())
				 {
					 WeakParticle->DestroyComponent();
							
				 }
			 },
			 2.0f,
			 false
		 );
	}
}

FName ABaseItem::GetItemType() const
{
	return ItemType;
}

void ABaseItem::DestroyItem()
{
	Destroy();
	
	/*if (PickupParticle)
	{
		FTimerHandle DestroyParticleTimerHandle;
		
		GetWorld()->GetTimerManager().SetTimer(
			DestroyParticleTimerHandle,
			// lamda: 익명 함수 (이름이 없는 함수)
			// [ ] 일종의 캡쳐리스트 람다 싱행시 [ ] 안에 있는 (현재는 Particle) 변수를 바깥 스코프에서 값을 가져다가 
			// 사용할 수 있게 만드는 것.
			[Particle]()
			{
				Particle->DestroyComponent();
			},
			1.0f, // destroy time in sec
			false
		);
	}*/
}

MineItem.h

#pragma once

#include "CoreMinimal.h"
#include "BaseItem.h"
#include "MineItem.generated.h"


UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMineItem : public ABaseItem
{
	GENERATED_BODY()
	
public:
	AMineItem();
	
protected:
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Item|Component")
	USphereComponent* ExplosionCollision;
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
	UParticleSystem* ExplosionParticle;
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
	USoundBase* ExplosionSound;
	
	// 폭발까지 걸리는 시간
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Mine")
	float ExplosionDelay;
	
	// 폭발 범위
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Mine")
	float ExplosionRadius;

	// 폭발 데미지
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Mine")
	int ExplosionDamage;
	
	bool bHasExploded;
	// 지뢰 발동 여부
	FTimerHandle ExplosionTimerHandle;

	virtual void ActivateItem(AActor* Activator) override;
	
	void Explode();
	

private:
	
	const FName CollisionProfile_OverlapAllDynamic = TEXT("OverlapAllDynamic");
};

MineItem.cpp

#include "MineItem.h"
#include "Components/SphereComponent.h"
#include "Kismet/GameplayStatics.h"
#include "Particles/ParticleSystemComponent.h"

AMineItem::AMineItem()
{
	ExplosionDelay = 5.0f;
	ExplosionRadius = 300.0f;
	ExplosionDamage = 30.0f;
	ItemType = "Mine";
	bHasExploded = false;
    
	ExplosionCollision = CreateDefaultSubobject<USphereComponent>(TEXT("ExplosionCollision"));
	ExplosionCollision->InitSphereRadius(ExplosionRadius);
	//ExplosionCollision->SetCollisionProfileName(TEXT("OverlapAllDynamic")); 
	ExplosionCollision->SetCollisionProfileName(CollisionProfile_OverlapAllDynamic); 
	ExplosionCollision->SetupAttachment(Scene);
}

void AMineItem::ActivateItem(AActor* Activator)
{
	if (bHasExploded) return;
	
	
	Super::ActivateItem(Activator);
	
	// ExplosionDelay 후 폭발 실행
	GetWorld()->GetTimerManager().SetTimer(ExplosionTimerHandle, this, &AMineItem::Explode, ExplosionDelay);
	
	bHasExploded = true;
}

void AMineItem::Explode()
{
	UParticleSystemComponent* Particle = nullptr;
	
	if (GEngine)
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("ActivateItem Explode")));
	
	if (ExplosionParticle)
	{
		Particle = UGameplayStatics::SpawnEmitterAtLocation(
			GetWorld(),
			ExplosionParticle,
			GetActorLocation(),
			GetActorRotation(),
			//true // 여기서 true 면 auto destroy 되어야하는데 안된다면, particle이 loop 형신인거라 다른 추가 조치를 해주어야 합니다.
			false // 그래서 loop 나 세밀한 조정을 원한경우 따로 destroy 구현합니다
		);
	}
	
	if (ExplosionSound)
	{		
		UGameplayStatics::PlaySoundAtLocation(
			GetWorld(),
			ExplosionSound,
			GetActorLocation(),
			GetActorRotation(),
			true 
		);
		
	}
	
	TArray<AActor*> OverlappingActors;
	ExplosionCollision->GetOverlappingActors(OverlappingActors);

	for (AActor* Actor : OverlappingActors)
	{
		if (Actor && Actor->ActorHasTag("Player"))
		{
			GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("Player damaged %d by MineItem"), ExplosionDamage));
			
			// 데미지를 발생시켜 Actor->TakeDamage()가 실행되도록 함
			UGameplayStatics::ApplyDamage(
				Actor,                      // 데미지를 받을 액터
				ExplosionDamage,            // 데미지 양
				nullptr,                    // 데미지를 유발한 주체 (지뢰를 설치한 캐릭터가 없으므로 nullptr)
				this,                       // 데미지를 유발한 오브젝트(지뢰)
				UDamageType::StaticClass()  // 기본 데미지 유형
			);
			
			
		}
	}

	// 지뢰 제거
	DestroyItem();
	
	if (Particle)
	{
		if (GEngine)
		{
			GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("Particle destroyed wid delay %f"), ExplosionDelay));
		}
		
		FTimerHandle DestroyParticleTimerHandle;
		
		GetWorld()->GetTimerManager().SetTimer(
			DestroyParticleTimerHandle,
			// lamda: 익명 함수 (이름이 없는 함수)
			// [ ] 일종의 캡쳐리스트 람다 싱행시 [ ] 안에 있는 (현재는 Particle) 변수를 바깥 스코프에서 값을 가져다가 
			// 사용할 수 있게 만드는 것.
			[Particle]()
			{
				Particle->DestroyComponent();
			},
			
			
			ExplosionDelay,
			//1.0f, // destroy time in sec
			false
		);
	}
}

Debugging

문제: 게임 완성 후 테스팅 플레이 해봤는데 갑자기 게임이 크래쉬 해버렸다.

제일 큰 문제가 바로 플레이 중 갑자기 크래쉬 해버린다는 거다.. 그래서 무엇 때문인지 감을 못 잡았다.

해결 방법: 많은 Null Check

예상하기는 파티클 생성이랑 그거 해제 시 메모리 접근이 잘못돼서 그런 거 같다. 그래서 그런 쪽 코드에 다 Safety? (null check)을 걸었더니 해결되었다.

느낀 점: 조심해서 코드를 짜자!

확실히 언리얼 엔진이 무겁고 더 많이 신경 써서 다뤄야겠다고 배웠다.

유니티 엔진이서 이런 식으로 크래쉬 난적은 없었던 거 같은데 이게 내가 아직 C++ 이랑 언리얼이 익숙하지 못해서 그런 건가...

근데 이전에 언리얼 블루프린트 만들 때는 로직 고민 거의 없이 구현해보고 싶은 것들 생각대로 구현되고, 크래쉬도 안 나서 조금 들뜨기도 하고 쉽게 생각했는데... 정신 차리자...

그런데 걱정은 이렇게 작은 프로젝트에서 크래쉬 나는데... 조금 큰 거는 크래쉬 나면 디버깅 어떻게 하지....

완성된 모습

Youtube:https://youtu.be/DBJt9eXNTGU

현재 게임로직

총 3개의 스테이지(Level) 존재
아이템 랜덤 생성: Health Potion, Big & Small Coin, Mine
각 스테이지에 생성된 모든 Coin 획득 시 다음 스테이지로 이동
Level 올라갈 시 체력 Restore
시간 초과 혹은 체력이 0 이 되면 Game Over
3개의 스테이즈 다 클리어시 Game Complete

Github Link: https://github.com/devcol-main/BC_Ch3_Assignment_5/blob/main/README.md

BC_Ch3_Assignment_5/README.md at main · devcol-main/BC_Ch3_Assignment_5

Contribute to devcol-main/BC_Ch3_Assignment_5 development by creating an account on GitHub.

github.com

UI 애니메이션 효과 및 3D 위젯 UI 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Fri, 12 Jun 2026 09:09:07 +0900

UI 애니메이션 효과 및 3D 위젯 UI 구현하기

UI 애니메이션 효과 디자인하기

1️⃣ UMG와 Animation에 대해 이해하기

언리얼 엔진에서는 UI를 만들 때 주로 UMG (언리얼 모션 그래픽스, Unreal Motion Graphics)를 사용합니다. UMG에는 Animation 기능이 탑재되어 있어, 예를 들어 버튼이 클릭될 때 색이 바뀌거나, 텍스트가 화면 위로 등장했다가 사라지는 등 다양한 연출을 쉽게 구현할 수 있습니다.
Animation 패널
- UMG 에디터 내에서 메뉴 상단에서 Window - Animations를 클릭하면 애니메이션을 다루는 창이 뜹니다.
- UMG 에디터 왼쪽 하단 (기본 레이아웃 기준)에 위치한 패널입니다.
- 여기서 새 애니메이션을 생성하거나, 이미 만든 애니메이션을 선택해 타임라인을 확인할 수 있습니다.

Keyframe(키 프레임)
- 특정 시간대에 UI 속성(크기, 위치, 투명도, 색상 등)을 어떻게 바꿀지를 기록하는 지점입니다.
- 여러 개의 키 프레임을 연결하여 하나의 애니메이션 타임라인을 완성합니다.

UMG 위젯 애니메이팅 UE 공식 문서: https://dev.epicgames.com/documentation/unreal-engine/animating-umg-widgets-in-unreal-engine?lang=ko

Animating UMG Widgets in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

How to create animated UI elements in UMG in Unreal Engine.

dev.epicgames.com

UMG UI 디자이너 퀵스타트 가이드 UE 공식 문서: https://dev.epicgames.com/documentation/unreal-engine/umg-ui-designer-quick-start-guide-in-unreal-engine?lang=ko

UMG UI Designer Quick Start Guide in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Getting started with using Unreal Motion Graphics in Unreal Engine.

dev.epicgames.com

2️⃣ Text 위젯에 애니메이션 적용하기

이제 실제로 “Game Over” 텍스트를 사용해 화면에 서서히 떠올랐다가 사라지는 연출을 만들어 봅시다.
위젯 블루프린트 내에서 텍스트 배치하기
- WBP_MainMenu를 열어서 디자이너 화면에 TextBlock 하나를 추가해 이름을 GameOverText 라고 하고, 또 하나 TextBlock을 추가해 이름을 TotalScoreText 라고 합시다.
- 두 TextBlock 모두 기본 Text를 설정해줍니다. (Content - Text 카테고리에 입력)
- 평소에는 GameOverText와 TotalScoreText를 Hidden (또는 Opacity=0) 상태로 배치합니다.
- 이 텍스트가 게임 시작 시 바로 보이지 않도록, TextBlock의 Visibility를 Hidden 으로 설정해 둡니다. 우리는 애니메이션으로 텍스트를 천천히 보이게 할 것이므로, 기본 상태를 숨기는 편이 좋습니다.

애니메이션 트랙 생성
- 에디터 왼쪽 하단의 Animation 패널에서 + Animation 버튼을 클릭해 새 애니메이션을 만듭니다. “Anim_TimeOver” 라고 이름을 붙입니다.

아래쪽 타임라인 영역에서 Track을 추가할 수 있는데, 여기서 + Add 를 클릭하고 GameOverText를 선택합니다.

Keyframe (키 프레임) 설정
- 추가된 GameOverText에서 옆에 희미하게 보이는 + 버튼을 누르면 추가할 수 있는 트랙들이 있습니다. 여기서 Render Opacity (투명도)를 트랙에 추가하여, 이 값이 시간에 따라 어떻게 변하는지 기록할 수 있도록 설정합니다.
- 시간 바를 옮기면서 각각 Render Opacity 값을 변경하면 자동으로 트랙에 Key가 등록됩니다.

3️⃣ 애니메이션을 Blueprint 재생 함수로 묶어두기

우리는 이 애니메이션을 재생하기 위해서는 그 동안의 작성한 게임 로직들 즉, C++에서 UMG의 애니메이션 재생이라는 흐름이 필요합니다. C++에서 블루프린트의 함수를 호출해야하는 반대 상황인것입니다.
이벤트 그래프에서 PlayGameOverAnim Function을 만들어줍니다.
시작시 GameOverText을 visible로 처리하고, Play Animation을 연결합니다. 즉, “PlayTimeOverAnim”을 호출하면 “Anim_TimeOver” 애니메이션이 재생되도록 구성합니다.
애니메이션 재생이 끝나면 자연스럽게 점수가 뜰 수 있도록, TotalScoreText 를 visible 처리를 하도록 연결해줍니다.

게임 오버 UI 애니메이션 효과 추가하기

#include "MainPlayerController.h"
#include "EnhancedInputSubsystems.h"
#include "EnhancedInputSubsystems.h" // Enhanced Input System의 Local Player Subsystem을 사용하기 위해 포함
#include "MainGameState.h"
#include "MainGameInstance.h"
#include "Blueprint/UserWidget.h"
#include "Kismet/GameplayStatics.h"
#include "Components/TextBlock.h"

// 어차피 블루프린트 상에서 전부 다 초기화를 하기 때문에 여기서는 전부 다 nullptr 처리
AMainPlayerController::AMainPlayerController()
	: InputMappingContext(nullptr),
	  MoveAction(nullptr),
	  JumpAction(nullptr),
	  LookAction(nullptr),
	  SprintAction(nullptr),
	  HUDWidgetClass(nullptr),
	  HUDWidgetInstance(nullptr),
	  MainMenuWidgetClass(nullptr),
	  MainMenuWidgetInstance(nullptr)

{
}

void AMainPlayerController::BeginPlay()
{
	Super::BeginPlay();

	// GetLocalPlayer():현재 PlayerController에 연결된 Local Player 객체를 가져옴     
	// Local Player 는 그 플레이어의 입력이나 화면 뷰 같은 것을 관리하는 어떤 객체
	if (ULocalPlayer* LocalPlayer = GetLocalPlayer())
	{
		// Local Player에서 EnhancedInputLocalPlayerSubsystem을 획득
		// UEnhancedInputLocalPlayerSubsystem: 입력 시스템을 관리 (IMC 추가 혹은 삭제하는 역할)
		if (UEnhancedInputLocalPlayerSubsystem* Subsystem =
			LocalPlayer->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>())
		{
			if (InputMappingContext)
			{
				// Subsystem을 통해 우리가 할당한 IMC를 활성화
				// 우선순위(Priority)는 0이 가장 높은 우선순위
				Subsystem->AddMappingContext(InputMappingContext, 0);
			}
		}
	}

	FString CurrentMapName = GetWorld()->GetMapName();
	if (CurrentMapName.Contains("MenuLevel"))
	{
		ShowMainMenu(false);
	}


	/*// HUD 위젯 생성 및 표시
	if (HUDWidgetClass)
	{
		HUDWidgetInstance = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidgetInstance)
		{
			HUDWidgetInstance->AddToViewport();
		}
	}

	AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
	if (MainGameState)
	{
		MainGameState->UpdateHUD();
	}*/
}

UUserWidget* AMainPlayerController::GetHUDWidget() const
{
	return HUDWidgetInstance;
}


// 메뉴 UI 표시
void AMainPlayerController::ShowMainMenu(bool bIsRestart)
{
	// HUD가 켜져 있다면 닫기
	if (HUDWidgetInstance)
	{
		HUDWidgetInstance->RemoveFromParent();
		HUDWidgetInstance = nullptr;
	}

	// 이미 메뉴가 떠 있으면 제거
	if (MainMenuWidgetInstance)
	{
		MainMenuWidgetInstance->RemoveFromParent();
		MainMenuWidgetInstance = nullptr;
	}

	// 메뉴 UI 생성
	if (MainMenuWidgetClass)
	{
		MainMenuWidgetInstance = CreateWidget<UUserWidget>(this, MainMenuWidgetClass);
		if (MainMenuWidgetInstance)
		{
			MainMenuWidgetInstance->AddToViewport();

			bShowMouseCursor = true;
			SetInputMode(FInputModeUIOnly());
		}

		if (UTextBlock* ButtonText = Cast<UTextBlock>(
			MainMenuWidgetInstance->GetWidgetFromName(TEXT("StartButtonText"))))
		{
			if (bIsRestart)
			{
				ButtonText->SetText(FText::FromString(TEXT("Restart")));
				
				
			}
			else
			{
				ButtonText->SetText(FText::FromString(TEXT("Start")));
			}
		}
		
		if (bIsRestart)
		{
			UFunction* PlayAnimFunc = MainMenuWidgetInstance->FindFunction(FName("PlayGameOverAnim"));
			if (PlayAnimFunc)
			{
				MainMenuWidgetInstance->ProcessEvent(PlayAnimFunc, nullptr);
			}

			if (UTextBlock* TotalScoreText = Cast<UTextBlock>(MainMenuWidgetInstance->GetWidgetFromName("TotalScoreText")))
			{
				if (UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(UGameplayStatics::GetGameInstance(this)))
				{
					TotalScoreText->SetText(FText::FromString(
						FString::Printf(TEXT("Total Score: %i"), MainGameInstance->TotalScore)
					));
				}
			}
		}
	}
}

// 게임 HUD 표시
void AMainPlayerController::ShowGameHUD()
{
	// HUD가 켜져 있다면 닫기
	if (HUDWidgetInstance)
	{
		HUDWidgetInstance->RemoveFromParent();
		HUDWidgetInstance = nullptr;
	}

	// 이미 메뉴가 떠 있으면 제거
	if (MainMenuWidgetInstance)
	{
		MainMenuWidgetInstance->RemoveFromParent();
		MainMenuWidgetInstance = nullptr;
	}

	if (HUDWidgetClass)
	{
		HUDWidgetInstance = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidgetInstance)
		{
			HUDWidgetInstance->AddToViewport();

			bShowMouseCursor = false;
			SetInputMode(FInputModeGameOnly());

			AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
			if (MainGameState)
			{
				MainGameState->UpdateHUD();
			}
		}
	}
}

// 게임 시작 - BasicLevel 오픈, GameInstance 데이터 리셋
void AMainPlayerController::StartGame()
{
	if (UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(UGameplayStatics::GetGameInstance(this)))
	{
		MainGameInstance->CurrentLevelIndex = 0;
		MainGameInstance->TotalScore = 0;
	}

	UGameplayStatics::OpenLevel(GetWorld(), FName("BasicLevel"));
	SetPause(false);
}

WidgetComponent로 캐릭터 체력 표시하기

1️⃣ WidgetComponent 개념 이해하기

WidgetComponent란?
- UMG (언리얼 모션 그래픽스)로 만든 위젯 (텍스트, 이미지, 버튼 등)을 3D 월드에 붙일 수 있게 해주는 컴포넌트입니다.
  - 예: “NPC 머리 위 체력바”, “아이템 위에 ‘F 키를 누르세요’ 텍스트” 등이 가능해집니다.
- 언리얼 엔진에서 WidgetComponent를 사용하면, 2D로만 보이던 UI를 공간 내 특정 위치에 붙여 놓고, 카메라 각도에 따라 회전하거나 크기가 달라지는 모습을 만들 수 있습니다.
- WidgetComponent는 Actor에 부착(Attach)할 수 있는 컴포넌트이며, 특정 UUserWidget(UMG Blueprint 클래스)을 3D 상에 표시하게 해 줍니다.
  - 보통은 SetWidgetSpace(EWidgetSpace::World)로 설정하여, 월드 공간에 UI가 존재하게 만듭니다.
  - 초기 상태에서 SetVisibility(false)로 해 두고, 플레이어가 가까이 왔을 때 SetVisibility(true)로 변경하여 표시할 수 있습니다.

2️⃣ Widget Blueprint 준비하기

Contents Browser에서 UI - Widgets 폴더에서 우클릭하고 User Interface > Widget Blueprint로 Parent는 User Widget을 선택해서 새 위젯 블루프린트를 하나 만듭니다. 이름으로 WBP_HP 라고 하겠습니다.

3️⃣ Character 클래스에 WidgetComponent 추가하기

UI 는 보통 2D 인데 3D 화를 시켜서 사용할 경우 2가지 모드가 있습니다: 스크린 vs 월드
- 스크린: UI 가 화면에 고정 되어 있음. (플레이어의 카메라 방향과 상관없이 항상 정면에서 보인다)
- 월드: 월드의 캐릭터 움직임에 따라서 글씨도 같이 돌아가게 됩니다.
- 여기서는 스크린으로 하겠습니다: OverheadWidget->SetWidgetSpace(EWidgetSpace::Screen);

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Character.h"
#include "MainCharacter.generated.h"

// 미리 선언
// 전방 선언(Forward Declaration) 
class USpringArmComponent; // 스프링 암 관련 클래스 헤더
class UCameraComponent; // 카메라 관련 클래스 전방 선언
class UWidgetComponent;

// Enhanced Input에서 액션 값을 받을 때 사용하는 구조체
struct FInputActionValue;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainCharacter : public ACharacter
{
	GENERATED_BODY()

public:
	// Sets default values for this character's properties
	AMainCharacter();
	
	virtual void BeginPlay() override;
	
	
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Camera")
	USpringArmComponent* SpringArmComp  = nullptr;
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Camera")
	UCameraComponent* CameraComp = nullptr;
	
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "UI")
	UWidgetComponent* OverheadWidget = nullptr;
	
	// 현재 체력을 가져오는 함수
	UFUNCTION(BlueprintPure, Category = "Health")
	float GetHealth() const;
		
	// 체력을 회복시키는 함수
	UFUNCTION(BlueprintCallable, Category = "Health")
	void AddHealth(float Amount);
	
protected:
	
	// === Variables ===
	// 최대 체력
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Health")
	float  MaxHealth;
	// 현재 체력
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category = "Health")
	float  Health;
	
	// = Movements
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Movement")
	float NormalSpeed; // 기본 걷기 속도
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Movement")
	float SprintSpeedMultiplier;  // "기본 속도" 대비 몇 배로 빠르게 달릴지
	
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Movement")
	float SprintSpeed; 	// 실제 스프린트 속도 SprintSpeed= NormalSpeed * SprintSpeedMultiplier
	
	
	// =====	
	
	// Called to bind functionality to input
	virtual void SetupPlayerInputComponent(class UInputComponent* PlayerInputComponent) override;	
	
	UFUNCTION()
	void Move(const FInputActionValue& value);
	
	UFUNCTION()
	void Look(const FInputActionValue& value);
	
	// on off 의 형태의 것들은 그냥 나눠 주는 것이 좋다
	// 왜냐하면 이전에는 세세하게 처리하기가 상당이 까다로웠는데
	// EnhancedInputSystem은 그것들을 매우 편하게 변경해주었기 때문에 왠만하면 나눠 주는 것이 좋다
	UFUNCTION()
	void StartJump(const FInputActionValue& value);
	UFUNCTION()
	void StopJump(const FInputActionValue& value);
	
	UFUNCTION()
	void StartSprint(const FInputActionValue& value);
	UFUNCTION()
	void StopSprint(const FInputActionValue& value);
	
	
	// 사망 처리 함수 (체력이 0 이하가 되었을 때 호출)
	UFUNCTION(BlueprintCallable, Category = "Health")
	virtual void OnDeath();
	
	void UpdateOverheadHP();

	// 데미지 처리 함수 - 외부로부터 데미지를 받을 때 호출됨
	// 또는 AActor의 TakeDamage()를 오버라이드
	virtual float TakeDamage(
		float DamageAmount,
		struct FDamageEvent const& DamageEvent, // Damage 관련 추가 정보 (예: Skill 속성에 따른 반응) 
		AController* EventInstigator, //데미지를 발생 시킨 주체
		AActor* DamageCauser // 데미지를 일으킨 오브젝트
		) override;
	
};

#include "MainCharacter.h"
#include "EnhancedInputComponent.h"
//#include "InputActionValue.h"
#include "MainPlayerController.h"

// 카메라, 스프링 암 실제 구현이 필요한 경우라서 include
// 전방 선언(Forward Declaration) 한것 여기서 (실질적으로 사용하는곳) 포함
#include "Camera/CameraComponent.h"
#include "GameFramework/SpringArmComponent.h" 

//
#include "GameFramework/CharacterMovementComponent.h" // GetCharacterMovement() 사용을 위해
#include "GameFramework/Actor.h"
#include "Components/WidgetComponent.h"
#include "Components/TextBlock.h"
//#include "Kismet/GameplayStatics.h"

AMainCharacter::AMainCharacter()
{ 	
	PrimaryActorTick.bCanEverTick = false;	
	
	// (1) 스프링 암 생성
	SpringArmComp = CreateDefaultSubobject<USpringArmComponent>(TEXT("SpringArm"));
	// 스프링 암을 루트 컴포넌트 (CapsuleComponent)에 부착
	SpringArmComp->SetupAttachment(RootComponent);
	// 캐릭터와 카메라 사이의 거리 기본값 300으로 설정
	SpringArmComp->TargetArmLength = 300.0f;  
	// 컨트롤러 회전에 따라 스프링 암도 회전하도록 설정
	SpringArmComp->bUsePawnControlRotation = true;  
	
	
	//

	// (2) 카메라 컴포넌트 생성
	CameraComp = CreateDefaultSubobject<UCameraComponent>(TEXT("Camera"));
	// 스프링 암의 소켓 위치에 카메라를 부착
	CameraComp->SetupAttachment(SpringArmComp, USpringArmComponent::SocketName);
	// 카메라는 스프링 암의 회전을 따르므로 PawnControlRotation은 꺼둠
	CameraComp->bUsePawnControlRotation = false;
	
	OverheadWidget = CreateDefaultSubobject<UWidgetComponent>(TEXT("OverheadWidget"));
	OverheadWidget->SetupAttachment(GetMesh());
	OverheadWidget->SetWidgetSpace(EWidgetSpace::Screen);
	
	
	// Movements & Sprint Speed	
	NormalSpeed = 600.0f;
	SprintSpeedMultiplier = 1.75f;
	SprintSpeed = NormalSpeed * SprintSpeedMultiplier;

	
	// #include "GameFramework/CharacterMovementComponent.h" 추가해야함
	// MaxWalkSpeed 변경시 캐릭터 이동속도가 즉시 변경
	GetCharacterMovement()->MaxWalkSpeed = NormalSpeed;
	
	
	// 초기 체력 설정
	MaxHealth = 100.0f;
	Health = MaxHealth;
}

void AMainCharacter::BeginPlay()
{
	Super::BeginPlay();
	UpdateOverheadHP();
}

// Called to bind functionality to input
void AMainCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
	Super::SetupPlayerInputComponent(PlayerInputComponent);
	// Enhanced InputComponent로 캐스팅
    if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(PlayerInputComponent))
    {
        // IA를 가져오기 위해 현재 소유 중인 Controller를 AMainPlayerController로 캐스팅
        if (AMainPlayerController* PlayerController = Cast<AMainPlayerController>(GetController()))
        {
        	// null check
            if (PlayerController->MoveAction)
            {
                // IA_Move 액션 키를 "키를 누르고 있는 동안" Move() 호출
                EnhancedInput->BindAction(
                    PlayerController->MoveAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::Move
                );
            }
            
            if (PlayerController->JumpAction)
            {
                // IA_Jump 액션 키를 "키를 누르고 있는 동안" StartJump() 호출
                EnhancedInput->BindAction(
                    PlayerController->JumpAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::StartJump
                );
                
                // IA_Jump 액션 키에서 "손을 뗀 순간" StopJump() 호출
                EnhancedInput->BindAction(
                    PlayerController->JumpAction,
                    ETriggerEvent::Completed,
                    this,
                    &AMainCharacter::StopJump
                );
            }
            
            if (PlayerController->LookAction)
            {
                // IA_Look 액션 마우스가 "움직일 때" Look() 호출
                EnhancedInput->BindAction(
                    PlayerController->LookAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::Look
                );
            }
            
            if (PlayerController->SprintAction)
            {
                // IA_Sprint 액션 키를 "누르고 있는 동안" StartSprint() 호출
                EnhancedInput->BindAction(
                    PlayerController->SprintAction,
                    ETriggerEvent::Triggered,                   
                    this, 
                    &AMainCharacter::StartSprint
                );
                // IA_Sprint 액션 키에서 "손을 뗀 순간" StopSprint() 호출
                EnhancedInput->BindAction(
                    PlayerController->SprintAction, 
                    ETriggerEvent::Completed, 
                    this, 
                    &AMainCharacter::StopSprint
                );
            }    
        }
    }

}

void AMainCharacter::Move(const FInputActionValue& value)
{
	// 컨트롤러가 있어야 방향 계산이 가능
	if (!Controller) return;

	// Value는 Axis2D로 설정된 IA_Move의 입력값 (WASD)을 담고 있음
	// 예) (X=1, Y=0) → 전진 / (X=-1, Y=0) → 후진 / (X=0, Y=1) → 오른쪽 / (X=0, Y=-1) → 왼쪽
	const FVector2D MoveInput = value.Get<FVector2D>();

	// IsNearlyZero
	// 부동소수점들은 딱 0으로 안 떨어 질 수도 있기 때문에 작은 오차들은 0으로 처리 하기 위한 함수
	if (!FMath::IsNearlyZero(MoveInput.X))
	{		
		// 캐릭터가 바라보는 방향(정면)으로 X축 이동
		AddMovementInput(GetActorForwardVector(), MoveInput.X);
	}

	if (!FMath::IsNearlyZero(MoveInput.Y))
	{
		// 캐릭터의 오른쪽 방향으로 Y축 이동
		AddMovementInput(GetActorRightVector(), MoveInput.Y);
	}
}

void AMainCharacter::Look(const FInputActionValue& value)
{
	// 마우스의 X, Y 움직임을 2D 축으로 가져옴
	FVector2D LookInput = value.Get<FVector2D>();

	// X는 좌우 회전 (Yaw), Y는 상하 회전 (Pitch)
	// 좌우 회전
	AddControllerYawInput(LookInput.X);
	
	// 상하 회전
	// IA에서 반전해둔 상태
	// 여기엔 추후 변경 가능한 옵션 추가해주자
	AddControllerPitchInput(LookInput.Y);
}

void AMainCharacter::StartJump(const FInputActionValue& value)
{
	// Jump 함수는 Character가 기본 제공
	if (value.Get<bool>())
	{
		Jump();
	}
}
void AMainCharacter::StopJump(const FInputActionValue& value)
{	
	// StopJumping 함수도 Character가 기본 제공
	if (!value.Get<bool>())
	{
		StopJumping();
	}	
}

void AMainCharacter::StartSprint(const FInputActionValue& value)
{
	// Shift 키를 누른 순간 이 함수가 호출된다고 가정
	// 스프린트 속도를 적용
	if (GetCharacterMovement())
	{
		// 중간에 변경시 
		SprintSpeed = NormalSpeed * SprintSpeedMultiplier;		
		
		GetCharacterMovement()->MaxWalkSpeed = SprintSpeed;
	}

}
void AMainCharacter::StopSprint(const FInputActionValue& value)
{
	// Shift 키를 뗀 순간 이 함수가 호출
	// 평상시 속도로 복귀
	if (GetCharacterMovement())
	{
		GetCharacterMovement()->MaxWalkSpeed = NormalSpeed;
	}
}


float AMainCharacter::GetHealth() const
{
	return Health;
}

// 체력 회복 함수
void AMainCharacter::AddHealth(float  Amount)
{
	// 체력을 회복시킴. 최대 체력을 초과하지 않도록 제한함
	Health = FMath::Clamp(Health + Amount, 0.0f, MaxHealth);
	UpdateOverheadHP();
	//UE_LOG(LogTemp, Log, TEXT("Health increased to: %f"), Health);
	
	/*
	if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Green,
				 TEXT("Health Increased to: %f"), Health);
	}*/
}

// 데미지 처리 함수
float  AMainCharacter::TakeDamage(float  DamageAmount, FDamageEvent const& DamageEvent, AController* EventInstigator, AActor* DamageCauser)
{
	// 기본 데미지 처리 로직 호출 (필수는 아님)
	int32 ActualDamage = Super::TakeDamage(DamageAmount, DamageEvent, EventInstigator, DamageCauser);

	// 체력을 데미지만큼 감소시키고, 0 이하로 떨어지지 않도록 Clamp
	Health = FMath::Clamp(Health - DamageAmount, 0.0f, MaxHealth);
	UpdateOverheadHP();
	//UE_LOG(LogTemp, Warning, TEXT("Health decreased to: %f"), Health);
	/*if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Yellow,
				 TEXT("Health decreased to: %f"), Health);
	}
	*/

	// 체력이 0 이하가 되면 사망 처리
	if (Health <= 0.0f)
	{
		OnDeath();
	}

	// 실제 적용된 데미지를 반환
	return ActualDamage;
}

// 사망 처리 함수
void AMainCharacter::OnDeath()
{
	//UE_LOG(LogTemp, Error, TEXT("Character is Dead!"));
	if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Red,
				 TEXT("Character is Dead!"));
	}

	// 사망 후 로직
}

void AMainCharacter::UpdateOverheadHP()
{
	if (!OverheadWidget) return;
	
	UUserWidget* OverheadWidgetInstance = OverheadWidget->GetUserWidgetObject();
	if (!OverheadWidgetInstance) return;
	
	if (UTextBlock* HPText = Cast<UTextBlock>(OverheadWidgetInstance->GetWidgetFromName(TEXT("OverHeadHP"))))
	{
		HPText->SetText(FText::FromString(FString::Printf(TEXT("%.0f / %.0f"), Health, MaxHealth)));
	}
}

BP_MainCharacter 에 Overhead Widget이 잘 추가 되었습니다.

4️⃣ Character 클래스에서 WidgetComponent 위치 설정

BP_MainCharacter 클래스에 들어가서 User Interface 카테고리에서 Widget Class를 WBP_HP로 설정해줍니다.

WBP_HP 를 보면서 위치 조정 할때는 Space를 잠시 World로 하면 됩니다. (수정 후 Screen으로 하셔야 합니다)

5️⃣ 캐릭터 사망하였을 시 처리 로직 추가

#include "MainCharacter.h"
#include "EnhancedInputComponent.h"
//#include "InputActionValue.h"
#include "MainPlayerController.h"

// 카메라, 스프링 암 실제 구현이 필요한 경우라서 include
// 전방 선언(Forward Declaration) 한것 여기서 (실질적으로 사용하는곳) 포함
#include "Camera/CameraComponent.h"
#include "GameFramework/SpringArmComponent.h" 

//
#include "MainGameState.h"
#include "GameFramework/CharacterMovementComponent.h" // GetCharacterMovement() 사용을 위해
#include "GameFramework/Actor.h"
#include "Components/WidgetComponent.h"
#include "Components/TextBlock.h"
//#include "Kismet/GameplayStatics.h"

AMainCharacter::AMainCharacter()
{ 	
	PrimaryActorTick.bCanEverTick = false;	
	
	// (1) 스프링 암 생성
	SpringArmComp = CreateDefaultSubobject<USpringArmComponent>(TEXT("SpringArm"));
	// 스프링 암을 루트 컴포넌트 (CapsuleComponent)에 부착
	SpringArmComp->SetupAttachment(RootComponent);
	// 캐릭터와 카메라 사이의 거리 기본값 300으로 설정
	SpringArmComp->TargetArmLength = 300.0f;  
	// 컨트롤러 회전에 따라 스프링 암도 회전하도록 설정
	SpringArmComp->bUsePawnControlRotation = true;  
	
	
	//

	// (2) 카메라 컴포넌트 생성
	CameraComp = CreateDefaultSubobject<UCameraComponent>(TEXT("Camera"));
	// 스프링 암의 소켓 위치에 카메라를 부착
	CameraComp->SetupAttachment(SpringArmComp, USpringArmComponent::SocketName);
	// 카메라는 스프링 암의 회전을 따르므로 PawnControlRotation은 꺼둠
	CameraComp->bUsePawnControlRotation = false;
	
	OverheadWidget = CreateDefaultSubobject<UWidgetComponent>(TEXT("OverheadWidget"));
	OverheadWidget->SetupAttachment(GetMesh());
	OverheadWidget->SetWidgetSpace(EWidgetSpace::Screen);
	
	
	// Movements & Sprint Speed	
	NormalSpeed = 600.0f;
	SprintSpeedMultiplier = 1.75f;
	SprintSpeed = NormalSpeed * SprintSpeedMultiplier;

	
	// #include "GameFramework/CharacterMovementComponent.h" 추가해야함
	// MaxWalkSpeed 변경시 캐릭터 이동속도가 즉시 변경
	GetCharacterMovement()->MaxWalkSpeed = NormalSpeed;
	
	
	// 초기 체력 설정
	MaxHealth = 100.0f;
	Health = MaxHealth;
}

void AMainCharacter::BeginPlay()
{
	Super::BeginPlay();
	UpdateOverheadHP();
}

// Called to bind functionality to input
void AMainCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
	Super::SetupPlayerInputComponent(PlayerInputComponent);
	// Enhanced InputComponent로 캐스팅
    if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(PlayerInputComponent))
    {
        // IA를 가져오기 위해 현재 소유 중인 Controller를 AMainPlayerController로 캐스팅
        if (AMainPlayerController* PlayerController = Cast<AMainPlayerController>(GetController()))
        {
        	// null check
            if (PlayerController->MoveAction)
            {
                // IA_Move 액션 키를 "키를 누르고 있는 동안" Move() 호출
                EnhancedInput->BindAction(
                    PlayerController->MoveAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::Move
                );
            }
            
            if (PlayerController->JumpAction)
            {
                // IA_Jump 액션 키를 "키를 누르고 있는 동안" StartJump() 호출
                EnhancedInput->BindAction(
                    PlayerController->JumpAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::StartJump
                );
                
                // IA_Jump 액션 키에서 "손을 뗀 순간" StopJump() 호출
                EnhancedInput->BindAction(
                    PlayerController->JumpAction,
                    ETriggerEvent::Completed,
                    this,
                    &AMainCharacter::StopJump
                );
            }
            
            if (PlayerController->LookAction)
            {
                // IA_Look 액션 마우스가 "움직일 때" Look() 호출
                EnhancedInput->BindAction(
                    PlayerController->LookAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::Look
                );
            }
            
            if (PlayerController->SprintAction)
            {
                // IA_Sprint 액션 키를 "누르고 있는 동안" StartSprint() 호출
                EnhancedInput->BindAction(
                    PlayerController->SprintAction,
                    ETriggerEvent::Triggered,                   
                    this, 
                    &AMainCharacter::StartSprint
                );
                // IA_Sprint 액션 키에서 "손을 뗀 순간" StopSprint() 호출
                EnhancedInput->BindAction(
                    PlayerController->SprintAction, 
                    ETriggerEvent::Completed, 
                    this, 
                    &AMainCharacter::StopSprint
                );
            }    
        }
    }

}

void AMainCharacter::Move(const FInputActionValue& value)
{
	// 컨트롤러가 있어야 방향 계산이 가능
	if (!Controller) return;

	// Value는 Axis2D로 설정된 IA_Move의 입력값 (WASD)을 담고 있음
	// 예) (X=1, Y=0) → 전진 / (X=-1, Y=0) → 후진 / (X=0, Y=1) → 오른쪽 / (X=0, Y=-1) → 왼쪽
	const FVector2D MoveInput = value.Get<FVector2D>();

	// IsNearlyZero
	// 부동소수점들은 딱 0으로 안 떨어 질 수도 있기 때문에 작은 오차들은 0으로 처리 하기 위한 함수
	if (!FMath::IsNearlyZero(MoveInput.X))
	{		
		// 캐릭터가 바라보는 방향(정면)으로 X축 이동
		AddMovementInput(GetActorForwardVector(), MoveInput.X);
	}

	if (!FMath::IsNearlyZero(MoveInput.Y))
	{
		// 캐릭터의 오른쪽 방향으로 Y축 이동
		AddMovementInput(GetActorRightVector(), MoveInput.Y);
	}
}

void AMainCharacter::Look(const FInputActionValue& value)
{
	// 마우스의 X, Y 움직임을 2D 축으로 가져옴
	FVector2D LookInput = value.Get<FVector2D>();

	// X는 좌우 회전 (Yaw), Y는 상하 회전 (Pitch)
	// 좌우 회전
	AddControllerYawInput(LookInput.X);
	
	// 상하 회전
	// IA에서 반전해둔 상태
	// 여기엔 추후 변경 가능한 옵션 추가해주자
	AddControllerPitchInput(LookInput.Y);
}

void AMainCharacter::StartJump(const FInputActionValue& value)
{
	// Jump 함수는 Character가 기본 제공
	if (value.Get<bool>())
	{
		Jump();
	}
}
void AMainCharacter::StopJump(const FInputActionValue& value)
{	
	// StopJumping 함수도 Character가 기본 제공
	if (!value.Get<bool>())
	{
		StopJumping();
	}	
}

void AMainCharacter::StartSprint(const FInputActionValue& value)
{
	// Shift 키를 누른 순간 이 함수가 호출된다고 가정
	// 스프린트 속도를 적용
	if (GetCharacterMovement())
	{
		// 중간에 변경시 
		SprintSpeed = NormalSpeed * SprintSpeedMultiplier;		
		
		GetCharacterMovement()->MaxWalkSpeed = SprintSpeed;
	}

}
void AMainCharacter::StopSprint(const FInputActionValue& value)
{
	// Shift 키를 뗀 순간 이 함수가 호출
	// 평상시 속도로 복귀
	if (GetCharacterMovement())
	{
		GetCharacterMovement()->MaxWalkSpeed = NormalSpeed;
	}
}


float AMainCharacter::GetHealth() const
{
	return Health;
}

// 체력 회복 함수
void AMainCharacter::AddHealth(float  Amount)
{
	// 체력을 회복시킴. 최대 체력을 초과하지 않도록 제한함
	Health = FMath::Clamp(Health + Amount, 0.0f, MaxHealth);
	UpdateOverheadHP();
	//UE_LOG(LogTemp, Log, TEXT("Health increased to: %f"), Health);
	
	/*
	if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Green,
				 TEXT("Health Increased to: %f"), Health);
	}*/
}

// 데미지 처리 함수
float  AMainCharacter::TakeDamage(float  DamageAmount, FDamageEvent const& DamageEvent, AController* EventInstigator, AActor* DamageCauser)
{
	// 기본 데미지 처리 로직 호출 (필수는 아님)
	int32 ActualDamage = Super::TakeDamage(DamageAmount, DamageEvent, EventInstigator, DamageCauser);

	// 체력을 데미지만큼 감소시키고, 0 이하로 떨어지지 않도록 Clamp
	Health = FMath::Clamp(Health - DamageAmount, 0.0f, MaxHealth);
	UpdateOverheadHP();
	//UE_LOG(LogTemp, Warning, TEXT("Health decreased to: %f"), Health);
	/*if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Yellow,
				 TEXT("Health decreased to: %f"), Health);
	}
	*/

	// 체력이 0 이하가 되면 사망 처리
	if (Health <= 0.0f)
	{
		OnDeath();
	}

	// 실제 적용된 데미지를 반환
	return ActualDamage;
}

// 사망 처리 함수
void AMainCharacter::OnDeath()
{
	//UE_LOG(LogTemp, Error, TEXT("Character is Dead!"));
	/*if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Red,
				 TEXT("Character is Dead!"));
	}*/
	
	AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
	if (MainGameState)
	{
		MainGameState->OnGameOver();
	}
}

void AMainCharacter::UpdateOverheadHP()
{
	if (!OverheadWidget) return;
	
	UUserWidget* OverheadWidgetInstance = OverheadWidget->GetUserWidgetObject();
	if (!OverheadWidgetInstance) return;
	
	if (UTextBlock* HPText = Cast<UTextBlock>(OverheadWidgetInstance->GetWidgetFromName(TEXT("OverHeadHP"))))
	{
		HPText->SetText(FText::FromString(FString::Printf(TEXT("%.0f / %.0f"), Health, MaxHealth)));
	}
}

#include "MainGameState.h"
#include "MainGameInstance.h"
#include "MainPlayerController.h"
#include "Kismet/GameplayStatics.h"
#include "SpawnVolume.h"
#include "CoinItem.h"
#include "Components/TextBlock.h"
#include "Blueprint/UserWidget.h"

AMainGameState::AMainGameState()
{
	Score = 0;
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	LevelDuration = 3.0f; // 한 레벨당 30초
	CurrentLevelIndex = 0;
	MaxLevels = 3;
}

void AMainGameState::BeginPlay()
{
	Super::BeginPlay();

	// 게임 시작 시 첫 레벨부터 진행
	StartLevel();
	
	//UpdateHUD();
	
	GetWorldTimerManager().SetTimer(
			HUDUpdateTimerHandle,
			this,
			&AMainGameState::UpdateHUD,
			0.1f,
			true
		);
}

int32 AMainGameState::GetScore() const
{
	return Score;
}

void AMainGameState::AddScore(int32 Amount)
{
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			MainGameInstance->AddToScore(Amount);
		}
	}
}


void AMainGameState::StartLevel()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		if (AMainPlayerController* MainPlayerController = Cast<AMainPlayerController>(PlayerController))
		{
			MainPlayerController->ShowGameHUD();
		}
	}

	
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			CurrentLevelIndex = MainGameInstance->CurrentLevelIndex;
		}
	}

	// 레벨 시작 시, 코인 개수 초기화
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	// 현재 맵에 배치된 모든 SpawnVolume을 찾아 아이템 40개를 스폰
	TArray<AActor*> FoundVolumes;
	UGameplayStatics::GetAllActorsOfClass(GetWorld(), ASpawnVolume::StaticClass(), FoundVolumes);
	const int32 ItemToSpawn = 40;

	for (int32 i = 0; i < ItemToSpawn; i++)
	{
		if (FoundVolumes.Num() > 0)
		{
			ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
			if (SpawnVolume)
			{
				AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();
				// 만약 스폰된 액터가 코인 타입이라면 SpawnedCoinCount 증가
				if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
				{
					SpawnedCoinCount++;
				}
			}
		}
	}
	// 30초 후에 OnLevelTimeUp()가 호출되도록 타이머 설정
	GetWorldTimerManager().SetTimer(
		LevelTimerHandle,
		this,
		&AMainGameState::OnLevelTimeUp,
		LevelDuration,
		false
	);
	/*UE_LOG(LogTemp, Warning, TEXT("Level %d Start!, Spawned %d coin"),
	       CurrentLevelIndex + 1,
	       SpawnedCoinCount);*/
}

void AMainGameState::OnLevelTimeUp()
{
	// 시간이 다 되면 레벨을 종료
	EndLevel();
}

void AMainGameState::OnCoinCollected()
{
	CollectedCoinCount++;

	/*UE_LOG(LogTemp, Warning, TEXT("Coin Collected: %d / %d"),
	       CollectedCoinCount,
	       SpawnedCoinCount)*/

	// 현재 레벨에서 스폰된 코인을 전부 주웠다면 즉시 레벨 종료
	if (SpawnedCoinCount > 0 && CollectedCoinCount >= SpawnedCoinCount)
	{
		EndLevel();
	}
}

void AMainGameState::EndLevel()
{	
	
	// 타이머 해제
	GetWorldTimerManager().ClearTimer(LevelTimerHandle);
	// 다음 레벨 인덱스로
	//CurrentLevelIndex++;
	
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			AddScore(Score);
			CurrentLevelIndex++;
			MainGameInstance->CurrentLevelIndex = CurrentLevelIndex;
		}
	}

	// 모든 레벨을 다 돌았다면 게임 오버 처리
	if (CurrentLevelIndex >= MaxLevels)
	{
		OnGameOver();
		return;
	}

	// 레벨 맵 이름이 있다면 해당 맵 불러오기
	if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
	{
		UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
	}
	else
	{
		// 맵 이름이 없으면 게임오버
		OnGameOver();
	}
}

void AMainGameState::OnGameOver()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		if (AMainPlayerController* MainPlayerController = Cast<AMainPlayerController>(PlayerController))
		{
			MainPlayerController->SetPause(true);
			MainPlayerController->ShowMainMenu(true);
		}
	}
	
	//UpdateHUD();
	//UE_LOG(LogTemp, Warning, TEXT("Game Over!!"));
	
}

void AMainGameState::UpdateHUD()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		AMainPlayerController* MainPlayerController = Cast<AMainPlayerController>(PlayerController);
		{
			if (UUserWidget* HUDWidget = MainPlayerController->GetHUDWidget())
			{
				// requires
				// #include "Components/TextBlock.h"
				// #include "Blueprint/UserWidget.h"
				
				//추후 변경 방안 
				// UPROPERTY(meta = (BindWidget))
				// class UButton* MyAwesomeButton;
				if (UTextBlock* TimeText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Time"))))
				{
					float RemainingTime = GetWorldTimerManager().GetTimerRemaining(LevelTimerHandle);
					TimeText->SetText(FText::FromString(FString::Printf(TEXT("Time: %.1f"), RemainingTime)));
				}
				
				//
				if (UTextBlock* ScoreText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Score"))))
				{
					if (UGameInstance* GameInstance = GetGameInstance())
					{
						UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
						if (MainGameInstance)
						{
							ScoreText->SetText(FText::FromString(FString::Printf(TEXT("Score: %i"), MainGameInstance->TotalScore)));
						}
					}
				}
				
				if (UTextBlock* LevelIndexText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Level"))))
				{
					LevelIndexText->SetText(FText::FromString(FString::Printf(TEXT("Level: %d"), CurrentLevelIndex + 1)));
				}
			}
		}
	}
}

#include "MainPlayerController.h"
#include "EnhancedInputSubsystems.h"
#include "EnhancedInputSubsystems.h" // Enhanced Input System의 Local Player Subsystem을 사용하기 위해 포함
#include "MainGameState.h"
#include "MainGameInstance.h"
#include "Blueprint/UserWidget.h"
#include "Kismet/GameplayStatics.h"
#include "Components/TextBlock.h"

// 어차피 블루프린트 상에서 전부 다 초기화를 하기 때문에 여기서는 전부 다 nullptr 처리
AMainPlayerController::AMainPlayerController()
	: InputMappingContext(nullptr),
	  MoveAction(nullptr),
	  JumpAction(nullptr),
	  LookAction(nullptr),
	  SprintAction(nullptr),
	  HUDWidgetClass(nullptr),
	  HUDWidgetInstance(nullptr),
	  MainMenuWidgetClass(nullptr),
	  MainMenuWidgetInstance(nullptr)

{
}

void AMainPlayerController::BeginPlay()
{
	Super::BeginPlay();

	// GetLocalPlayer():현재 PlayerController에 연결된 Local Player 객체를 가져옴     
	// Local Player 는 그 플레이어의 입력이나 화면 뷰 같은 것을 관리하는 어떤 객체
	if (ULocalPlayer* LocalPlayer = GetLocalPlayer())
	{
		// Local Player에서 EnhancedInputLocalPlayerSubsystem을 획득
		// UEnhancedInputLocalPlayerSubsystem: 입력 시스템을 관리 (IMC 추가 혹은 삭제하는 역할)
		if (UEnhancedInputLocalPlayerSubsystem* Subsystem =
			LocalPlayer->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>())
		{
			if (InputMappingContext)
			{
				// Subsystem을 통해 우리가 할당한 IMC를 활성화
				// 우선순위(Priority)는 0이 가장 높은 우선순위
				Subsystem->AddMappingContext(InputMappingContext, 0);
			}
		}
	}

	FString CurrentMapName = GetWorld()->GetMapName();
	if (CurrentMapName.Contains("MenuLevel"))
	{
		ShowMainMenu(false);
	}


	/*// HUD 위젯 생성 및 표시
	if (HUDWidgetClass)
	{
		HUDWidgetInstance = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidgetInstance)
		{
			HUDWidgetInstance->AddToViewport();
		}
	}

	AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
	if (MainGameState)
	{
		MainGameState->UpdateHUD();
	}*/
}

UUserWidget* AMainPlayerController::GetHUDWidget() const
{
	return HUDWidgetInstance;
}


// 메뉴 UI 표시
void AMainPlayerController::ShowMainMenu(bool bIsRestart)
{
	// HUD가 켜져 있다면 닫기
	if (HUDWidgetInstance)
	{
		HUDWidgetInstance->RemoveFromParent();
		HUDWidgetInstance = nullptr;
	}

	// 이미 메뉴가 떠 있으면 제거
	if (MainMenuWidgetInstance)
	{
		MainMenuWidgetInstance->RemoveFromParent();
		MainMenuWidgetInstance = nullptr;
	}

	// 메뉴 UI 생성
	if (MainMenuWidgetClass)
	{
		MainMenuWidgetInstance = CreateWidget<UUserWidget>(this, MainMenuWidgetClass);
		if (MainMenuWidgetInstance)
		{
			MainMenuWidgetInstance->AddToViewport();

			bShowMouseCursor = true;
			SetInputMode(FInputModeUIOnly());
		}

		if (UTextBlock* ButtonText = Cast<UTextBlock>(
			MainMenuWidgetInstance->GetWidgetFromName(TEXT("StartButtonText"))))
		{
			if (bIsRestart)
			{
				ButtonText->SetText(FText::FromString(TEXT("Restart")));
				
				
			}
			else
			{
				ButtonText->SetText(FText::FromString(TEXT("Start")));
			}
		}
		
		if (bIsRestart)
		{
			UFunction* PlayAnimFunc = MainMenuWidgetInstance->FindFunction(FName("PlayGameOverAnim"));
			if (PlayAnimFunc)
			{
				MainMenuWidgetInstance->ProcessEvent(PlayAnimFunc, nullptr);
			}

			if (UTextBlock* TotalScoreText = Cast<UTextBlock>(MainMenuWidgetInstance->GetWidgetFromName("TotalScoreText")))
			{
				if (UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(UGameplayStatics::GetGameInstance(this)))
				{
					TotalScoreText->SetText(FText::FromString(
						FString::Printf(TEXT("Total Score: %i"), MainGameInstance->TotalScore)
					));
				}
			}
		}
	}
}

// 게임 HUD 표시
void AMainPlayerController::ShowGameHUD()
{
	// HUD가 켜져 있다면 닫기
	if (HUDWidgetInstance)
	{
		HUDWidgetInstance->RemoveFromParent();
		HUDWidgetInstance = nullptr;
	}

	// 이미 메뉴가 떠 있으면 제거
	if (MainMenuWidgetInstance)
	{
		MainMenuWidgetInstance->RemoveFromParent();
		MainMenuWidgetInstance = nullptr;
	}

	if (HUDWidgetClass)
	{
		HUDWidgetInstance = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidgetInstance)
		{
			HUDWidgetInstance->AddToViewport();

			bShowMouseCursor = false;
			SetInputMode(FInputModeGameOnly());

			AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
			if (MainGameState)
			{
				MainGameState->UpdateHUD();
			}
		}
	}
}

// 게임 시작 - BasicLevel 오픈, GameInstance 데이터 리셋
void AMainPlayerController::StartGame()
{
	if (UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(UGameplayStatics::GetGameInstance(this)))
	{
		MainGameInstance->CurrentLevelIndex = 0;
		MainGameInstance->TotalScore = 0;
	}

	UGameplayStatics::OpenLevel(GetWorld(), FName("BasicLevel"));
	SetPause(false);
}

0 Conclustion

게임 흐름에 맞춘 메뉴 UI 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Fri, 12 Jun 2026 05:57:31 +0900

게임 흐름에 맞춘 메뉴 UI 구현하기

게임 메뉴 UI 디자인하기

1️⃣ 메뉴 위젯 생성하고 버튼 추가하기

그동안은 게임 중에 나오는 위젯을 설계했다면, 이번에는 게임을 일시적으로 중단하고 시작하거나 종료하는 메뉴 위젯을 만들어보도록 하겠습니다.
Content Browser에서 UI - Widgets 폴더에서 마우스 우클릭 → User Interface → Widget Blueprint 선택합니다. 새로 생성되는 위젯의 이름은 WBP_MainMenu라고 지어 주세요.
더블 클릭하여 열면, 중앙에 Designer 탭, 오른쪽에 Details 탭, 왼쪽에는 Hierarchy & Palette가 보입니다.
Canvas Panel을 놓아서 기본적인 바탕을 마련합니다.
그 아래에 Border을 생성해서 바탕을 투명도를 주고 검정색 바탕화면으로 지정해줍니다. 그래서 게임 실행 시 레벨의 모습이 잘 보이지 않도록 설정합니다.
Common - Button 위젯을 각각 Start 버튼 하나만 Canvas Panel 아래에 둡니다. Button의 이름은 StartButton으로 변경해줍니다.
Alignment를 (0.5, 0.5)로 놓고 X, Y의 위치를 화면 크기의 절반으로 두면 가운데에 딱 배치될 수 있습니다.
혹은 그냥 Anchors 를 정 중앙으로 하면 됩니다. (Ctrl+Shift+ 원하는 Anchor 위치 선택하면 반영됩니다)
각 버튼마다 Common - Text를 끌어다 놓습니다. 왼쪽 하단에 Hierarchy창에 드래그 앤 드랍을 하면 편합니다. Text의 이름은 StartButtonText로 지정해줍니다.

2️⃣ 메뉴 레벨 생성하고 설정하기

흔히 게임 개발 시 메뉴 전용 맵을 만들어, 그 맵에서는 메뉴만 띄우도록 하고, 실제 게임이 시작되면 게임 레벨로 넘어가게 합니다.
이 방식을 쓰면 “Menu UI와 Game Level”이 완전히 분리되어, 구조가 좀 더 명확해집니다.
File - New Level 을 선택하고 Basic 템플릿으로 생성을 합니다. Maps 폴더에 MenuLevel이라는 이름으로 저장을 해줍니다.
- 단축키: Ctrl+N
Editor - Project Settings에 들어가서 Maps & Modes에서 Default Maps를 MenuLevel로 지정해서 저장해주도록 합니다.

게임 흐름 내에 메뉴 UI 배치하기

우선, 우리가 만든 이 메뉴 위젯 (WBP_MainMenu)을 다양한 상황에서 표시하고, 숨기고, 다시 띄우는 로직을 단계별로 구현해야 합니다.
1. 플레이 버튼을 누르면 Menu UI가 가장 먼저 뜨기
2. 게임 시작 시 자동으로 HUD를 띄우기
3. 메뉴가 나타날 때마다, UI 입력 모드로 전환하여 버튼 클릭에 집중하게 만드는 방식으로 수정
4. 게임이 종료되면 메뉴가 다시 뜨도록 만들기

1️⃣ PlayerController에 기본 위젯 오픈 함수 구현

위젯을 어디서 만들고 관리할지는 프로젝트마다 다른데, 일반적으로 PlayerController가 UI를 다루기 좋습니다. 게임 모드도 가능하지만, 멀티플레이를 고려하면 PlayerController가 UI 담당이 좀 더 자연스러운 편입니다.

게임 입력 vs UI 입력
- 게임 플레이 중 메뉴가 활성화되면, UI만 입력을 받도록 하거나, UI + 게임 둘 다 입력을 받도록 할 수 있습니다.
- 이때 UI에 마우스 포커스가 가도록 만들려면 SetInputMode 계열 함수를 사용해야 합니다. SetInputMode 계열 함수를 통해 PlayerController가 어느 입력을 우선으로 처리할지 결정합니다.
- UI 전용 입력 모드로 전환하면, 플레이어의 마우스 입력과 키 입력이 먼저 UI로 전달됩니다. 캐릭터 이동이나 시야 회전 등 게임 월드 입력은 잠시 비활성화되고, 버튼 클릭에 집중할 수 있습니다.
- FInputModeUIOnly 구조체 생성 → SetWidgetToFocus로 포커스할 UI 위젯 지정
- SetInputMode(InputMode) 호출 → 이제 마우스 클릭이나 키 입력이 UI를 먼저 처
- bShowMouseCursor = true로 마우스 커서를 보이게 설정
빌드한 후, BP_SpartaPlayerController 에서 MainMenuWidgetClass에 WBP_MainMenu 를 할당해줍니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/PlayerController.h"
#include "MainPlayerController.generated.h"

// Declaration
class UInputMappingContext; // IMC 관련 전방 선언
class UInputAction; // IA 관련 전방 선언


// Enhanced Input에서 액션 값을 받을 때 사용하는 구조체
struct FInputActionValue;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainPlayerController : public APlayerController
{
	GENERATED_BODY()

public:
	AMainPlayerController();

	// 에디터에서 세팅할 IMC
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputMappingContext* InputMappingContext;

	// IA
	// IA_Move를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* MoveAction;
	// IA_Jump를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* JumpAction;
	// IA_Look를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* LookAction;
	// IA_Sprint를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
	UInputAction* SprintAction;

	// UMG 위젯 클래스를 에디터에서 할당받을 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "HUD")
	TSubclassOf<UUserWidget> HUDWidgetClass;
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "HUD")
	UUserWidget* HUDWidgetInstance;

	UFUNCTION(BlueprintPure, Category = "HUD")
	UUserWidget* GetHUDWidget() const;

	// HUD 표시
	UFUNCTION(BlueprintCallable, Category = "HUD")
	void ShowGameHUD();


	// 메뉴 UI
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Menu")
	TSubclassOf<UUserWidget> MainMenuWidgetClass;
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Menu")
	UUserWidget* MainMenuWidgetInstance;

	// 메인 메뉴 표시
	UFUNCTION(BlueprintCallable, Category = "Menu")
	void ShowMainMenu(bool bIsRestart);
	// 게임 시작
	UFUNCTION(BlueprintCallable, Category = "Menu")
	void StartGame();

protected:
	virtual void BeginPlay() override;

	/*
	
	//UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input", meta=(AllowPrivateAccess="true"))
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
	UInputAction* ToggleInventoryAction;
	
	bool bIsInventoryOpen;
	
	UFUNCTION(BlueprintCallable)
	void ToggleInventory();
	
	void ActivateCharacterInput();
	void ActivateUIInput();
	*/
};

#include "MainPlayerController.h"
#include "EnhancedInputSubsystems.h"
#include "EnhancedInputSubsystems.h" // Enhanced Input System의 Local Player Subsystem을 사용하기 위해 포함
#include "MainGameState.h"
#include "MainGameInstance.h"
#include "Blueprint/UserWidget.h"
#include "Kismet/GameplayStatics.h"
#include "Components/TextBlock.h"

// 어차피 블루프린트 상에서 전부 다 초기화를 하기 때문에 여기서는 전부 다 nullptr 처리
AMainPlayerController::AMainPlayerController()
	: InputMappingContext(nullptr),
	  MoveAction(nullptr),
	  JumpAction(nullptr),
	  LookAction(nullptr),
	  SprintAction(nullptr),
	  HUDWidgetClass(nullptr),
	  HUDWidgetInstance(nullptr),
	  MainMenuWidgetClass(nullptr),
	  MainMenuWidgetInstance(nullptr)

{
}

void AMainPlayerController::BeginPlay()
{
	Super::BeginPlay();

	// GetLocalPlayer():현재 PlayerController에 연결된 Local Player 객체를 가져옴     
	// Local Player 는 그 플레이어의 입력이나 화면 뷰 같은 것을 관리하는 어떤 객체
	if (ULocalPlayer* LocalPlayer = GetLocalPlayer())
	{
		// Local Player에서 EnhancedInputLocalPlayerSubsystem을 획득
		// UEnhancedInputLocalPlayerSubsystem: 입력 시스템을 관리 (IMC 추가 혹은 삭제하는 역할)
		if (UEnhancedInputLocalPlayerSubsystem* Subsystem =
			LocalPlayer->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>())
		{
			if (InputMappingContext)
			{
				// Subsystem을 통해 우리가 할당한 IMC를 활성화
				// 우선순위(Priority)는 0이 가장 높은 우선순위
				Subsystem->AddMappingContext(InputMappingContext, 0);
			}
		}
	}

	// HUD 위젯 생성 및 표시
	if (HUDWidgetClass)
	{
		HUDWidgetInstance = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidgetInstance)
		{
			HUDWidgetInstance->AddToViewport();
		}
	}

	AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
	if (MainGameState)
	{
		MainGameState->UpdateHUD();
	}
}

UUserWidget* AMainPlayerController::GetHUDWidget() const
{
	return HUDWidgetInstance;
}


// 메뉴 UI 표시
void AMainPlayerController::ShowMainMenu(bool bIsRestart)
{
	// HUD가 켜져 있다면 닫기
	if (HUDWidgetInstance)
	{
		HUDWidgetInstance->RemoveFromParent();
		HUDWidgetInstance = nullptr;
	}

	// 이미 메뉴가 떠 있으면 제거
	if (MainMenuWidgetInstance)
	{
		MainMenuWidgetInstance->RemoveFromParent();
		MainMenuWidgetInstance = nullptr;
	}

	// 메뉴 UI 생성
	if (MainMenuWidgetClass)
	{
		MainMenuWidgetInstance = CreateWidget<UUserWidget>(this, MainMenuWidgetClass);
		if (MainMenuWidgetInstance)
		{
			MainMenuWidgetInstance->AddToViewport();

			bShowMouseCursor = true;
			SetInputMode(FInputModeUIOnly());
		}

		if (UTextBlock* ButtonText = Cast<UTextBlock>(
			MainMenuWidgetInstance->GetWidgetFromName(TEXT("StartButtonText"))))
		{
			if (bIsRestart)
			{
				ButtonText->SetText(FText::FromString(TEXT("Restart")));
			}
			else
			{
				ButtonText->SetText(FText::FromString(TEXT("Start")));
			}
		}
	}
}

// 게임 HUD 표시
void AMainPlayerController::ShowGameHUD()
{
	// HUD가 켜져 있다면 닫기
	if (HUDWidgetInstance)
	{
		HUDWidgetInstance->RemoveFromParent();
		HUDWidgetInstance = nullptr;
	}

	// 이미 메뉴가 떠 있으면 제거
	if (MainMenuWidgetInstance)
	{
		MainMenuWidgetInstance->RemoveFromParent();
		MainMenuWidgetInstance = nullptr;
	}

	if (HUDWidgetClass)
	{
		HUDWidgetInstance = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidgetInstance)
		{
			HUDWidgetInstance->AddToViewport();

			bShowMouseCursor = false;
			SetInputMode(FInputModeGameOnly());

			AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
			if (MainGameState)
			{
				MainGameState->UpdateHUD();
			}
		}
	}
}

// 게임 시작 - BasicLevel 오픈, GameInstance 데이터 리셋
void AMainPlayerController::StartGame()
{
	if (UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(UGameplayStatics::GetGameInstance(this)))
	{
		MainGameInstance->CurrentLevelIndex = 0;
		MainGameInstance->TotalScore = 0;
	}

	UGameplayStatics::OpenLevel(GetWorld(), FName("BasicLevel"));
}

2️⃣ GameState에서 게임 흐름에 따라 UI 호출

#include "MainGameState.h"
#include "MainGameInstance.h"
#include "MainPlayerController.h"
#include "Kismet/GameplayStatics.h"
#include "SpawnVolume.h"
#include "CoinItem.h"
#include "Components/TextBlock.h"
#include "Blueprint/UserWidget.h"

AMainGameState::AMainGameState()
{
	Score = 0;
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	LevelDuration = 30.0f; // 한 레벨당 30초
	CurrentLevelIndex = 0;
	MaxLevels = 3;
}

void AMainGameState::BeginPlay()
{
	Super::BeginPlay();

	// 게임 시작 시 첫 레벨부터 진행
	StartLevel();
	
	UpdateHUD();
	
	GetWorldTimerManager().SetTimer(
			HUDUpdateTimerHandle,
			this,
			&AMainGameState::UpdateHUD,
			0.1f,
			true
		);
}

int32 AMainGameState::GetScore() const
{
	return Score;
}

void AMainGameState::AddScore(int32 Amount)
{
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			MainGameInstance->AddToScore(Amount);
		}
	}
}


void AMainGameState::StartLevel()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		if (AMainPlayerController* SpartaPlayerController = Cast<AMainPlayerController>(PlayerController))
		{
			SpartaPlayerController->ShowGameHUD();
		}
	}

	
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			CurrentLevelIndex = MainGameInstance->CurrentLevelIndex;
		}
	}

	// 레벨 시작 시, 코인 개수 초기화
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	// 현재 맵에 배치된 모든 SpawnVolume을 찾아 아이템 40개를 스폰
	TArray<AActor*> FoundVolumes;
	UGameplayStatics::GetAllActorsOfClass(GetWorld(), ASpawnVolume::StaticClass(), FoundVolumes);
	const int32 ItemToSpawn = 40;

	for (int32 i = 0; i < ItemToSpawn; i++)
	{
		if (FoundVolumes.Num() > 0)
		{
			ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
			if (SpawnVolume)
			{
				AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();
				// 만약 스폰된 액터가 코인 타입이라면 SpawnedCoinCount 증가
				if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
				{
					SpawnedCoinCount++;
				}
			}
		}
	}
	// 30초 후에 OnLevelTimeUp()가 호출되도록 타이머 설정
	GetWorldTimerManager().SetTimer(
		LevelTimerHandle,
		this,
		&AMainGameState::OnLevelTimeUp,
		LevelDuration,
		false
	);
	/*UE_LOG(LogTemp, Warning, TEXT("Level %d Start!, Spawned %d coin"),
	       CurrentLevelIndex + 1,
	       SpawnedCoinCount);*/
}

void AMainGameState::OnLevelTimeUp()
{
	// 시간이 다 되면 레벨을 종료
	EndLevel();
}

void AMainGameState::OnCoinCollected()
{
	CollectedCoinCount++;

	/*UE_LOG(LogTemp, Warning, TEXT("Coin Collected: %d / %d"),
	       CollectedCoinCount,
	       SpawnedCoinCount)*/

	// 현재 레벨에서 스폰된 코인을 전부 주웠다면 즉시 레벨 종료
	if (SpawnedCoinCount > 0 && CollectedCoinCount >= SpawnedCoinCount)
	{
		EndLevel();
	}
}

void AMainGameState::EndLevel()
{	
	
	// 타이머 해제
	GetWorldTimerManager().ClearTimer(LevelTimerHandle);
	// 다음 레벨 인덱스로
	//CurrentLevelIndex++;
	
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			AddScore(Score);
			CurrentLevelIndex++;
			MainGameInstance->CurrentLevelIndex = CurrentLevelIndex;
		}
	}

	// 모든 레벨을 다 돌았다면 게임 오버 처리
	if (CurrentLevelIndex >= MaxLevels)
	{
		OnGameOver();
		return;
	}

	// 레벨 맵 이름이 있다면 해당 맵 불러오기
	if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
	{
		UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
	}
	else
	{
		// 맵 이름이 없으면 게임오버
		OnGameOver();
	}
}

void AMainGameState::OnGameOver()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		if (AMainPlayerController* SpartaPlayerController = Cast<AMainPlayerController>(PlayerController))
		{
			SpartaPlayerController->ShowMainMenu(true);
		}
	}
	
	//UpdateHUD();
	//UE_LOG(LogTemp, Warning, TEXT("Game Over!!"));
	
}

void AMainGameState::UpdateHUD()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		AMainPlayerController* MainPlayerController = Cast<AMainPlayerController>(PlayerController);
		{
			if (UUserWidget* HUDWidget = MainPlayerController->GetHUDWidget())
			{
				// requires
				// #include "Components/TextBlock.h"
				// #include "Blueprint/UserWidget.h"
				
				//추후 변경 방안 
				// UPROPERTY(meta = (BindWidget))
				// class UButton* MyAwesomeButton;
				if (UTextBlock* TimeText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Time"))))
				{
					float RemainingTime = GetWorldTimerManager().GetTimerRemaining(LevelTimerHandle);
					TimeText->SetText(FText::FromString(FString::Printf(TEXT("Time: %.1f"), RemainingTime)));
				}
				
				//
				if (UTextBlock* ScoreText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Score"))))
				{
					if (UGameInstance* GameInstance = GetGameInstance())
					{
						UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
						if (MainGameInstance)
						{
							ScoreText->SetText(FText::FromString(FString::Printf(TEXT("Score: %i"), MainGameInstance->TotalScore)));
						}
					}
				}
				
				if (UTextBlock* LevelIndexText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Level"))))
				{
					LevelIndexText->SetText(FText::FromString(FString::Printf(TEXT("Level: %d"), CurrentLevelIndex + 1)));
				}
			}
		}
	}
}

3️⃣ Start 버튼 클릭 이벤트에 함수 바인딩

BP_MainPlayerController Setting:Menu -> WBP_MainMenu

Designer 탭에서 StartButton 버튼을 선택하고, Details 패널에서 맨 위쪽에 버튼 이름을 지정해주는 부분이 있습니다. 그 옆에 Is Variable에 체크를 해줍니다. 그러면 맨 하단에 Events 들이 활성화되는 것을 볼 수 있습니다.

WBP_MainMenu Setting:

Buttion set Is Variable true
OnClicked

UI 위젯 설계와 실시간 데이터 연동하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Fri, 12 Jun 2026 04:17:42 +0900

UI 위젯 설계와 실시간 데이터 연동하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

UMG (User Widget) 위젯 기초 디자인 이해하기

1️⃣ HUD (Heads-Up Display)란?

HUD는 게임 내에서 플레이어에게 정보를 제공하기 위한 화면을 말합니다. 일반적으로 게임 중 화면의 일부에 배치되며, 플레이어가 현재 게임 상황을 이해하는 데 필요한 체력, 미니맵, 퀘스트 업데이트와 같은 데이터를 제공합니다.
언리얼 엔진에서는 다음과 같은 HUD 시스템이 있습니다.
1. Canvas 기반 HUD:
  - AHUD 클래스를 상속하여 구현
  - 기본적인 2D 그리기 작업(텍스트, 이미지 등) 가능
  - 레거시 방식으로 간주되며, 간단한 HUD에 적합
2. UMG (Unreal Motion Graphics):
  - 언리얼 엔진의 Widget Blueprint를 이용한 UI 시스템
  - 더 직관적이고 강력한 HUD 디자인 가능
  - 다양한 위젯(Text, Button, Image 등)을 사용하여 HUD를 제작
우리는 여기서 UMG 방식을 따르도록 합니다.

유저 인터페이스 및 HUD 관련 UE 공식 문서: https://dev.epicgames.com/documentation/unreal-engine/user-interfaces-and-huds-in-unreal-engine?lang=ko

User Interfaces and HUDs in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Guides and information for artists and programmers creating user interfaces such as menus and HUDs in Unreal Engine

dev.epicgames.com

UMG UI 디자이너 퀵스타트 가이드 UE 공식 문서: https://dev.epicgames.com/documentation/unreal-engine/umg-ui-designer-quick-start-guide-in-unreal-engine?lang=ko

UMG UI Designer Quick Start Guide in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Getting started with using Unreal Motion Graphics in Unreal Engine.

dev.epicgames.com

2️⃣ 위젯 블루프린트 (Widget Blueprint)란?

Widget Blueprint란?
- 언리얼 엔진에서 UI (User Interface)를 시각적으로 설계할 수 있도록 제공되는 에디터용 블루프린트입니다.
- 개발자는 이 블루프린트 안에서 Text Block, Button, Image 등 다양한 UI 요소를 드래그 앤 드롭으로 간편하게 배치할 수 있습니다.
- 이렇게 만든 Widget Blueprint는 게임 화면에 표시되는 UI가 됩니다.
Widget Blueprint 생성 경로
- Content Browser에서 Contents 하위에 UI 폴더를 만들고, 그 하위에 또 Widget 폴더를 만듭니다.
- Widget 폴더에서 우클릭하고 User Interface - Widget Blueprint를 선택하고 부모 클래스로 User Widget을 선택해 줍니다. 그리고 WBP_HUD 라는 이름으로 생성합니다.

Widget Blueprint 열기
- 생성된 위젯을 더블 클릭하면, 오른쪽 상단에 Designer 탭과 Graph 탭이 있는 것을 확인할 수 있습니다.
  - Designer 탭: UI를 배치하는 공간입니다.
  - Graph 탭: 블루프린트 이벤트 그래프(로직)을 작성하는 공간입니다.

3️⃣ UI 요소 (UI Elements)란?

UI Elements (UI 요소)란?
- 언리얼 엔진에서 제공하는 다양한 UI 구성 요소를 말합니다. 왼쪽 상단에 보면 Palette 탭이 있으며, 여기에는 다양한 UI 요소들을 제공합니다.
- 예를 들어, Text Block (텍스트 표시용), Button (버튼), Progress Bar (게이지 표시) 등이 있습니다.
  - Text Block: 캐릭터 체력, Score(점수), Time(남은 시간) 등 텍스트를 보여줄 때
  - Button: “Start Game”, “Quit Game” 등 클릭 이벤트가 필요한 메뉴 버튼
  - Progress Bar: 체력 게이지나 로딩 게이지 등을 시각적으로 표시할 때

4️⃣ 점수, 시간, 레벨 표시를 위한 UI Widget 디자인하기

Widget Blueprint의 Designer 탭에서 배치

마우스로 드래그 앤 드롭하여 원하는 위치에 배치할 수 있습니다. Details 패널에서 해당 요소의 크기, 색상, 폰트, 정렬 방식 등을 원하는 대로 수정할 수 있습니다.
우선, Palette에서 Panel 중 Canvas Panel을 찾아서 클릭합니다. Canvas Panel은 모든 UI 요소를 포함할 수 있는 “큰 도화지” 같은 역할을 합니다. UI 요소들을 자유롭게 배치할 수 있는 가장 기본적인 레이아웃 패널이기도 합니다.
Canvas Panel을 드래그 앤 드롭하여 Designer Tab에 끌어다 놓습니다. 그러면 왼쪽 아래 Hierarchy 탭을 보면 Canvas Panel이 가장 루트로 생성된 것을 확인할 수 있습니다.
오른쪽 상단에 보면, Screen Size를 결정할 수 있는 부분이 있는데 여기서 가장 대중적인 화면 크기인 1920 x 1080 (16:9 Full HD) 사이즈로 설정하기 선택해줍니다.(구버전은 21.5-24" monitor 라고 나옵니다)

다음으로 Palette에서 Common 리스트 중에서 Text를 선택 → Canvas Panel 위로 드래그 앤 드롭합니다

원하는 Font 에셋 만들기
- 우리는 폰트 스타일을 적용하기 위해서는 콘텐츠 폴더에 Font를 import 해야합니다. 미리 .ttf나 .otf 확장자를 가진 폰트 파일을 다운로드 받습니다.
- Contents - UI - Fonts 폴더를 미리 만들어둡니다.
- 마우스 우클릭 → Import to ‘/Game/UI/Fonts’를 클릭하면 파일 선택 창에서 .ttf나 .otf 폰트 파일을 선택하면, 언리얼 엔진 내로 임포트가 진행됩니다.
- 임포트가 완료되면, 콘텐츠 브라우저에 새로운 폰트 에셋이 생깁니다.
- 이렇게 생성된 Font Asset을 Font Family를 지정할 때 이 에셋을 적용할 수 있습니다. 언리얼엔진에서는 기본적으로 Roboto 폰트 스타일만은 제공합니다.
- 이번 프로젝트에서는 무료폰트인 함렛을 사용했습니다. : https://github.com/hyper-type/hahmlet

GitHub - hyper-type/hahmlet: Hahmlet font by Minjoo Ham and Mark Frömberg aka Hypertype

Hahmlet font by Minjoo Ham and Mark Frömberg aka Hypertype - hyper-type/hahmlet

github.com

무료 폰트 모음 사이트 눈누에서 더 확인해 보실 수 있습니다: https://noonnu.cc/

눈누

상업적 이용 가능한 한글 폰트를 쉽게 찾아보세요.

noonnu.cc

HUD Widget을 생성해 화면에 표시하기

1️⃣ PlayerController에서 HUD 생성 로직 추가하기

Widget (HUD나 UI 요소)은 보통 PlayerController에서 구현하게 됩니다. 그 이유는 Widget이 플레이어의 입력과 상호작용하며 화면에 표시되는 요소이기 때문입니다.
MainPlayerController.h & .cpp 작성후 꼭!!! Project.Buid.cs 파일 에서 코드를 수정해 줘야 빌드가 됩니다.

MainPlayerController.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/PlayerController.h"
#include "MainPlayerController.generated.h"

// Declaration
class UInputMappingContext;  // IMC 관련 전방 선언
class UInputAction;// IA 관련 전방 선언


// Enhanced Input에서 액션 값을 받을 때 사용하는 구조체
struct FInputActionValue;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainPlayerController : public APlayerController
{
	GENERATED_BODY()

public:
	AMainPlayerController();
	
	// 에디터에서 세팅할 IMC
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputMappingContext* InputMappingContext;
	
	// IA
	// IA_Move를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* MoveAction;
	// IA_Jump를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* JumpAction;
	// IA_Look를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* LookAction;
	// IA_Sprint를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
	UInputAction* SprintAction;
	
	// UMG 위젯 클래스를 에디터에서 할당받을 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "UI")
	TSubclassOf<UUserWidget> HUDWidgetClass;
	
	
protected:
	virtual void BeginPlay() override;

	
};

MainPlayerController.cpp

#include "MainPlayerController.h"
#include "EnhancedInputSubsystems.h"
#include "EnhancedInputSubsystems.h" // Enhanced Input System의 Local Player Subsystem을 사용하기 위해 포함
#include "Blueprint/UserWidget.h"

// 어차피 블루프린트 상에서 전부 다 초기화를 하기 때문에 여기서는 전부 다 nullptr 처리
AMainPlayerController::AMainPlayerController()
	: InputMappingContext(nullptr),
	  MoveAction(nullptr),
	  JumpAction(nullptr),
	  LookAction(nullptr),
	  SprintAction(nullptr)

{
}

void AMainPlayerController::BeginPlay()
{
	Super::BeginPlay();

	// GetLocalPlayer():현재 PlayerController에 연결된 Local Player 객체를 가져옴     
	// Local Player 는 그 플레이어의 입력이나 화면 뷰 같은 것을 관리하는 어떤 객체
	if (ULocalPlayer* LocalPlayer = GetLocalPlayer())
	{
		// Local Player에서 EnhancedInputLocalPlayerSubsystem을 획득
		// UEnhancedInputLocalPlayerSubsystem: 입력 시스템을 관리 (IMC 추가 혹은 삭제하는 역할)
		if (UEnhancedInputLocalPlayerSubsystem* Subsystem =
			LocalPlayer->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>())
		{
			if (InputMappingContext)
			{
				// Subsystem을 통해 우리가 할당한 IMC를 활성화
				// 우선순위(Priority)는 0이 가장 높은 우선순위
				Subsystem->AddMappingContext(InputMappingContext, 0);
			}
		}
	}

	// HUD 위젯 생성 및 표시
	if (HUDWidgetClass)
	{
		UUserWidget* HUDWidget = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidget)
		{
			HUDWidget->AddToViewport();
		}
	}
}

BC_Ch3_Assignment_5.Build.cs

// Copyright Epic Games, Inc. All Rights Reserved.

using UnrealBuildTool;

public class BC_Ch3_Assignment_5 : ModuleRules
{
	public BC_Ch3_Assignment_5(ReadOnlyTargetRules Target) : base(Target)
	{
		PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
	
		PublicDependencyModuleNames.AddRange(new string[]
		{
			"Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput",
			"UMG" // 추가
		});

		PrivateDependencyModuleNames.AddRange(new string[] {  });

		// Uncomment if you are using Slate UI
		// PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore" });
		
		// Uncomment if you are using online features
		// PrivateDependencyModuleNames.Add("OnlineSubsystem");

		// To include OnlineSubsystemSteam, add it to the plugins section in your uproject file with the Enabled attribute set to true
	}
}

위의 코드를 조금 설명하자면, 현재 프로젝트 내에서 필수적으로 사용하는 엔진 기능들 이라고 보시면 됩니다.

PublicDependencyModuleNames

Core: 엔진의 기본 기능들
CoreUObject: 주로 리플렉션 시스템, 가비지 컬렉터
Engine: 게임엔진의 주요 기능
InputCore: 입력 시스템
EnhancedInput: Enhanced Input System
UMG:Widget Blue Print 관련 모델 (HUD 포함)

빌드 후, 이전에 만들어 두었던 BP_MainPlayerController에 보시면 UI->HUDWidget Class 가 생성되었습니다.

방금 만든 WBP_HUD 를 지정해 줍니다.

Play Mode 와 Play Setting 에 있는 Advanced Setting 으로 가셔서

뷰표트 세팅을 아까와 동일하게 1920 X 1080으로 변경해 줍니다.

이제 플레이해보면 UI 가 적용된 모습이 보입니다.

혹시라도 UI 가 이상하다면 New Editor Window (PIE) 로 플레이해 보세요.

HUD 위젯과 GameState 데이터 연동하기

데이터 바인딩 vs SetText 방식으로 위젯 갱신하기

1️⃣ GameState에서 점수 데이터 바인딩하기

Text Block 선택 & Bind 버튼 클릭
- 언리얼 에디터의 WBP_HUD (Widget Blueprint)를 엽니다.
- Designer 탭에서 점수를 표시할 Score를 표시할 Text Block을 하나 선택합니다.
- 오른쪽 Details 패널에서 Text 속성을 찾습니다.
- Text 항목 오른쪽에 있는 Bind 버튼을 클릭 → Create Binding을 선택합니다.

자동 생성된 함수 확인
- Binding 버튼을 클릭하면, Graph 탭 또는 이벤트 그래프에 새 블루프린트 함수가 자동 생성됩니다.
- 함수 이름은 보통 “GetText” 같은 식으로 자동으로 정해지는데, 우리는 왼쪽에 Functions 목록에서 함수를 클릭하고 F2를 눌러서 GetScore로 이름을 변경하도록 합시다.
GameState에서 Score 읽어오기
- 새로 생성된 바인딩 함수 안에서 GameState를 가져와야 합니다. 블루프린트에서는 아래와 같은 순서로 작업합니다.

마지막에 가져온 Score를 Format Text를 통해 표시를 만들어준 후 이 문자열을 Return Node로 반환하면, Text Block에 해당 문자열이 표시됩니다.

장점: 초급자에게는 Binding 방식이 코드를 많이 작성하지 않아도 되므로 더 직관적입니다.

단점: UI 복잡해지면 SetText 에 비해서 성능면에서 떨어지게 됩니다.

2️⃣ SetText 방식으로 위젯 갱신하기

MainGameState 에서 주요 변수들을 관리하고 있기 때문에 여기에서 위젯을 갱신하도록 구현하겠습니다.
Input을 입력받고 관리하는 쪽은 PlayerController 쪽에서 합니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/GameState.h"
#include "MainGameState.generated.h"


UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainGameState : public AGameState
{
	GENERATED_BODY()
	
public:
	AMainGameState();	
	
	virtual void BeginPlay() override;
	
	// === Variables ===
	// 전역 점수를 저장하는 변수
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="Score")
	int32 Score;

	// 현재 레벨에서 스폰된 코인 개수
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Coin")
	int32 SpawnedCoinCount;
	// 플레이어가 수집한 코인 개수
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Coin")
	int32 CollectedCoinCount;
	// 각 레벨이 유지되는 시간 (초 단위)
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Level")
	float LevelDuration;
	// 현재 진행 중인 레벨 인덱스
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Level")
	int32 CurrentLevelIndex;
	// 전체 레벨의 개수
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Level")
	int32 MaxLevels;
	// 실제 레벨 맵 이름 배열. 여기 있는 인덱스를 차례대로 연동
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Level")
	TArray<FName> LevelMapNames;
	
	// 매 레벨이 끝나기 전까지 시간이 흐르도록 관리하는 타이머
	FTimerHandle LevelTimerHandle;
	
	FTimerHandle HUDUpdateTimerHandle;
	
	
	// === Func ===
	// 현재 점수를 읽는 함수
	UFUNCTION(BlueprintPure, Category="Score")
	int32 GetScore() const;
	
	// 점수를 추가해주는 함수
	UFUNCTION(BlueprintCallable, Category="Score")
	void AddScore(int32 Amount);
	
	UFUNCTION(BlueprintCallable, Category = "Level")
	void OnGameOver();
	
	// 레벨을 시작할 때, 아이템 스폰 및 타이머 설정
	void StartLevel();
	// 레벨 제한 시간이 만료되었을 때 호출
	void OnLevelTimeUp();
	// 코인을 주웠을 때 호출
	void OnCoinCollected();
	// 레벨을 강제 종료하고 다음 레벨로 이동
	void EndLevel();
	void UpdateHUD();
	
};

#include "MainGameState.h"
#include "MainGameInstance.h"
#include "MainPlayerController.h"
#include "Kismet/GameplayStatics.h"
#include "SpawnVolume.h"
#include "CoinItem.h"
#include "Components/TextBlock.h"
#include "Blueprint/UserWidget.h"

AMainGameState::AMainGameState()
{
	Score = 0;
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	LevelDuration = 30.0f; // 한 레벨당 30초
	CurrentLevelIndex = 0;
	MaxLevels = 3;
}

void AMainGameState::BeginPlay()
{
	Super::BeginPlay();

	// 게임 시작 시 첫 레벨부터 진행
	StartLevel();
	
	UpdateHUD();
	
	GetWorldTimerManager().SetTimer(
			HUDUpdateTimerHandle,
			this,
			&AMainGameState::UpdateHUD,
			0.1f,
			true
		);
}

int32 AMainGameState::GetScore() const
{
	return Score;
}

void AMainGameState::AddScore(int32 Amount)
{
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			MainGameInstance->AddToScore(Amount);
		}
	}
}


void AMainGameState::StartLevel()
{
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			CurrentLevelIndex = MainGameInstance->CurrentLevelIndex;
		}
	}

	// 레벨 시작 시, 코인 개수 초기화
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	// 현재 맵에 배치된 모든 SpawnVolume을 찾아 아이템 40개를 스폰
	TArray<AActor*> FoundVolumes;
	UGameplayStatics::GetAllActorsOfClass(GetWorld(), ASpawnVolume::StaticClass(), FoundVolumes);
	const int32 ItemToSpawn = 40;

	for (int32 i = 0; i < ItemToSpawn; i++)
	{
		if (FoundVolumes.Num() > 0)
		{
			ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
			if (SpawnVolume)
			{
				AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();
				// 만약 스폰된 액터가 코인 타입이라면 SpawnedCoinCount 증가
				if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
				{
					SpawnedCoinCount++;
				}
			}
		}
	}
	// 30초 후에 OnLevelTimeUp()가 호출되도록 타이머 설정
	GetWorldTimerManager().SetTimer(
		LevelTimerHandle,
		this,
		&AMainGameState::OnLevelTimeUp,
		LevelDuration,
		false
	);
	UE_LOG(LogTemp, Warning, TEXT("Level %d Start!, Spawned %d coin"),
	       CurrentLevelIndex + 1,
	       SpawnedCoinCount);
}

void AMainGameState::OnLevelTimeUp()
{
	// 시간이 다 되면 레벨을 종료
	EndLevel();
}

void AMainGameState::OnCoinCollected()
{
	CollectedCoinCount++;

	UE_LOG(LogTemp, Warning, TEXT("Coin Collected: %d / %d"),
	       CollectedCoinCount,
	       SpawnedCoinCount)

	// 현재 레벨에서 스폰된 코인을 전부 주웠다면 즉시 레벨 종료
	if (SpawnedCoinCount > 0 && CollectedCoinCount >= SpawnedCoinCount)
	{
		EndLevel();
	}
}

void AMainGameState::EndLevel()
{	
	
	// 타이머 해제
	GetWorldTimerManager().ClearTimer(LevelTimerHandle);
	// 다음 레벨 인덱스로
	//CurrentLevelIndex++;
	
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			AddScore(Score);
			CurrentLevelIndex++;
			MainGameInstance->CurrentLevelIndex = CurrentLevelIndex;
		}
	}

	// 모든 레벨을 다 돌았다면 게임 오버 처리
	if (CurrentLevelIndex >= MaxLevels)
	{
		OnGameOver();
		return;
	}

	// 레벨 맵 이름이 있다면 해당 맵 불러오기
	if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
	{
		UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
	}
	else
	{
		// 맵 이름이 없으면 게임오버
		OnGameOver();
	}
}

void AMainGameState::OnGameOver()
{
	UpdateHUD();
	UE_LOG(LogTemp, Warning, TEXT("Game Over!!"));
	// 여기서 UI를 띄운다거나, 재시작 기능을 넣을 수도 있음
}

void AMainGameState::UpdateHUD()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		AMainPlayerController* MainPlayerController = Cast<AMainPlayerController>(PlayerController);
		{
			if (UUserWidget* HUDWidget = MainPlayerController->GetHUDWidget())
			{
				// requires
				// #include "Components/TextBlock.h"
				// #include "Blueprint/UserWidget.h"
				
				//추후 변경 방안 
				// UPROPERTY(meta = (BindWidget))
				// class UButton* MyAwesomeButton;
				if (UTextBlock* TimeText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Time"))))
				{
					float RemainingTime = GetWorldTimerManager().GetTimerRemaining(LevelTimerHandle);
					TimeText->SetText(FText::FromString(FString::Printf(TEXT("Time: %.1f"), RemainingTime)));
				}
				
				//
				if (UTextBlock* ScoreText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Score"))))
				{
					if (UGameInstance* GameInstance = GetGameInstance())
					{
						UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
						if (MainGameInstance)
						{
							ScoreText->SetText(FText::FromString(FString::Printf(TEXT("Score: %i"), MainGameInstance->TotalScore)));
						}
					}
				}
				
				if (UTextBlock* LevelIndexText = Cast<UTextBlock>(HUDWidget->GetWidgetFromName(TEXT("Level"))))
				{
					LevelIndexText->SetText(FText::FromString(FString::Printf(TEXT("Level: %d"), CurrentLevelIndex + 1)));
				}
			}
		}
	}
}

직접 SetText 호출
- 방식은 PlayerController의 Tick 함수(또는 Timer 이벤트)에서 GameState의 Score를 읽어와서, HUD 위젯에 있는 Text Block에 SetText를 호출하는 방식입니다.
- 이 경우에는 Binding을 쓰지 않고, C++ 혹은 블루프린트 스크립트에서 명시적으로 “점수가 바뀔 때마다 UI Text를 갱신”하도록 로직을 짭니다.
- SetText를 쓰면, 필요할 때만 UI를 업데이트할 수 있어 퍼포먼스에 유리할 수 있습니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/PlayerController.h"
#include "MainPlayerController.generated.h"

// Declaration
class UInputMappingContext;  // IMC 관련 전방 선언
class UInputAction;// IA 관련 전방 선언


// Enhanced Input에서 액션 값을 받을 때 사용하는 구조체
struct FInputActionValue;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainPlayerController : public APlayerController
{
	GENERATED_BODY()

public:
	AMainPlayerController();
	
	// 에디터에서 세팅할 IMC
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputMappingContext* InputMappingContext;
	
	// IA
	// IA_Move를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* MoveAction;
	// IA_Jump를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* JumpAction;
	// IA_Look를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input")
	UInputAction* LookAction;
	// IA_Sprint를 지정할 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
	UInputAction* SprintAction;
	
	// UMG 위젯 클래스를 에디터에서 할당받을 변수
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "HUD")
	TSubclassOf<UUserWidget> HUDWidgetClass;
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "HUD")
	UUserWidget* HUDWidgetInstance;
		
	UFUNCTION(BlueprintPure, Category = "HUD")
	UUserWidget* GetHUDWidget() const;
	
protected:
	virtual void BeginPlay() override;
	
	/*
	
	//UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Input", meta=(AllowPrivateAccess="true"))
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
	UInputAction* ToggleInventoryAction;
	
	bool bIsInventoryOpen;
	
	UFUNCTION(BlueprintCallable)
	void ToggleInventory();
	
	void ActivateCharacterInput();
	void ActivateUIInput();
	*/
	
};

#include "MainPlayerController.h"
#include "EnhancedInputSubsystems.h"
#include "EnhancedInputSubsystems.h" // Enhanced Input System의 Local Player Subsystem을 사용하기 위해 포함
#include "MainGameState.h"
#include "Blueprint/UserWidget.h"

// 어차피 블루프린트 상에서 전부 다 초기화를 하기 때문에 여기서는 전부 다 nullptr 처리
AMainPlayerController::AMainPlayerController()
	: InputMappingContext(nullptr),
	  MoveAction(nullptr),
	  JumpAction(nullptr),
	  LookAction(nullptr),
	  SprintAction(nullptr),
	  HUDWidgetClass(nullptr),
	  HUDWidgetInstance(nullptr)

{
}

void AMainPlayerController::BeginPlay()
{
	Super::BeginPlay();

	// GetLocalPlayer():현재 PlayerController에 연결된 Local Player 객체를 가져옴     
	// Local Player 는 그 플레이어의 입력이나 화면 뷰 같은 것을 관리하는 어떤 객체
	if (ULocalPlayer* LocalPlayer = GetLocalPlayer())
	{
		// Local Player에서 EnhancedInputLocalPlayerSubsystem을 획득
		// UEnhancedInputLocalPlayerSubsystem: 입력 시스템을 관리 (IMC 추가 혹은 삭제하는 역할)
		if (UEnhancedInputLocalPlayerSubsystem* Subsystem =
			LocalPlayer->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>())
		{
			if (InputMappingContext)
			{
				// Subsystem을 통해 우리가 할당한 IMC를 활성화
				// 우선순위(Priority)는 0이 가장 높은 우선순위
				Subsystem->AddMappingContext(InputMappingContext, 0);
			}
		}
	}

	// HUD 위젯 생성 및 표시
	if (HUDWidgetClass)
	{
		HUDWidgetInstance = CreateWidget<UUserWidget>(this, HUDWidgetClass);
		if (HUDWidgetInstance)
		{
			HUDWidgetInstance->AddToViewport();
		}
	}
	
	AMainGameState* MainGameState = GetWorld() ? GetWorld()->GetGameState<AMainGameState>() : nullptr;
	if (MainGameState)
	{
		MainGameState->UpdateHUD();
	}
}

UUserWidget* AMainPlayerController::GetHUDWidget() const
{
	return HUDWidgetInstance;
}

[TA] TA - Technical Artist (테크니컬 아티스트)란? | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Fri, 12 Jun 2026 00:32:51 +0900

언리얼엔진 공식문서 - 직무 가이드 살펴보기: https://www.unrealengine.com/tech-blog/jobs-in-unreal-engine---technical-artist?lang=ko

언리얼 엔진 직무 살펴보기 - 테크니컬 아티스트

실시간 기술 관련 커리어를 찾고 계신다면, 급성장 중인 테크니컬 아티스트를 고려해보시는 것은 어떨까요? 지난 12개월 사이에 수요가 48%나 증가한 이 직무는 아트와 코드를 잇는 중요한 역할

www.unrealengine.com

TA - Technical Artist 란?

출처: https://www.unrealengine.com/tech-blog/jobs-in-unreal-engine---technical-artist?lang=ko

TA-Technical Artist | 테크니컬 아티스트

'Technical Artist'는 한국 게임 및 IT 업계에서 줄여서 'TA(티에이)' 또는 '테크니컬 아티스트'라고 부릅니다.

아트(디자인)와 프로그래밍(기술)의 교집합에 있는 직무로, 미술적 감각과 기술적 이해도를 모두 갖추고 작업 환경을 개선하는 역할을 합니다. 즉 아티스트가 만든 리소스가 엔진 안에서 제대로 사용되도록 돕고, 개발자가 만든 기능이 시각적으로 잘 표현되도록 연결합니다.

주요 업무 내용은 다음과 같습니다.

최적화 및 엔진 구현: 아티스트가 만든 3D 모델이나 배경이 게임 엔진에서 원활하게 돌아가도록 리소스를 가다듬고 프레임 저하를 방지합니다.
툴(Tool) 개발 및 자동화: 아트 팀이 더 빠르고 편하게 작업할 수 있도록 돕는 전용 스크립트나 플러그인을 만듭니다.
리깅(Rigging) 및 애니메이션: 캐릭터가 자연스럽게 움직일 수 있도록 뼈(Bone)를 심고 관절의 무게값을 설정합니다.
이펙트 및 셰이더 제작: 불, 물, 폭발 등 시각적 효과를 담당하거나, 독특한 질감과 빛의 반사를 표현하는 셰이더를 프로그래밍합니다.
리소스 파이프라인 정리: 파일 이름 규칙, 폴더 구조, Import 설정 관리
머티리얼 구조 설계: Parent Material, Material Instance 구조 정리
반복 작업 자동화: 에셋 이름 정리, 폴더 자동 분류, 검사 도구 제작
VFX 연결: Niagara 이펙트 호출 위치와 타이밍 관리
최적화 기준 수립: Texture 크기, Material 복잡도, 파티클 수, Draw Call 관리
부서 간 소통: 아트 팀과 프로그래밍 팀 사이의 의견을 조율하고 기술적인 해결책을 제시하는 다리 역할을 합니다.

언리얼엔진 공식문서 - 직무 가이드 살펴보기: https://www.unrealengine.com/tech-blog/jobs-in-unreal-engine---technical-artist?lang=ko

언리얼 엔진 직무 살펴보기 - 테크니컬 아티스트

www.unrealengine.com

클라이언트 개발자에게 TA 기초가 필요한 이유

클라이언트 개발자는 보통 기능을 구현한다. 하지만 화면에 그것이 출력되어야 하고 어떻게 보여줄지에 대해서 잘 알아야 합니다. 공격 모션, 무기 궤적 이펙트, 피격 이펙트, 사운드, 카메라 흔들림, 머티리얼 변화가 함께 연결되어야 플레이어가 “공격이 제대로 들어갔다”라고 느낍니다.

소통에 원활한 도움을 줍니다

이펙트가 구려요 -> 공격 Notify 타이밍은 맞는데 Niagara System이 무기 Socket 위치와 어긋난 것 같습니다
머티리얼 색이 이상하고 잘 안보여요 -> 색상 문제라기보다 Lighting 환경과 Roughness 값 때문에 반사가 강하게 보이는 것 같습니다
애니메이션 동작이 이상해요 -> Animation 자체 문제라기보다 Root Motion과 캐릭터 이동 로직이 충돌하는 것 같습니다

정확하고 구체적인 표현으로 소통할수있게 됩니다.

게임 화면을 구성하는 기본 요소들

Mesh

Mesh: 게임 오브젝트의 형태를 만드는 3D구조.

그 중 크게 두개로 나눌 수 있는데 Static Mesh 와 Skeletal Mesh 가 있습니다.

Static Mesh: 뼈대 구조가 없는 정적인 오브젝트들 (바위, 벽, 건물, 무기, 물건들)
Skeletal Mesh: Bone과 Skeleton 구조를 가진 오브젝트( 캐릭터, 몬스터 등등 애니메이션이 필요한 오브젝트)

또한 한번 그렇게 설정했다고 못바꾸는 것이 아닌, 상황에 따라서 변경 가능합니다.

Skeletal Mesh to Static Mesh Conversion: https://dev.epicgames.com/documentation/unreal-engine/skeletal-mesh-to-static-mesh-conversion-in-unreal-engine

Skeletal Mesh to Static Mesh Conversion in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Learn how to convert posed Skeletal Mesh assets to Static Mesh assets in Unreal Engine.

dev.epicgames.com

스태틱 메시를 스켈레탈 메시로 변환하기: https://dev.epicgames.com/documentation/fortnite/convert-a-static-mesh-into-a-skeletal-mesh-in-unreal-editor-for-fortnite?lang=ko

Convert a Static Mesh into a Skeletal Mesh in Unreal Editor for Fortnite | Fortnite Documentation | Epic Developer Community

Create a fully working Skeletal Mesh from a Static Mesh using the suite of Mesh editors in Unreal Editor for Fortnite.

dev.epicgames.com

Texture

3차원 물체(모델링)의 표면에 입혀지는 '무늬'나 '재질 이미지'를 뜻합니다. (예: 나무 상자 3D 도형 위에 실제 나무껍질 이미지를 입히는 것)

Texture는 Mesh 표면에 적용되는 이미지 데이터이고, 단순히 색을 입히는 이미지가 아니라, 표면의 여러 정보를 담습니다.

베이스 컬러 (Base Color): 기본 색상
노멀 맵 (Normal Map): RGB 채널을 통해 표면의 굴곡과 방향성을 기록하여, 폴리곤이 많지 않아도 빛을 받았을 때 마치 입체적인 요철이 있는 것처럼 착시를 일으키는 텍스처입니다.

메탈릭 맵 (Metallic Map): 표면이 금속인지 비금속인지를 구분하는 텍스처입니다. 보통 흰색(1.0)에 가까울수록 금속 특유의 반사를 띄고, 검은색(0.0)은 비금속을 의미합니다.
러프니스 맵 (Roughness Map): 표면의 거칠기를 표현합니다. 매끄러울수록 빛을 선명하게 반사하고, 거칠수록 빛이 여러 방향으로 퍼져 뿌옇게 반사되도록 합니다. (프로그램에 따라 반짝임을 뜻하는 '스무스니스(Smoothness) 맵'을 사용하기도 합니다.)
앰비언트 오클루전 맵 (Ambient Occlusion Map): 틈새나 주름 등 빛이 닿기 힘든 구석진 곳에 생기는 미세한 그림자를 미리 구워낸 텍스처로, 사물 간의 입체감과 깊이를 더해줍니다.

Material

3D 게임에서 머티리얼(Material)은 3D 오브젝트 표면의 질감, 색상, 빛 반사 방식 등을 결정하는 렌더링 속성의 조합입니다. 현대 게임 엔진(유니티, 언리얼 등)에서는 주로 사실적인 물리 기반 렌더링(PBR) 방식을 사용하며, 머티리얼을 구성하는 주요 텍스처(맵) 종류는 다음과 같습니다

1. PBR 머티리얼을 구성하는 핵심 텍스처

베이스 컬러 / 알베도 (Base Color / Albedo): 물체 본연의 기본 색상과 패턴을 나타냅니다. (빛 정보는 포함하지 않음)
노멀 맵 (Normal Map): 텍스처의 밝고 어두운 명암을 이용해, 평평한 폴리곤 표면을 울퉁불퉁하거나 입체적인 질감으로 보이게 하는 속성입니다.
러프니스 / 스무스니스 (Roughness / Glossiness): 표면의 거친 정도를 나타내며, 빛이 표면에 닿았을 때 반사광이 얼마나 퍼지거나 선명하게 맺힐지 결정합니다.
메탈릭 (Metallic): 해당 표면이 금속(1.0)인지 비금속(0.0)인지 정의하며, 금속 특유의 반사율과 색상을 제어합니다.
앰비언트 오클루전 (Ambient Occlusion): 그림자가 생기는 구석이나 틈새 부분에 가짜 그림자를 드리워 입체감과 깊이를 더해줍니다.

2. 표현 목적에 따른 렌더링 모드 및 특수 머티리얼

불투명 (Opaque): 일반적인 벽, 돌, 금속 등 투명도가 없는 물체에 사용됩니다. [1]
투명 (Transparent): 유리, 물, 홀로그램, 식물의 잎처럼 빛이 투과되거나 반투명한 효과를 냅니다. [1]
언릿 (Unlit): 주변의 광원(빛)에 영향을 받지 않고 머티리얼 자체의 색상만 100% 발광하여 보여주는 방식입니다. (카툰 렌더링이나 UI에 주로 사용)
스킨 (Skin): 사람의 피부처럼 빛이 표면을 뚫고 들어가 살짝 산란되는 효과(Subsurface Scattering)를 적용한 머티리얼입니다.

Lighting

3D 게임에서 라이팅은 게임의 분위기와 사실감을 결정하는 핵심 요소입니다. 크게 빛의 형태와 역할에 따른 분류와 연산 방식에 따른 분류로 나뉩니다.

1. 광원의 형태와 역할에 따른 종류

게임 월드 내에서 빛을 뿜어내는 방식에 따른 구분입니다.

디렉셔널 라이트 (Directional Light)
- 태양이나 달처럼 무한히 먼 곳에서 평행하게 전체 공간을 비추는 빛입니다.
- 주로 씬(Scene)의 메인 광원으로 사용되며, 그림자 생성에 매우 효율적입니다.
포인트 라이트 (Point Light)
- 전구나 횃불처럼 한 점(Point)에서 사방으로 퍼져나가는 빛입니다.
- 특정 범위 내의 물체와 환경을 비출 때 사용됩니다.
스포트라이트 (Spot Light)
- 손전등이나 무대 조명처럼 특정 원뿔(Cone) 형태나 각도로 퍼져나가는 빛입니다.
- 빛의 도달 거리와 각도를 조절할 수 있습니다.
에어리어 라이트 (Area Light)
- 사각형이나 원통 같은 특정 면(Area) 에서 빛을 발산합니다.
- 가장 부드럽고 사실적인 그림자를 만들 수 있지만, 연산 비용이 높아 주로 오프라인 렌더링에 쓰이거나 베이크드 라이트로 활용됩니다.
앰비언트 라이트 (Ambient Light)
- 어두운 곳에서도 사물의 형태를 알아볼 수 있도록 씬 전체에 기본적으로 깔아주는 환경광입니다.
이미시브 라이트 (Emissive Light)
- 광원 오브젝트 자체가 발광하여 주변을 비추는 효과입니다. (예: 네온사인, 모니터 화면)

2. 연산 방식에 따른 종류

게임 엔진에서 빛과 그림자를 계산하는 방식입니다.

실시간 라이팅 (Realtime Lighting)
- 게임이 실행되는 동안 매 프레임마다 빛과 그림자의 위치를 계산합니다.
- 캐릭터가 움직이거나 시간이 지남에 따라 변하는 환경에 적합하지만, 높은 사양(GPU)이 요구됩니다.
베이크드 라이팅 (Baked Lighting / Precomputed)
- 게임을 실행하기 전에 미리 빛과 그림자를 계산하여 텍스처(라이트맵) 형태로 굳혀버리는 방식입니다.
- 그림자 연산이 없어 최적화에 탁월하지만, 움직이는 물체에는 적용할 수 없다는 단점이 있습니다.
혼합 라이팅 (Mixed Lighting)
- 실시간과 베이크드 방식을 결합한 형태입니다.
- 예를 들어 배경은 미리 구워두고(Bake), 움직이는 플레이어 캐릭터에게만 실시간 그림자가 적용되도록 설정하여 퀄리티와 최적화를 모두 챙길 수 있습니다.

고급 라이팅 기법

사실적인 그래픽을 위해 사용되는 현대적인 기술들입니다.

글로벌 일루미네이션 (Global Illumination, GI)
- 광원뿐만 아니라 물체에 부딪혀 튕겨 나오는 빛(반사광)까지 계산하여 극도로 사실적인 명암을 표현하는 기법입니다.
볼류메트릭 라이팅 (Volumetric Lighting)
- 빛 줄기 효과로, 안개나 먼지가 낀 공간에서 빛의 통로가 눈에 보이도록 렌더링하는 기법입니다.

루멘 (Lumen) 글로벌 일루미네이션 및 리플렉션

언리얼 엔진 5의 핵심 라이팅 시스템인 루멘(Lumen) 은 빛이 표면에 부딪혀 반사되는 간접광(Global Illumination)과 반사(Reflection)를 실시간으로 처리합니다. 프로젝트 세팅에서 활성화하여 사용할 수 있습니다.

장점: 정적인 라이트 맵을 구울 필요 없이 빛을 수정할 때마다 결과가 뷰포트에 바로 반영되어 작업 속도가 매우 빠릅니다.

라이트 모빌리티 (Mobility)

라이트를 생성하면 디테일(Details) 패널에서 모빌리티 설정을 지정해야 합니다. 이는 빛이 어떻게 연산되고 그림자가 표현되는지를 결정합니다.

스태틱 (Static): 완전히 고정된 라이트로, 런타임에 연산되지 않고 오프라인 상태에서 미리 구워(Bake) 둡니다. 성능 비용이 가장 낮지만 움직이는 물체에는 그림자가 제대로 적용되지 않습니다.
무버블 (Movable): 실시간으로 이동하고 작동하는 동적 라이트입니다. 퀄리티가 높고 움직이는 오브젝트에 완벽하게 반응하지만, 성능 소모가 가장 큽니다.
스테이셔너리 (Stationary): 라이트의 위치와 모양은 고정되어 있지만, 밝기와 색상 등은 실시간으로 변경할 수 있습니다. 스태틱과 무버블의 장점을 혼합한 방식으로, 고정된 환경에서 동적 그림자가 필요한 경우 주로 사용합니다.

게임에서 빛의 역할들

분위기 형성: 따뜻함, 차가움, 긴장감 등
시선 유도: 중요한 오브젝트를 강조
공간감 형성: 그림자를 통해 깊이감 제공
플레이 경험 보조: 위험 지역, 안전 지역, 목표 지점 강조

[언리얼 페스트 서울 2025] Day2 라이팅 팁: 라이트를 이해하는 법(feat. CG 아티스트들이 라이트에 관심 없는 이유) : https://youtu.be/Mr_1CBuoThI

Animation

캐릭터나 오브젝트의 움직임을 표현합니다.게임에서 Animation은 단순 재생 영상이 아니라 입력, 상태, 판정, 피드백과 연결된다.

공격 애니메이션에서 중요한 요소

공격 시작 타이밍: 입력 후 언제 공격이 시작되는가
무기 이동 타이밍: 무기가 실제로 휘둘리는 시점
판정 타이밍: 데미지가 적용되는 시점
이펙트 타이밍: Slash VFX, Hit VFX가 나오는 시점
후속 행동 타이밍: 다음 행동으로 넘어갈 수 있는 시점

VFX (Visual Effects, 시각 특수 효과)

3D 게임에서 VFX(Visual Effects, 시각 특수 효과)는 게임 화면에 등장하는 마법, 폭발, 불, 물, 날씨 등 현실에서 직접 촬영하기 어렵거나 상상 속에만 존재하는 시각적 요소들을 컴퓨터 그래픽으로 구현하는 작업입니다

1. 3D 게임 VFX의 핵심 역할

게임에서 VFX는 단순한 배경 장식을 넘어 게임플레이의 핵심적인 요소로 작동합니다.

타격감 및 피드백: 캐릭터가 스킬을 사용하거나 적을 공격할 때 번쩍이는 효과, 화면 흔들림, 파편 튀김 등을 통해 타격감과 조작의 재미를 극대화합니다.
몰입감 조성: 비, 눈, 안개, 모래바람 등 환경 효과를 만들어내어 게임의 분위기를 살립니다.
정보 전달: 캐릭터의 상태(예: 독에 걸림, 보호막 생성 등)를 시각적으로 명확하게 전달하여 유저가 상황을 인지하도록 돕습니다.

2. 주요 제작 분야

게임 VFX는 크게 다음과 같은 효과들을 다룹니다.

스킬 및 마법 이펙트: 캐릭터의 액션에 동반되는 화려한 오라, 광선, 마법진.
물리/환경 효과: 폭발, 연기, 불꽃, 물의 흐름, 파도.
UI 및 연출 효과: 화면 가장자리가 붉어지는 피해 효과, 레벨 업 시 발생하는 빛 기둥 등.

3. 게임 VFX 제작에 쓰이는 기술과 도구

영화 VFX가 완성된 영상에 효과를 합성하는 것과 달리, 3D 게임 VFX는 실시간으로 화면을 렌더링해야 하므로 다음과 같은 기술과 툴이 주로 사용됩니다.

파티클 시스템 (Particle System): 불꽃, 빗방울, 먼지처럼 수많은 작은 점이나 이미지를 흩날려 형태를 만드는 기술입니다.
셰이더 (Shader): 빛의 반사, 굴절, 물의 일렁임 등을 수학적으로 계산하여 화면에 그려내는 프로그래밍 및 노드 기반 기술입니다.
주요 엔진 툴: 언리얼 엔진(Unreal Engine)의 나이아가라(Niagara)나 유니티(Unity)의 비주얼 이펙트 그래프(VFX Graph)를 주로 사용합니다

게임에서 많이 쓰이는 VFX 예시

공격 궤적: 공격 방향과 범위 전달
피격 이펙트: 적중 여부 전달
폭발: 강한 충격 표현
먼지 / 불꽃: 상황의 질감 표현
마법 효과: 스킬의 성격 표현
위험 범위 표시: 플레이어에게 회피 정보 전달

과제 (게임 분석): 게임 액션 하나를 선택하고 리소스 연결 구조 분석하기

자신이 좋아하는 게임에서 액션 하나를 선택하고 아래 항목들 분석해 보기.

작성 항목

선택한 게임과 액션:

예시:
- 기본 공격
- 스킬 사용
- 총 발사
- 피격
- 점프 착지
- 아이템 사용
- 문 열기
- 대시 이동

시작 이벤트 이 액션은 어떤 입력 또는 이벤트에서 시작되는가?

필요한 리소스

Mesh:
Animation:
VFX:
Material:
Sound:
Camera:
UI:

연결 흐름:

역할 분리:

개발자 담당:
아티스트 담당:
TA 관점에서 확인할 부분:

정리. 이 액션에서 가장 중요하다고 생각한 연결 지점은 무엇인가?

[페이지] Unreal Engine | 언리얼 엔진

TA | 아이템 시스템과 게임 흐름 로직 구현하기 | 코드 카타 (Code Kata): 둘만의 암호 | TIL 35th | 캠프 34일 차 | 06/11/2026 (Thur)

DevCol — Thu, 11 Jun 2026 23:55:57 +0900

TA | 아이템 시스템과 게임 흐름 로직 구현하기 | 코드 카타 (Code Kata): 둘만의 암호

TA

[Unreal Engine/TA] - [TA] TA - Technical Artist (테크니컬 아티스트)란? | [언리얼 엔진 C++ (Unreal Engine C++)]

[TA] TA - Technical Artist (테크니컬 아티스트)란? | [언리얼 엔진 C++ (Unreal Engine C++)]

언리얼엔진 공식문서 - 직무 가이드 살펴보기: https://www.unrealengine.com/tech-blog/jobs-in-unreal-engine---technical-artist?lang=ko 언리얼 엔진 직무 살펴보기 - 테크니컬 아티스트실시간 기술 관련 커리어를 찾

devcol.tistory.com

아이템 시스템과 게임 흐름 로직 구현하기

[Unreal Engine/UE 기초] - 인터페이스 기반 아이템 클래스 설계하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

인터페이스 기반 아이템 클래스 설계하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

devcol.tistory.com

[Unreal Engine/UE 기초] - 충돌 이벤트로 획득되는 아이템 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

충돌 이벤트로 획득되는 아이템 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

devcol.tistory.com

[Unreal Engine/UE 기초] - 아이템 스폰 및 레벨 데이터 관리하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

아이템 스폰 및 레벨 데이터 관리하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

devcol.tistory.com

[Unreal Engine/UE 기초] - 캐릭터 체력 및 점수 관리 시스템 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

캐릭터 체력 및 점수 관리 시스템 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

devcol.tistory.com

[Unreal Engine/UE 기초] - 게임 루프 설계를 통한 게임 흐름 제어하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

게임 루프 설계를 통한 게임 흐름 제어하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

devcol.tistory.com

코드 카타 (Code Kata) : 둘만의 암호

067. 둘만의 암호 | Solved Date: 2026-06-11-Thur | Problem Link

CodeKata/Programmers/067. 둘만의 암호.md at 455afb31f97c399b772ad546584bc1013af901d9 · devcol-main/CodeKata

CodeKata. Contribute to devcol-main/CodeKata development by creating an account on GitHub.

github.com

게임 루프 설계를 통한 게임 흐름 제어하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Thu, 11 Jun 2026 19:54:04 +0900

게임 루프 설계를 통한 게임 흐름 제어하기

GameState를 이용한 게임 루프 구현하기

게임루프: 보통 게임의 핵심적인 흐름을 얘기합니다. 즉 게임이 시작할 때부터 종료까지 수행하는 단계들

게임플로우: 게임을 시작해서 진행하고 끝내는 과정에서 발생하는 모든 상호작용들

1️⃣ GameState와 GameMode

언리얼 엔진에서 게임 루프나 전역 상태를 관리할 때 대표적으로 고려되는 클래스는 GameState와 GameMode가 있습니다.

GameMode를 쓰는 이유는?
- 서버 전용 로직을 담는 곳이며, 게임 규칙 (팀 배정, 승패 조건, 플레이어 스폰 등)을 서버에서 제어하는 데 사용됩니다.
- 클라이언트는 GameMode에 직접 접근할 수 없습니다. 따라서 클라이언트도 알아야 하는 정보(예: 남은 시간, 현재 점수 등)를 GameMode에만 두면 복잡해집니다.
- 보통 멀티플레이를 고려한다면, “중요 규칙 로직”만 GameMode에 두고, “서버-클라이언트가 공통으로 알아야 하는 상태”는 GameState에 두는 방식을 많이 사용합니다.
GameState를 쓰는 이유는?
- 게임 전반에 걸쳐 모든 플레이어가 공유해야 하는 상태를 담는 클래스입니다. 보통 전역 상태가 필요할 경우 GameState를 활용합니다.
- GameState 객체는 게임이 시작될 때 서버에서 생성되고, 클라이언트는 이를 복제받아서 똑같은 정보를 읽을 수 있습니다. 즉, “서버와 클라이언트 모두” 동일한 정보를 가지게 됩니다.
이번 강의에서는 레벨마다 40개의 아이템을 스폰하고, 시간 제한 30초 내에 플레이어가 모든 코인을 주우면 즉시 레벨이 끝나고 다음 레벨로 넘어가는 구조를 만들 것입니다. 이처럼 멀티플레이를 고려했을 때도 클라이언트가 알아야 할 상태가 많아지므로, GameMode 대신 GameState를 선택하여 전역 상태를 관리하는 방식으로 구현합니다.

2️⃣ SpawnVolume 클래스 스폰 데이터 반환 수정

기존에는 스폰 함수가 void를 반환했는데, 스폰된 아이템의 정보 (코인이 맞는지, 혹은 다른 아이템인지)를 추후 GameState에서 카운팅 하려면, 스폰 함수가 스폰된 AActor*를 반환해야 합니다.
아래 코드에서는 SpawnRandomItem()이 스폰된 액터 포인터를 반환하도록 수정하고, 그 액터가 코인인지 확인할 수 있게 만듭니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ItemSpawnRow.h"       // 우리가 정의한 구조체

#include "SpawnVolume.generated.h"

class UBoxComponent;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API ASpawnVolume : public AActor
{
	GENERATED_BODY()
	
public:	
	// Sets default values for this actor's properties
	ASpawnVolume();
	
	UFUNCTION(BlueprintCallable, Category = "Spawning")	
	AActor* SpawnRandomItem(); // 리턴 형식을 AActor* 로 변경
	
protected:
	
	//
	FItemSpawnRow* GetRandomItem() const;
	
	// === Components	
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Spawning")
    USceneComponent* Scene;
    // 스폰 영역을 담당할 박스 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Spawning")
    UBoxComponent* SpawningBox;
	
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Spawning")
	UDataTable* ItemDataTable;
	
	// === Functions
	
	// 특정 아이템 클래스를 스폰하는 함수
	UFUNCTION(BlueprintCallable, Category="Spawning")
	AActor* SpawnItem(TSubclassOf<AActor> ItemClass); // 리턴 형식을 AActor* 로 변경
	
	// 스폰 볼륨 내부에서 무작위 좌표를 얻어오는 함수
	UFUNCTION(BlueprintCallable, Category="Spawning")
	FVector GetRandomPointInVolume() const;	
	
	
};

#include "SpawnVolume.h"
#include "Components/BoxComponent.h"
#include "Engine/World.h"
#include "GameFramework/Actor.h"

ASpawnVolume::ASpawnVolume()
{
	PrimaryActorTick.bCanEverTick = false;

	// 박스 컴포넌트를 생성하고, 이 액터의 루트로 설정
	Scene = CreateDefaultSubobject<USceneComponent>(TEXT("Scene"));
	SetRootComponent(Scene);
    
	SpawningBox = CreateDefaultSubobject<UBoxComponent>(TEXT("SpawningBox"));
	SpawningBox->SetupAttachment(Scene);
}

AActor* ASpawnVolume::SpawnRandomItem()
{
	if (FItemSpawnRow* SelectedRow = GetRandomItem())
	{
		if (UClass* ActualClass = SelectedRow->ItemClass.Get())
		{
			return SpawnItem(ActualClass);
		}
	}
	return nullptr;
} 

FVector ASpawnVolume::GetRandomPointInVolume() const
{
	// 1) 박스 컴포넌트의 스케일된 Extent, 즉 x/y/z 방향으로 반지름(절반 길이)을 구함
	FVector BoxExtent = SpawningBox->GetScaledBoxExtent();
	// 2) 박스 중심 위치
	FVector BoxOrigin = SpawningBox->GetComponentLocation();

	// 3) 각 축별로 -Extent ~ +Extent 범위의 무작위 값 생성
	return BoxOrigin + FVector(
		FMath::FRandRange(-BoxExtent.X, BoxExtent.X),
		FMath::FRandRange(-BoxExtent.Y, BoxExtent.Y),
		FMath::FRandRange(-BoxExtent.Z, BoxExtent.Z)
	);
}


FItemSpawnRow* ASpawnVolume::GetRandomItem() const
{
	if (!ItemDataTable) 
		return nullptr;

	
	// 1) 모든 Row(행) 가져오기
	TArray<FItemSpawnRow*> AllRows;
	static const FString ContextString(TEXT("ItemSpawnContext")); // 디버깅 용도
	ItemDataTable->GetAllRows(ContextString, AllRows);

	if (AllRows.IsEmpty()) return nullptr; 

	// 2) 전체 확률 합 구하기
	float TotalChance = 0.0f; // 초기화
	for (const FItemSpawnRow* Row : AllRows) // AllRows 배열의 각 Row를 순회
	{
		if (Row) // Row가 유효한지 확인
		{
			TotalChance += Row->SpawnChance; // SpawnChance 값을 TotalChance에 더하기
		}
	}

	// 3) 0 ~ TotalChance 사이 랜덤 값
	const float RandValue = FMath::FRandRange(0.0f, TotalChance);
	float AccumulateChance = 0.0f; // 랜덤 값 보정
	//Algo::Accumulate( AllRows, AccumulateChance)
	
	// 4) 누적 확률로 아이템 선택
	for (FItemSpawnRow* Row : AllRows)
	{
		AccumulateChance += Row->SpawnChance;
		if (RandValue <= AccumulateChance)
		{
			return Row;
		}
	}

	return nullptr;
}

AActor* ASpawnVolume::SpawnItem(TSubclassOf<AActor> ItemClass)
{
	if (!ItemClass) return nullptr;

	// SpawnActor가 성공하면 스폰된 액터의 포인터가 반환됨
	AActor* SpawnedActor = GetWorld()->SpawnActor<AActor>(
		ItemClass,
		GetRandomPointInVolume(),
		FRotator::ZeroRotator
	);
	
	return SpawnedActor;
}

3️⃣ GameState 기반의 게임 루프 구현

게임 흐름 (3레벨, 각 레벨당 30초, 코인 모두 획득 시 즉시 다음 레벨로 이동, 3 레벨이 끝나면 Game Over)의 로직을 관리하도록 변경합니다.
레벨 시작 시 40개 아이템을 소환하며, 그중 코인 아이템이 몇 개 생성되었는지 추적(SpawnedCoinCount)하고, 플레이어가 먹은 코인 개수를 추적(CollectedCoinCount)하여 “모두 먹었다면” 즉시 레벨 종료합니다.

맵 전환 (OpenLevel) 시 주의
- UGameplayStatics::OpenLevel을 호출하면 지금 월드가 언로드 (제거) 되고, 새로운 맵이 로드되면서 BeginPlay()가 다시 실행됩니다. 이때 GameState도 새로 생성되기 때문에, 이전 레벨에서 유지하던 변수가 모두 초기화될 수 있습니다.
로직 함수
- BeginPlay(): 게임 시작 시 StartLevel() 호출
- StartLevel():
  1. 코인 개수들 초기화(SpawnedCoinCount=0, CollectedCoinCount=0)
  2. 스폰 볼륨들을 찾아서 40개 아이템 스폰(반복).
    - 만약 SpawnRandomItem()이 ACoinItem을 반환하면 SpawnedCoinCount++
  3. 30초 타이머 설정 (OnLevelTimeUp 호출)
- UGameplayStatics::GetAllActorsOfClass(GetWorld(), ASpawnVolume::StaticClass(), FoundVolumes);
  - GetAllActorsOfClass(): 현재 월드에서 이 액터에 해당되는 것들을 모두 가져오는 함수
  - #include "Kismet/GameplayStatics.h" 추가 해줘야합니다
  - TArray<AActor*> FoundVolumes;
- IsA() : 해당 포인터가 찾는 게 맞는지 확인. (하위 클래스도 같이 확인해 줍니다)
- OnLevelTimeUp(): 30초가 만료되면 레벨 종료(EndLevel())
- OnCoinCollected(): 코인 아이템을 먹을 때마다 호출.
  - CollectedCoinCount++
  - CollectedCoinCount >= SpawnedCoinCount 이면, 즉시 EndLevel()
- GetWorldTimerManager().ClearTimer: 타이머 초기화
- EndLevel()
  1. 현재 레벨 타이머 정리
  2. CurrentLevelIndex++
  3. 만약 CurrentLevelIndex >= MaxLevels 이면 OnGameOver()
    - 아니면 다음 레벨 StartLevel()
- OnGameOver()
  - GameOver 로그 출력 (혹은 UI 호출 등)
  - 추후 RestartGame 등 처리(블루프린트나 GameMode에서 구현)

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/GameState.h"
#include "MainGameState.generated.h"


UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainGameState : public AGameState
{
	GENERATED_BODY()
	
public:
	AMainGameState();	
	
	virtual void BeginPlay() override;
	
	// === Variables ===
	// 전역 점수를 저장하는 변수
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="Score")
	int32 Score;

	// 현재 레벨에서 스폰된 코인 개수
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Coin")
	int32 SpawnedCoinCount;
	// 플레이어가 수집한 코인 개수
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Coin")
	int32 CollectedCoinCount;
	// 각 레벨이 유지되는 시간 (초 단위)
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Level")
	float LevelDuration;
	// 현재 진행 중인 레벨 인덱스
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Level")
	int32 CurrentLevelIndex;
	// 전체 레벨의 개수
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Level")
	int32 MaxLevels;
	// 실제 레벨 맵 이름 배열. 여기 있는 인덱스를 차례대로 연동
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Level")
	TArray<FName> LevelMapNames;
	
	// 매 레벨이 끝나기 전까지 시간이 흐르도록 관리하는 타이머
	FTimerHandle LevelTimerHandle;
	
	
	// === Func ===
	// 현재 점수를 읽는 함수
	UFUNCTION(BlueprintPure, Category="Score")
	int32 GetScore() const;
	
	// 점수를 추가해주는 함수
	UFUNCTION(BlueprintCallable, Category="Score")
	void AddScore(int32 Amount);
	
	UFUNCTION(BlueprintCallable, Category = "Level")
	void OnGameOver();
	
	// 레벨을 시작할 때, 아이템 스폰 및 타이머 설정
	void StartLevel();
	// 레벨 제한 시간이 만료되었을 때 호출
	void OnLevelTimeUp();
	// 코인을 주웠을 때 호출
	void OnCoinCollected();
	// 레벨을 강제 종료하고 다음 레벨로 이동
	void EndLevel();
	
};

#include "MainGameState.h"
#include "Kismet/GameplayStatics.h"
#include "SpawnVolume.h"
#include "CoinItem.h"

AMainGameState::AMainGameState()
{
	Score = 0;
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	LevelDuration = 30.0f; // 한 레벨당 30초
	CurrentLevelIndex = 0;
	MaxLevels = 3;
}

void AMainGameState::BeginPlay()
{
	Super::BeginPlay();
	
	// 게임 시작 시 첫 레벨부터 진행
	StartLevel();
}

int32 AMainGameState::GetScore() const
{
	return Score;
}

void AMainGameState::AddScore(int32 Amount)
{
	Score += Amount;
}


void AMainGameState::StartLevel()
{
		// 레벨 시작 시, 코인 개수 초기화
		SpawnedCoinCount = 0;
		CollectedCoinCount = 0;
	
		// 현재 맵에 배치된 모든 SpawnVolume을 찾아 아이템 40개를 스폰
		TArray<AActor*> FoundVolumes;
		UGameplayStatics::GetAllActorsOfClass(GetWorld(), ASpawnVolume::StaticClass(), FoundVolumes);
	
		const int32 ItemToSpawn = 40;
		
		for (int32 i = 0; i < ItemToSpawn; i++)
		{
				if (FoundVolumes.Num() > 0)
						{
						ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
						if (SpawnVolume)
						{
								AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();
								// 만약 스폰된 액터가 코인 타입이라면 SpawnedCoinCount 증가
								if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
								{
										SpawnedCoinCount++;
								}
						}				
				}
		}
	
		// 30초 후에 OnLevelTimeUp()가 호출되도록 타이머 설정
		GetWorldTimerManager().SetTimer(
			LevelTimerHandle,
			this,
			&AMainGameState::OnLevelTimeUp,
			LevelDuration,
			false
		);
	
		UE_LOG(LogTemp, Warning, TEXT("Level %d Start!, Spawned %d coin"),
			CurrentLevelIndex + 1,
			SpawnedCoinCount);
}

void AMainGameState::OnLevelTimeUp()
{
		// 시간이 다 되면 레벨을 종료
		EndLevel();
}

void AMainGameState::OnCoinCollected()
{
		CollectedCoinCount++;
	
		UE_LOG(LogTemp, Warning, TEXT("Coin Collected: %d / %d"), 
			CollectedCoinCount,
			SpawnedCoinCount)
	
		// 현재 레벨에서 스폰된 코인을 전부 주웠다면 즉시 레벨 종료
		if (SpawnedCoinCount > 0 && CollectedCoinCount >= SpawnedCoinCount)
		{
				EndLevel();
		}
}

void AMainGameState::EndLevel()
{
		// 타이머 해제
		GetWorldTimerManager().ClearTimer(LevelTimerHandle);
		// 다음 레벨 인덱스로
		CurrentLevelIndex++;

		// 모든 레벨을 다 돌았다면 게임 오버 처리
		if (CurrentLevelIndex >= MaxLevels)
		{
				OnGameOver();
				return;
		}
		
		// 레벨 맵 이름이 있다면 해당 맵 불러오기
		if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
		{			    
				UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
		}
		else
		{
				// 맵 이름이 없으면 게임오버
				OnGameOver();
		}
}

void AMainGameState::OnGameOver()
{
		UE_LOG(LogTemp, Warning, TEXT("Game Over!!"));
		// 여기서 UI를 띄운다거나, 재시작 기능을 넣을 수도 있음
}

4️⃣ 코인 아이템 점수 획득 로직 수정

CoinItem은 플레이어가 닿았을 때 (ActivateItem) 점수를 획득하고 자기 자신을 제거하는 구조입니다. 여기서 추가로 “코인을 하나 더 먹었다”라고 GameState에게 알려야 합니다

#include "CoinItem.h"
#include "Engine/World.h"
#include "MainGameState.h"

ACoinItem::ACoinItem()
{
	// 부모클래스라 안해도 되지만 
	// 점수 기본값을 0으로 설정
	PointValue = 0;
	ItemType = "DefaultCoin";
}

void ACoinItem::ActivateItem(AActor* Activator)
{
	// 플레이어 태그 확인
	if (Activator && Activator->ActorHasTag("Player"))
	{
		// 점수 획득 디버그 메시지
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, 
			FString::Printf(TEXT("Player Gained %i Points!"), PointValue));
        	
		
		if (UWorld* World = GetWorld())
		{
			if (AMainGameState* GameState = World->GetGameState<AMainGameState>())
			{
				GameState->AddScore(PointValue);
				GameState->OnCoinCollected();
			}
		}
		
		// 부모 클래스 (BaseItem)에 정의된 아이템 파괴 함수 호출
		DestroyItem();
	}
}

Game Instance를 활용한 데이터 유지하기

BP_MainGameState의 Level Map Names Setting.

현재 만들어둔 레벨들의 이름을 넣습니다.

Proejct -Maps & Modes 세팅에서 Game State Class를 BP_MainGameState 로 설정해 줍니다.

현재 게임은 Level이 전환될 때마다 GameState 가 새로 만들어져서 Variable 들의 정보가 다 초기화됩니다 (Score, CurrentLevelIndex 등등) 그래서 유지해야 하는 데이터들을 저장하기 위한 작업을 해보겠습니다.

1️⃣ Game Instance란?

레벨 전환 시에는 GameState, GameMode 같은 기본 클래스를 비롯해, 맵 내에서 생성된 대부분의 객체가 처음부터 다시 생성됩니다.
하지만 어떤 경우에는 “이전 레벨에서 획득한 점수나 플레이어 상태” 등을 모든 레벨에 걸쳐 유지하고 싶을 수 있습니다. 이를 위해서는 보통 두 가지 방법을 활용합니다.

Game Instance
- 프로젝트가 시작될 때 (에디터에서 게임 실행을 누른 시점)부터 애플리케이션이 완전히 종료될 때까지 유일하게 계속 살아있는 객체입니다.
- 마치 Singleton과 비슷하다.
- 맵이 전환되어도 파괴되지 않으므로, 여기서 전역 데이터를 유지할 수 있습니다.
Seamless Travel
- 멀티플레이 환경에서 주로 사용되는 레벨 전환 방식으로, GameState/PlayerController 등을 파괴하지 않고 그대로 다음 맵으로 넘어가는 기능입니다.
- Seamless Travel을 사용하면 대부분의 객체를 유지할 수 있지만, 설정과 로직이 조금 더 복잡하므로, 싱글 플레이 전용 간단 프로젝트라면 GameInstance를 사용하기가 쉽습니다.

Game Instance Subsystem 이란 것 또한 많이 사용하는데 이것은 추후에 더 알아보도록 하겠습니다.

2️⃣ Game Instance 생성 및 변수 선언

#pragma once

#include "CoreMinimal.h"
#include "Engine/GameInstance.h"
#include "MainGameInstance.generated.h"

UCLASS()
class BC_CH3_ASSIGNMENT_5_API UMainGameInstance : public UGameInstance
{
	GENERATED_BODY()
	
public:
	UMainGameInstance();
	
	// 게임 전체 누적 점수
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category = "GameData")
	int32 TotalScore;
	// 현재 레벨 인덱스 (GameState에서도 관리할 수 있지만, 맵 전환 후에도 살리고 싶다면 GameInstance에 복제할 수 있음)
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category = "GameData")
	int32 CurrentLevelIndex;
	
	UFUNCTION(BlueprintCallable, Category = "GameData")
	void AddToScore(int32 Amount);
	
};

#include "MainGameInstance.h"

UMainGameInstance::UMainGameInstance()
{
	TotalScore = 0;
	CurrentLevelIndex = 0;
}

void UMainGameInstance::AddToScore(int32 Amount)
{
	TotalScore += Amount;
	UE_LOG(LogTemp, Warning, TEXT("Total Score Updated: %d"), TotalScore);
}

Update 된 MainGameState.cpp

#include "MainGameState.h"
#include "MainGameInstance.h"
#include "Kismet/GameplayStatics.h"
#include "SpawnVolume.h"
#include "CoinItem.h"

AMainGameState::AMainGameState()
{
	Score = 0;
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	LevelDuration = 30.0f; // 한 레벨당 30초
	CurrentLevelIndex = 0;
	MaxLevels = 3;
}

void AMainGameState::BeginPlay()
{
	Super::BeginPlay();

	// 게임 시작 시 첫 레벨부터 진행
	StartLevel();
}

int32 AMainGameState::GetScore() const
{
	return Score;
}

void AMainGameState::AddScore(int32 Amount)
{
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			MainGameInstance->AddToScore(Amount);
		}
	}
}


void AMainGameState::StartLevel()
{
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			CurrentLevelIndex = MainGameInstance->CurrentLevelIndex;
		}
	}

	// 레벨 시작 시, 코인 개수 초기화
	SpawnedCoinCount = 0;
	CollectedCoinCount = 0;
	// 현재 맵에 배치된 모든 SpawnVolume을 찾아 아이템 40개를 스폰
	TArray<AActor*> FoundVolumes;
	UGameplayStatics::GetAllActorsOfClass(GetWorld(), ASpawnVolume::StaticClass(), FoundVolumes);
	const int32 ItemToSpawn = 40;

	for (int32 i = 0; i < ItemToSpawn; i++)
	{
		if (FoundVolumes.Num() > 0)
		{
			ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
			if (SpawnVolume)
			{
				AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();
				// 만약 스폰된 액터가 코인 타입이라면 SpawnedCoinCount 증가
				if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
				{
					SpawnedCoinCount++;
				}
			}
		}
	}
	// 30초 후에 OnLevelTimeUp()가 호출되도록 타이머 설정
	GetWorldTimerManager().SetTimer(
		LevelTimerHandle,
		this,
		&AMainGameState::OnLevelTimeUp,
		LevelDuration,
		false
	);
	UE_LOG(LogTemp, Warning, TEXT("Level %d Start!, Spawned %d coin"),
	       CurrentLevelIndex + 1,
	       SpawnedCoinCount);
}

void AMainGameState::OnLevelTimeUp()
{
	// 시간이 다 되면 레벨을 종료
	EndLevel();
}

void AMainGameState::OnCoinCollected()
{
	CollectedCoinCount++;

	UE_LOG(LogTemp, Warning, TEXT("Coin Collected: %d / %d"),
	       CollectedCoinCount,
	       SpawnedCoinCount)

	// 현재 레벨에서 스폰된 코인을 전부 주웠다면 즉시 레벨 종료
	if (SpawnedCoinCount > 0 && CollectedCoinCount >= SpawnedCoinCount)
	{
		EndLevel();
	}
}

void AMainGameState::EndLevel()
{	
	
	// 타이머 해제
	GetWorldTimerManager().ClearTimer(LevelTimerHandle);
	// 다음 레벨 인덱스로
	//CurrentLevelIndex++;
	
	if (UGameInstance* GameInstance = GetGameInstance())
	{
		UMainGameInstance* MainGameInstance = Cast<UMainGameInstance>(GameInstance);
		if (MainGameInstance)
		{
			AddScore(Score);
			CurrentLevelIndex++;
			MainGameInstance->CurrentLevelIndex = CurrentLevelIndex;
		}
	}

	// 모든 레벨을 다 돌았다면 게임 오버 처리
	if (CurrentLevelIndex >= MaxLevels)
	{
		OnGameOver();
		return;
	}

	// 레벨 맵 이름이 있다면 해당 맵 불러오기
	if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
	{
		UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
	}
	else
	{
		// 맵 이름이 없으면 게임오버
		OnGameOver();
	}
}

void AMainGameState::OnGameOver()
{
	UE_LOG(LogTemp, Warning, TEXT("Game Over!!"));
	// 여기서 UI를 띄운다거나, 재시작 기능을 넣을 수도 있음
}

프로젝트 세팅 안에 Game Instance 도 변경해줘야 합니다. 그전에 BP_MainGmaeInstace 도 만들고 설정하겠습니다.

3️⃣ 전체 게임 루프 요약

게임 실행
- GameInstance 생성, GameMode/GameState 생성, 첫 레벨 로드
BeginPlay()
- ASpartaGameState::BeginPlay() → StartLevel()
- 스폰 볼륨(SpawnVolume)에서 40개 아이템 스폰
- 코인 개수 추적(SpawnedCoinCount)
- 30초 타이머 시작
플레이어가 코인 획득
- CoinItem::ActivateItem()에서 GameState->AddScore(), OnCoinCollected()
- 모든 코인을 모으면 즉시 EndLevel()
레벨 종료
- EndLevel()에서 CurrentLevelIndex++
- 남은 레벨이 있으면 UGameplayStatics::OpenLevel(...)로 다음 맵 로드
- 더 이상 레벨이 없으면 OnGameOver()
다음 맵 로드 시
- 새로운 GameState가 생성 → 다시 BeginPlay() → StartLevel()
- 이전 레벨에서 유지하고 싶은 정보는 GameInstance나 “Seamless Travel” 등을 통해 별도로 관리해야 함
Game Over
- 로그 출력 (추후 UI 표시로 전환)

캐릭터 체력 및 점수 관리 시스템 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Thu, 11 Jun 2026 16:48:24 +0900

캐릭터 체력 및 점수 관리 시스템 구현하기

캐릭터 체력 시스템 구현하기

1️⃣ 캐릭터 클래스에 체력 변수 및 함수 선언

PlayerState를 쓰지 않는 이유
- PlayerState: 각 플레이어마다의 어떤 정보를 관리해주는 클래스
- 언리얼 엔진에서 PlayerState는 주로 멀티플레이 환경에서 각 플레이어 간 데이터 동기화를 위해 사용합니다.
  - 예를 들어, 점수나 킬/데스 카운트처럼 서버와 클라이언트 모두가 공통으로 확인해야 하는 정보를 저장하죠.
- 하지만 싱글 플레이 게임에서는 이런 동기화가 필요 없으므로, 캐릭터 클래스자체에 체력이나 스코어 변수를 넣어 관리해도 충분합니다.
- 그럼에도 추후 확장성 생각하면 PlayerState 가 더 좋을 수 있지만 우선은 이렇게 합니다.
캐릭터 클래스에 체력 관리 로직 추가
- 싱글 플레이 환경을 가정하여, 플레이어 캐릭터를 담당하는 클래스에 체력 관리용 변수를 선언합니다.

MaxHealth: 캐릭터의 최대 체력을 나타냅니다.
Health: 캐릭터의 현재 체력을 나타냅니다.
TakeDamage(): 데미지를 받았을 때 호출되는 함수로, 내부에서 체력을 감소시키는 로직을 처리합니다.

AddHealth(): 아이템 등을 통해 체력을 회복할 때 호출하는 함수로, 내부에서 체력을 회복시킵니다.
OnDeath(): 체력이 0 이하가 되었을 때 호출되는 사망 처리 함수입니다.

(BlueprintPure: Get함수 사용시 주로 사용됩니다)

2️⃣ 데미지 및 회복 처리

언리얼 엔진에는 데미지 시스템을 간편히 사용할 수 있는 UGameplayStatics::ApplyDamage(데미지 발생)와 AActor::TakeDamage(데미지 처리) 함수가 제공됩니다.
데미지 처리 흐름 (ApplyDamage → TakeDamage)
1. UGameplayStatics::ApplyDamage
  - 공격자 (또는 폭발물 등)가 데미지를 줄 대상 액터와 데미지 양, 데미지를 유발한 주체 등을 인자로 넘겨 호출합니다.
  - 내부적으로 대상 액터의 TakeDamage() 함수를 호출하려 시도합니다.
2. AActor::TakeDamage
  - Actor의 가상 함수입니다. 모든 액터가 기본적으로 이 함수를 가지고 있으며, 필요하다면 자식 클래스(캐릭터 등)에서 오버라이드할 수 있습니다.
  - 실제로 체력 감소 또는 특수한 데미지 처리 로직을 이 안에서 구현하게 됩니다.

AddHealth(float Amount)
- 체력을 일정 양만큼 회복합니다.
- FMath::Clamp를 통해 최대 체력을 초과하지 않도록 제한합니다.
TakeDamage(...)
- 언리얼 엔진의 기본 데미지 시스템을 사용하는 대표적인 함수입니다.
- DamageAmount: 데미지 값
- EventInstigator: 데미지를 유발한 주체(Controller)
- DamageCauser: 데미지를 직접 발생시킨 오브젝트(총알, 폭발물 등)
- 반환값: 실제 적용된 데미지(기본 로직에서는 DamageAmount와 동일한 경우가 많지만, 게임 상황에 따라 감소 또는 증폭 등을 처리할 수도 있습니다.)
OnDeath()
- 체력이 0 이하로 떨어졌을 때 사망 로직을 처리하는 함수입니다.
- 흔히 입력 비활성화, Ragdoll 적용, 사망 애니메이션 재생 등을 수행합니다.

MainCharacter.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Character.h"
#include "MainCharacter.generated.h"

// 미리 선언
// 전방 선언(Forward Declaration) 
class USpringArmComponent; // 스프링 암 관련 클래스 헤더
class UCameraComponent; // 카메라 관련 클래스 전방 선언


// Enhanced Input에서 액션 값을 받을 때 사용하는 구조체
struct FInputActionValue;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainCharacter : public ACharacter
{
	GENERATED_BODY()

public:
	// Sets default values for this character's properties
	AMainCharacter();
	
	
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Camera")
	USpringArmComponent* SpringArmComp  = nullptr;
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Camera")
	UCameraComponent* CameraComp = nullptr;
	
	// 현재 체력을 가져오는 함수
	UFUNCTION(BlueprintPure, Category = "Health")
	float GetHealth() const;
		
	// 체력을 회복시키는 함수
	UFUNCTION(BlueprintCallable, Category = "Health")
	void AddHealth(float Amount);
	
protected:
	
	// === Variables ===
	// 최대 체력
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Health")
	float  MaxHealth;
	// 현재 체력
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category = "Health")
	float  Health;
	
	// = Movements
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Movement")
	float NormalSpeed; // 기본 걷기 속도
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Movement")
	float SprintSpeedMultiplier;  // "기본 속도" 대비 몇 배로 빠르게 달릴지
	
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Movement")
	float SprintSpeed; 	// 실제 스프린트 속도 SprintSpeed= NormalSpeed * SprintSpeedMultiplier
	
	
	// =====	
	
	// Called to bind functionality to input
	virtual void SetupPlayerInputComponent(class UInputComponent* PlayerInputComponent) override;	
	
	UFUNCTION()
	void Move(const FInputActionValue& value);
	
	UFUNCTION()
	void Look(const FInputActionValue& value);
	
	// on off 의 형태의 것들은 그냥 나눠 주는 것이 좋다
	// 왜냐하면 이전에는 세세하게 처리하기가 상당이 까다로웠는데
	// EnhancedInputSystem은 그것들을 매우 편하게 변경해주었기 때문에 왠만하면 나눠 주는 것이 좋다
	UFUNCTION()
	void StartJump(const FInputActionValue& value);
	UFUNCTION()
	void StopJump(const FInputActionValue& value);
	
	UFUNCTION()
	void StartSprint(const FInputActionValue& value);
	UFUNCTION()
	void StopSprint(const FInputActionValue& value);
	
	
	// 사망 처리 함수 (체력이 0 이하가 되었을 때 호출)
	UFUNCTION(BlueprintCallable, Category = "Health")
	virtual void OnDeath();

	// 데미지 처리 함수 - 외부로부터 데미지를 받을 때 호출됨
	// 또는 AActor의 TakeDamage()를 오버라이드
	virtual float TakeDamage(
		float DamageAmount,
		struct FDamageEvent const& DamageEvent, // Damage 관련 추가 정보 (예: Skill 속성에 따른 반응) 
		AController* EventInstigator, //데미지를 발생 시킨 주체
		AActor* DamageCauser // 데미지를 일으킨 오브젝트
		) override;
	
};

MainCharacter.cpp

#include "MainCharacter.h"
#include "EnhancedInputComponent.h"
//#include "InputActionValue.h"
#include "MainPlayerController.h"

// 카메라, 스프링 암 실제 구현이 필요한 경우라서 include
// 전방 선언(Forward Declaration) 한것 여기서 (실질적으로 사용하는곳) 포함
#include "Camera/CameraComponent.h"
#include "GameFramework/SpringArmComponent.h" 

//
#include "GameFramework/CharacterMovementComponent.h" // GetCharacterMovement() 사용을 위해
#include "GameFramework/Actor.h"
#include "Kismet/GameplayStatics.h"

AMainCharacter::AMainCharacter()
{ 	
	PrimaryActorTick.bCanEverTick = false;	
	
	// (1) 스프링 암 생성
	SpringArmComp = CreateDefaultSubobject<USpringArmComponent>(TEXT("SpringArm"));
	// 스프링 암을 루트 컴포넌트 (CapsuleComponent)에 부착
	SpringArmComp->SetupAttachment(RootComponent);
	// 캐릭터와 카메라 사이의 거리 기본값 300으로 설정
	SpringArmComp->TargetArmLength = 300.0f;  
	// 컨트롤러 회전에 따라 스프링 암도 회전하도록 설정
	SpringArmComp->bUsePawnControlRotation = true;  
	
	
	//

	// (2) 카메라 컴포넌트 생성
	CameraComp = CreateDefaultSubobject<UCameraComponent>(TEXT("Camera"));
	// 스프링 암의 소켓 위치에 카메라를 부착
	CameraComp->SetupAttachment(SpringArmComp, USpringArmComponent::SocketName);
	// 카메라는 스프링 암의 회전을 따르므로 PawnControlRotation은 꺼둠
	CameraComp->bUsePawnControlRotation = false;
	
	// Movements & Sprint Speed
	
	NormalSpeed = 600.0f;
	SprintSpeedMultiplier = 1.75f;
	SprintSpeed = NormalSpeed * SprintSpeedMultiplier;

	
	// #include "GameFramework/CharacterMovementComponent.h" 추가해야함
	// MaxWalkSpeed 변경시 캐릭터 이동속도가 즉시 변경
	GetCharacterMovement()->MaxWalkSpeed = NormalSpeed;
	
	
	// 초기 체력 설정
	MaxHealth = 100.0f;
	Health = MaxHealth;
}


// Called to bind functionality to input
void AMainCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
	Super::SetupPlayerInputComponent(PlayerInputComponent);
	// Enhanced InputComponent로 캐스팅
    if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(PlayerInputComponent))
    {
        // IA를 가져오기 위해 현재 소유 중인 Controller를 AMainPlayerController로 캐스팅
        if (AMainPlayerController* PlayerController = Cast<AMainPlayerController>(GetController()))
        {
        	// null check
            if (PlayerController->MoveAction)
            {
                // IA_Move 액션 키를 "키를 누르고 있는 동안" Move() 호출
                EnhancedInput->BindAction(
                    PlayerController->MoveAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::Move
                );
            }
            
            if (PlayerController->JumpAction)
            {
                // IA_Jump 액션 키를 "키를 누르고 있는 동안" StartJump() 호출
                EnhancedInput->BindAction(
                    PlayerController->JumpAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::StartJump
                );
                
                // IA_Jump 액션 키에서 "손을 뗀 순간" StopJump() 호출
                EnhancedInput->BindAction(
                    PlayerController->JumpAction,
                    ETriggerEvent::Completed,
                    this,
                    &AMainCharacter::StopJump
                );
            }
            
            if (PlayerController->LookAction)
            {
                // IA_Look 액션 마우스가 "움직일 때" Look() 호출
                EnhancedInput->BindAction(
                    PlayerController->LookAction,
                    ETriggerEvent::Triggered,
                    this,
                    &AMainCharacter::Look
                );
            }
            
            if (PlayerController->SprintAction)
            {
                // IA_Sprint 액션 키를 "누르고 있는 동안" StartSprint() 호출
                EnhancedInput->BindAction(
                    PlayerController->SprintAction,
                    ETriggerEvent::Triggered,                   
                    this, 
                    &AMainCharacter::StartSprint
                );
                // IA_Sprint 액션 키에서 "손을 뗀 순간" StopSprint() 호출
                EnhancedInput->BindAction(
                    PlayerController->SprintAction, 
                    ETriggerEvent::Completed, 
                    this, 
                    &AMainCharacter::StopSprint
                );
            }    
        }
    }

}

void AMainCharacter::Move(const FInputActionValue& value)
{
	// 컨트롤러가 있어야 방향 계산이 가능
	if (!Controller) return;

	// Value는 Axis2D로 설정된 IA_Move의 입력값 (WASD)을 담고 있음
	// 예) (X=1, Y=0) → 전진 / (X=-1, Y=0) → 후진 / (X=0, Y=1) → 오른쪽 / (X=0, Y=-1) → 왼쪽
	const FVector2D MoveInput = value.Get<FVector2D>();

	// IsNearlyZero
	// 부동소수점들은 딱 0으로 안 떨어 질 수도 있기 때문에 작은 오차들은 0으로 처리 하기 위한 함수
	if (!FMath::IsNearlyZero(MoveInput.X))
	{		
		// 캐릭터가 바라보는 방향(정면)으로 X축 이동
		AddMovementInput(GetActorForwardVector(), MoveInput.X);
	}

	if (!FMath::IsNearlyZero(MoveInput.Y))
	{
		// 캐릭터의 오른쪽 방향으로 Y축 이동
		AddMovementInput(GetActorRightVector(), MoveInput.Y);
	}
}

void AMainCharacter::Look(const FInputActionValue& value)
{
	// 마우스의 X, Y 움직임을 2D 축으로 가져옴
	FVector2D LookInput = value.Get<FVector2D>();

	// X는 좌우 회전 (Yaw), Y는 상하 회전 (Pitch)
	// 좌우 회전
	AddControllerYawInput(LookInput.X);
	
	// 상하 회전
	// IA에서 반전해둔 상태
	// 여기엔 추후 변경 가능한 옵션 추가해주자
	AddControllerPitchInput(LookInput.Y);
}

void AMainCharacter::StartJump(const FInputActionValue& value)
{
	// Jump 함수는 Character가 기본 제공
	if (value.Get<bool>())
	{
		Jump();
	}
}
void AMainCharacter::StopJump(const FInputActionValue& value)
{	
	// StopJumping 함수도 Character가 기본 제공
	if (!value.Get<bool>())
	{
		StopJumping();
	}	
}

void AMainCharacter::StartSprint(const FInputActionValue& value)
{
	// Shift 키를 누른 순간 이 함수가 호출된다고 가정
	// 스프린트 속도를 적용
	if (GetCharacterMovement())
	{
		// 중간에 변경시 
		SprintSpeed = NormalSpeed * SprintSpeedMultiplier;		
		
		GetCharacterMovement()->MaxWalkSpeed = SprintSpeed;
	}

}
void AMainCharacter::StopSprint(const FInputActionValue& value)
{
	// Shift 키를 뗀 순간 이 함수가 호출
	// 평상시 속도로 복귀
	if (GetCharacterMovement())
	{
		GetCharacterMovement()->MaxWalkSpeed = NormalSpeed;
	}
}


float AMainCharacter::GetHealth() const
{
	return Health;
}

// 체력 회복 함수
void AMainCharacter::AddHealth(float  Amount)
{
	// 체력을 회복시킴. 최대 체력을 초과하지 않도록 제한함
	Health = FMath::Clamp(Health + Amount, 0.0f, MaxHealth);
	//UE_LOG(LogTemp, Log, TEXT("Health increased to: %f"), Health);
	
	if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Green,
				 TEXT("Health Increased to: %f"), Health);
	}
}

// 데미지 처리 함수
float  AMainCharacter::TakeDamage(float  DamageAmount, FDamageEvent const& DamageEvent, AController* EventInstigator, AActor* DamageCauser)
{
	// 기본 데미지 처리 로직 호출 (필수는 아님)
	int32 ActualDamage = Super::TakeDamage(DamageAmount, DamageEvent, EventInstigator, DamageCauser);

	// 체력을 데미지만큼 감소시키고, 0 이하로 떨어지지 않도록 Clamp
	Health = FMath::Clamp(Health - DamageAmount, 0.0f, MaxHealth);
	//UE_LOG(LogTemp, Warning, TEXT("Health decreased to: %f"), Health);
	if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Yellow,
				 TEXT("Health decreased to: %f"), Health);
	}

	// 체력이 0 이하가 되면 사망 처리
	if (Health <= 0.0f)
	{
		OnDeath();
	}

	// 실제 적용된 데미지를 반환
	return ActualDamage;
}

// 사망 처리 함수
void AMainCharacter::OnDeath()
{
	//UE_LOG(LogTemp, Error, TEXT("Character is Dead!"));
	if (GEngine)
	{ 
		GEngine->AddOnScreenDebugMessage(
				-1, 2.f, FColor::Red,
				 TEXT("Character is Dead!"));
	}

	// 사망 후 로직
}

3️⃣ 지뢰 아이템 데미지 함수 수정

지뢰 아이템 (MineItem)이 폭발할 때, 주변 액터에게 데미지를 주려면 UGameplayStatics::ApplyDamage 함수를 호출해 해당 액터의 TakeDamage()가 실행되도록 하면 됩니다.

UGamePlayStatics::ApplyDamage() 라는 UE Static 제공 함수.
#include "Kismet/GameplayStatics.h" 해줘야 합니다.
UGameplayStatics::ApplyDamage는 언리얼 엔진에서 액터에게 손쉽게 데미지를 가하고 대상의 TakeDamage() 함수를 트리거하는 핵심 함수입니다

UGameplayStatics::ApplyDamage(
    AActor* DamagedActor,           // 데미지를 받을 대상 액터
    float BaseDamage,               // 기본 데미지 양
    AController* EventInstigator,   // 데미지를 입힌 주체의 컨트롤러 (데스 카운트 등에 사용)
    AActor* DamageCauser,           // 데미지를 실제로 발생시킨 액터 (무기, 투사체 등)
    TSubclassOf<UDamageType> DamageTypeClass // 데미지 타입 클래스
);

ApplyDamage()
1. 대상 액터(Actor)가 존재하는지 확인.
2. 대상 액터의 TakeDamage() 함수를 호출합니다.
3. DamageType은 여러 가지 파생 클래스를 만들어 물리/화염/독 등 다양한 데미지 유형을 정의할 수 있습니다 (지금은 기본값 사용).
지뢰는 독립적으로 스폰된 뒤 폭발하므로 EventInstigator를 nullptr로 둡니다.
- 멀티플레이에서 “누가 지뢰를 설치했느냐”를 추적하려면, 생성 시점에 Instigator나 Controller 정보를 넣어줄 수도 있습니다.

#include "MineItem.h"
#include "Components/SphereComponent.h"
#include "Kismet/GameplayStatics.h"

AMineItem::AMineItem()
{
	ExplosionDelay = 5.0f;
	ExplosionRadius = 300.0f;
	ExplosionDamage = 30.0f;
	ItemType = "Mine";
    
	ExplosionCollision = CreateDefaultSubobject<USphereComponent>(TEXT("ExplosionCollision"));
	ExplosionCollision->InitSphereRadius(ExplosionRadius);
	//ExplosionCollision->SetCollisionProfileName(TEXT("OverlapAllDynamic")); 
	ExplosionCollision->SetCollisionProfileName(CollisionProfile_OverlapAllDynamic); 
	ExplosionCollision->SetupAttachment(Scene);
}

void AMineItem::ActivateItem(AActor* Activator)
{
	// 5초 후 폭발 실행
	GetWorld()->GetTimerManager().SetTimer(ExplosionTimerHandle, this, &AMineItem::Explode, ExplosionDelay);
}

void AMineItem::Explode()
{
	TArray<AActor*> OverlappingActors;
	ExplosionCollision->GetOverlappingActors(OverlappingActors);

	for (AActor* Actor : OverlappingActors)
	{
		if (Actor && Actor->ActorHasTag("Player"))
		{
			//GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("Player damaged %d by MineItem"), ExplosionDamage));
			
			// 데미지를 발생시켜 Actor->TakeDamage()가 실행되도록 함
			UGameplayStatics::ApplyDamage(
				Actor,                      // 데미지를 받을 액터
				ExplosionDamage,            // 데미지 양
				nullptr,                    // 데미지를 유발한 주체 (지뢰를 설치한 캐릭터가 없으므로 nullptr)
				this,                       // 데미지를 유발한 오브젝트(지뢰)
				UDamageType::StaticClass()  // 기본 데미지 유형
			);
			
			
		}
	}

	// 지뢰 제거
	DestroyItem();
}

4️⃣ 힐링 아이템 체력 회복 함수 수정

아래 코드는 힐링 아이템(HealingItem)이 플레이어를 회복시킵니다. AddHealth() 함수를 직접 호출해 체력을 증가시킵니다.

ActorHasTag("Player")로 플레이어인지 판별하는 단순 로직입니다.
- 캐릭터를 구분하는 더 안전한 방법(예: Cast<AMainCharacter>(Activator))을 쓰거나, Collision 채널을 이용하는 식으로도 바꿀 수 있습니다.
AddHealth()에서 FMath::Clamp를 사용해 최대 체력 이상으로 올라가지 않도록 제한합니다.

점수 관리 시스템 구현하기

1️⃣ GameMode와 GameState의 연계 이해하기

언리얼 엔진에서 GameMode와 GameState는 게임의 전역 정보를 유지하고, 필요할 경우 멀티플레이어 환경에서 해당 정보를 서버와 클라이언트 간에 동기화하는 역할을 합니다.
- GameMode
  - “게임의 규칙(룰)”을 정의하고 관리합니다.
  - 어떤 캐릭터를 스폰할지, 플레이어가 사망했을 때 어떻게 처리할지를 결정합니다.
  - 멀티플레이에서는 서버 전용으로 동작합니다(클라이언트에는 존재하지 않음).
- GameState
  - 게임 플레이 전반에서 “공유되어야 하는 전역 상태”를 저장합니다. GameState는 기본적으로 “레벨당 1개” 존재하며, 엔진 내부에서 데이터 동기화를 고려해 설계되었기에 전역 데이터 관리용으로 적합합니다.
  - 대표적으로 점수, 남은 시간, 현재 게임 단계(Phase), 스폰된 오브젝트의 총 개수 등을 저장합니다.
  - 멀티플레이에서는 서버가 관리하고, 클라이언트는 이를 자동으로 동기화 받아볼 수 있습니다.
싱글 플레이에서도 GameState가 굳이 필요 없을 것 같지만, “전역적으로 공유해야 할 정보”를 한 군데서 관리하면 유지보수가 더 편해집니다. “몇 개의 아이템이 스폰되었는지”, “현재 게임 진행도는 어느 정도인지” 같은 데이터를 GameState에서 일괄 관리할 수 있기 때문입니다.
예시: 전역적인 스폰 제한 로직
- “현재 게임에 스폰된 아이템이 30개를 넘으면, 더 이상 아이템을 스폰하지 않는다.”
- 이 로직을 GameState에 두고 관리한다면:
  1. GameState 내부에서 “스폰된 아이템 개수” 변수를 관리
  2. 스폰이 일어날 때마다 이 변수를 증가시키고, 30개를 초과하는지 체크
  3. 초과 시 GameMode(또는 스폰 시스템)에서 “더 이상 스폰 금지” 로직 적용
- 이처럼 전역적으로 공유되어야 할 데이터(점수, 스폰 개수, 타이머 등)는 GameState에 저장하고, 게임 규칙이나 흐름을 제어하는 로직은 GameMode 또는 별도의 매니저 클래스로 분리하는 것이 일반적입니다.

2️⃣ GameState에 점수 데이터 및 함수 추가

이번에는 전역 점수를 GameState에 저장하고, 누군가 점수를 획득할 때마다 AddScore()를 호출해 점수가 증가하도록 구현해봅니다.
언리얼 에디터에서 C++ Class → GameStateBase를 선택하고, 클래스 이름을 MainGameStateBase 라고 짓습니다.
Main GameStateBase.h와 MainGameStateBase.cpp에 아래와 같이 코드를 작성합니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/GameState.h"
#include "MainGameState.generated.h"


UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMainGameState : public AGameState
{
	GENERATED_BODY()
	
public:
	AMainGameState();	
	
	// === Variables ===
	// 전역 점수를 저장하는 변수
	UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category="Score")
	int32 Score;

	
	// === Func ===
	// 현재 점수를 읽는 함수
	UFUNCTION(BlueprintPure, Category="Score")
	int32 GetScore() const;
	
	// 점수를 추가해주는 함수
	UFUNCTION(BlueprintCallable, Category="Score")
	void AddScore(int32 Amount);
	
};

#include "MainGameState.h"

AMainGameState::AMainGameState()
{
	
}

int32 AMainGameState::GetScore() const
{
	return Score;
}

void AMainGameState::AddScore(int32 Amount)
{
	Score += Amount;
}

3️⃣ GameMode와 GameState 연동

다음으로, 기존에 만들었던 GameMode 클래스에서 GameStateClass 멤버를 우리가 만든 MainGameState로 설정해줍니다.

방금 만든 MainGameState 에 대한 C++ 코드가 컴파일되면, 언리얼 에디터에서 해당 클래스를 인식하게 됩니다.
MainGameState 를 더 확장하거나 블루프린트 비주얼 스크립팅을 사용하기 위해, C++ 클래스를 부모로 하는 블루프린트(BP_ MainGameState)를 만들어서 사용합니다.
Project Settings 적용
- Edit → Project Settings → Maps & Modes로 들어가서 Default GameMode를 우리 커스텀 게임 모드( MainGameState 또는 그 블루프린트 클래스)로 설정합니다.
- 그 뒤 Game State Class도 BP_MainGameState (또는 MainGameState )로 맞춰주면, 전역적으로 이 설정이 적용됩니다.
World Settings에서 설정 (레벨별로 오버라이드 가능)

#include "MainGameMode.h"
#include "MainCharacter.h"
#include "MainPlayerController.h"
#include "MainGameState.h"

AMainGameMode::AMainGameMode()
{
	// StaticClass(): 클래스 이름을 통해서 호출해주는것
	DefaultPawnClass = AMainCharacter::StaticClass();
	//
	PlayerControllerClass = AMainPlayerController::StaticClass();
	GameStateClass = AMainGameState::StaticClass();
}

4️⃣ 코인 아이템 점수 획득 함수 수정

GetWorld()->GetGameState<AMainGameState>()로 게임 스테이트를 가져오고, AddScore(PointValue) 함수를 호출해 점수를 올립니다.
PointValue(int32)는 이 코인 아이템이 제공하는 점수량이며, ACoinItem의 멤버 변수로 관리하고 있습니다.
이 과정을 통해 플레이어가 코인을 획득하면, 전역적으로 관리되는 GameState에서 점수가 증가하고, 코인은 사라져서 한 번만 획득되도록 처리됩니다.

#include "CoinItem.h"
#include "Engine/World.h"
#include "MainGameState.h"

ACoinItem::ACoinItem()
{
	// 부모클래스라 안해도 되지만 
	// 점수 기본값을 0으로 설정
	PointValue = 0;
	ItemType = "DefaultCoin";
}

void ACoinItem::ActivateItem(AActor* Activator)
{
	// 플레이어 태그 확인
	if (Activator && Activator->ActorHasTag("Player"))
	{
		// 점수 획득 디버그 메시지
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, 
			FString::Printf(TEXT("Player Gained %i Points!"), PointValue));
        
		if (UWorld* World = GetWorld())
		{
			if (AMainGameState* GameState = World->GetGameState<AMainGameState>())
			{
				GameState->AddScore(PointValue);
			}
		}
		
		// 부모 클래스 (BaseItem)에 정의된 아이템 파괴 함수 호출
		DestroyItem();
	}
}

아이템 스폰 및 레벨 데이터 관리하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Thu, 11 Jun 2026 15:03:18 +0900

아이템 스폰 및 레벨 데이터 관리하기

랜덤 위치에 아이템 스폰하기

1️⃣ 레벨 셋팅하기

Resources 폴더에 Maps 폴더에는 3개의 레벨이 이미 존재합니다. 각각 난이도에 따라서 크기가 다른 맵이고, BasicLevel- Intermediate Level- Advanced Level 순서로 크기가 작아집니다.

위 3개의 레벨을 Content - Maps 폴더로 이동 시킨 후, 기존에 사용하던 MainLevel에서 BasicLevel을 기본 레벨로 지정합니다.
- Edit - Project Settings - Maps & Modes에서 Defaults Maps를 BasicLevel로 변경을 해줍니다.
MainLevel은 삭제를 해줍니다.

2️⃣ 콜리전 컴포넌트로 스폰 영역 지정하기

스폰 영역을 지정할 수 있는 방법은 여러 방식이 있고, 가장 정교한 방법중 하나인 수학적 알고리즘으로 정의 할 수도 있지만 여기서는 조금더 간단하게 지정하겠습니다.
언리얼 엔진에서는 직접 지정한 박스(상자), 구체, 캡슐 등 원하는 형태의 ‘콜리전 컴포넌트’ 내부에서 임의의 좌표를 뽑아 아이템(액터)을 스폰할 수 있습니다.
이번에는 우리가 만든 아이템들을 레벨 상에서 자연스럽게 랜덤 배치하려고 합니다. 가장 간단한 방법으로, 콜리전 컴포넌트인 UBoxComponent를 활용해보겠습니다.
우선, 새로운 C++ 클래스 Actor를 상속한 클랫스로, SpawnVolume 이라는 이름으로 클래스를 하나 생성합니다.

UBoxComponent* SpawningBox;

이 컴포넌트가 박스 형태의 콜리전 영역을 나타냅니다.
언리얼 엔진의 UBoxComponent는 박스 내부에서 오버랩(Overlap)이나 충돌(Collision)을 감지할 수 있는 컴포넌트입니다.
실제로 눈에 보이는 3D 메시는 아니며, “박스 형태의 충돌 범위”만 제공합니다.

GetRandomPointInVolume()

SpawningBox 범위 내부에서 랜덤 좌표(FVector)를 리턴합니다.
이 좌표를 이용해 아이템을 생성하면 “직육면체 형태 범위 안에서” 임의의 위치에 아이템이 뜨는 효과를 낼 수 있습니다.

SpawnItem(TSubclassOf<AActor> ItemClass);

파라미터로 받은 아이템 클래스를 SpawnVolume 내부의 랜덤 위치에 생성(SpawnActor)하는 함수입니다.

TSubclassOf<AActor>: 하위 클래스까지도 전부 다 포함해서 지정해 줄 수 있는 템플릿.

하드 레퍼런스: 클래스가 항상 메모리에 로드된 상태에서 바로 접근
반대로 소프트 레퍼런스인: TSoftClassPtr 도 존재합니다
소프트 레퍼런스: 클래스의 경로만 유지합니다. 그래서 만약에 해단되는 어떤 클래스가 필요한 상황이 되면 그때 가서 메모리에 로드를 하게 됩니다.

GetScaledBoxExtent()

박스 컴포넌트의 실제 “가로/세로/높이 절반 길이(Extent)”를 반환합니다 (중심에서 끝부분 까지의 길이이기 때문에 절반 길이입니다). 에디터에서 Scale을 조절하면 여기에도 반영됩니다.

GetComponentLocation()

컴포넌트의 위치 = 현재 우리가 사용하려는 BoxOrigin의 위치

FMath::FRandRange(a, b)

a ~ b 사이 임의의 float 값을 반환합니다.
여기서는 X, Y, Z 좌표마다 랜덤 값을 생성하여 BoxOrigin에 더해줍니다.

SpawnActor

AKAsset* SpawnedActor1 = (AKAsset*) GetWorld()->SpawnActor(AKAsset::StaticClass(), NAME_None, &Location);

AActor* UWorld::SpawnActor
(
    UClass* Class,
    FName InName,
    FVector const* Location,
    FRotator const* Rotation,
    AActor* Template,
    bool bNoCollisionFail,
    bool bRemoteOwned,
    AActor* Owner,
    APawn* Instigator,
    bool bNoFail,
    ULevel* OverrideLevel,
    bool bDeferConstruction
)

Spawning Actors in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Methods of creating new instances of Actors in gameplay code.

dev.epicgames.com

SpawnVolume.h

#pragma once

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

class UBoxComponent;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API ASpawnVolume : public AActor
{
	GENERATED_BODY()
	
public:	
	// Sets default values for this actor's properties
	ASpawnVolume();
	
	// 우선 테스트라 public으로
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Spawning")
    USceneComponent* Scene;
    // 스폰 영역을 담당할 박스 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Spawning")
    UBoxComponent* SpawningBox;

    // 스폰 볼륨 내부에서 무작위 좌표를 얻어오는 함수
    UFUNCTION(BlueprintCallable, Category="Spawning")
    FVector GetRandomPointInVolume() const;
    // 특정 아이템 클래스를 스폰하는 함수
    UFUNCTION(BlueprintCallable, Category="Spawning")
    void SpawnItem(TSubclassOf<AActor> ItemClass);
	virtual void Tick(float DeltaTime) override;

};

SpawnVolume .cpp

#include "SpawnVolume.h"
#include "Components/BoxComponent.h"
#include "Engine/World.h"
#include "GameFramework/Actor.h"

ASpawnVolume::ASpawnVolume()
{
	PrimaryActorTick.bCanEverTick = false;

	// 박스 컴포넌트를 생성하고, 이 액터의 루트로 설정
	Scene = CreateDefaultSubobject<USceneComponent>(TEXT("Scene"));
	SetRootComponent(Scene);
    
	SpawningBox = CreateDefaultSubobject<UBoxComponent>(TEXT("SpawningBox"));
	SpawningBox->SetupAttachment(Scene);
}

FVector ASpawnVolume::GetRandomPointInVolume() const
{
	// 1) 박스 컴포넌트의 스케일된 Extent, 즉 x/y/z 방향으로 반지름(절반 길이)을 구함
	FVector BoxExtent = SpawningBox->GetScaledBoxExtent();
	// 2) 박스 중심 위치
	FVector BoxOrigin = SpawningBox->GetComponentLocation();

	// 3) 각 축별로 -Extent ~ +Extent 범위의 무작위 값 생성
	return BoxOrigin + FVector(
		FMath::FRandRange(-BoxExtent.X, BoxExtent.X),
		FMath::FRandRange(-BoxExtent.Y, BoxExtent.Y),
		FMath::FRandRange(-BoxExtent.Z, BoxExtent.Z)
	);
}

void ASpawnVolume::SpawnItem(TSubclassOf<AActor> ItemClass)
{
	if (!ItemClass) return;

	GetWorld()->SpawnActor<AActor>(
		ItemClass,
		GetRandomPointInVolume(),
		FRotator::ZeroRotator
	);
}

3️⃣ 아이템 랜덤 스폰 테스트하기

빌드를 하고 언리얼 에디터로 돌아와서 이 SpawnVolume 클래스를 상속받은 BP_SpawnVolume Blueprint 클래스를 생성합니다.

BP_SpawnVolume을 레벨에 드래그해 놓고, 적절히 위치와 스케일을 조정합니다.

3개의 레벨 모두 이렇게 BP_SpawnVolume 을 맵의 크기에 맞게 적절하게 셋팅을 해줍니다.

2. 아이템 스폰 확률 데이터 테이블 만들기

1️⃣Item Data 구조체 만들기

어떤 아이템이 몇 % 확률로 스폰되는지를 코드로 직접 하드코딩하면, 매번 수정할 때마다 빌드를 해줘야 해서 번거롭습니다.
언리얼 엔진의 데이터 테이블을 사용하면, 이를 엑셀 (CSV)이나 JSON 파일로 관리해서 엔진 안으로 임포트하고, 코드나 블루프린트에서 쉽게 불러 쓸 수 있습니다. 기획자나 디자이너도 엑셀에서 숫자만 바꾸면 되므로 매우 편리합니다.
우선, 데이터 테이블의 각 “행(Row)”을 C++ 구조체로 매핑해야 합니다. 언리얼 엔진은 FTableRowBase라는 기본 구조체를 제공하며, 이를 상속한 구조체를 만들면, 각 CSV (또는 JSON) 행을 FItemSpawnRow 구조체에서 정해준 형태로 받아올 수 있게 됩니다.
이러한 구조체는 클래스가 아니기 때문에, 부모 클래스를 선택할 수 있는 옵션에 나타나지 않습니다. 따라서 None을 선택해서 ItemSpawnRow C++ 파일을 만들어줍니다.

#pragma once

#include "CoreMinimal.h"
#include "Engine/DataTable.h" // FTableRowBase 정의가 들어있는 헤더
#include "ItemSpawnRow.generated.h"

USTRUCT(BlueprintType)
struct FItemSpawnRow : public FTableRowBase
{
	GENERATED_BODY()

public:
	// 아이템 이름
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
	FName ItemName;
	
	// 어떤 아이템 클래스를 스폰할지
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
	TSubclassOf<AActor> ItemClass; // 원래는 소프트 레퍼런스인 TSoftClassPtr 로 하는게 맞습니다.
	// 이 아이템의 스폰 확률
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
	float SpawnChance;
};

FTableRowBase
- 언리얼 엔진에서 “이 구조체는 데이터 테이블로 쓸 수 있다”라고 인식하게 해주는 베이스 구조체입니다.
TSoftClassPtr<AActor>
- 소프트 레퍼런스로, 클래스를 바로 로드하지 않고도 경로만 기억해둘 수 있습니다.
- 필요할 때 Get()을 통해 실제 UClass*를 얻어 인스턴스를 생성할 수 있습니다.

2️⃣ CSV 파일 작성 및 임포트하기 (방법 1)

엑셀을 열고 2열부터 Column 이름을 작성합니다.
1열은 “RowName”으로 인식됩니다. Key 값으로 사용할 값을 입력해줘야 합니다.
2열부터는 각 아이템 (데이터) 정보를 한 줄씩 기록합니다.
경로는 각 BP 클래스 우클릭 → Copy Reference 로 정확히 가져옵니다. 그리고 블루프린트의 경우 뒤에 "_C"가 붙어야 BP 클래스로 인식되니까 마지막에 반드시 붙여주세요.
- Copy Reference는 언리얼 엔진 런타임에서 사용되는 “클래스/오브젝트” 경로입니다.
  - 블루프린트/C++로 자산 로드 시 ConstructorHelpers::FClassFinder 등에서 활용.
CSV로 저장
- 언리얼 콘텐츠 폴더가 아니라 본인이 편한 로컬 위치에 파일명 ItemSpawnTable.csv 로 **CSV UTF-8 (쉼표로 분리)**로 저장합니다.
언리얼 에디터로 돌아와, Content Browser에서 Blueprints 폴더에서 우클릭 → Import to /Game/Blueprints 를 선택, 아래와 같이 옵션을 설정하고 Apply를 클릭해줍니다.
그러면 다음과 같이 성공적으로 DatTable이 만들어진 것을 볼 수 있습니다.
- 만약 CSV 파일에서 데이터가 업데이트되었을 경우 Reimport를 해주면 됩니다.

3️⃣ 언리얼 에디터에서 직접 데이터 테이블 수정하기 (방법 2)

CSV를 쓰는 대신, 언리얼 에디터 내에서 직접 편집하는 방법도 있습니다.
1. Content Browser 창에서 우클릭 → Miscellaneous → Data Table 선택
2. 팝업창에서 Row Structure로 FItemSpawnRow를 선택하고 OK
3. 새로 생성된 DataTable 에셋을 열면, 에디터 UI 상에서 아래처럼 Row 정보를 바로 편집 가능합니다.
  - Add Row 버튼을 눌러 행을 추가하고, Row Name, ItemName, ItemClass, SpawnChance 등을 원하는 값으로 넣습니다.
하지만 이런 방식은 Excel처럼 대량의 데이터를 한 번에 편집하기는 불편할 수 있습니다.
상황에 따라 에디터 직접 편집 / CSV 임포트 모두 필요에 따라 병행할 수도 있습니다. </aside><aside>

아이템 스폰 확률 데이터 테이블 만들기

1️⃣Item Data 구조체 만들기

어떤 아이템이 몇 % 확률로 스폰되는지를 코드로 직접 하드코딩하면, 매번 수정할 때마다 빌드를 해줘야 해서 번거롭습니다.
언리얼 엔진의 데이터 테이블을 사용하면, 이를 엑셀 (CSV)이나 JSON 파일로 관리해서 엔진 안으로 임포트하고, 코드나 블루프린트에서 쉽게 불러 쓸 수 있습니다. 기획자나 디자이너도 엑셀에서 숫자만 바꾸면 되므로 매우 편리합니다.
우선, 데이터 테이블의 각 “행(Row)”을 C++ 구조체로 매핑해야 합니다. 언리얼 엔진은 FTableRowBase라는 기본 구조체를 제공하며, 이를 상속한 구조체를 만들면, 각 CSV (또는 JSON) 행을 FItemSpawnRow 구조체에서 정해준 형태로 받아올 수 있게 됩니다.
이러한 구조체는 클래스가 아니기 때문에, 부모 클래스를 선택할 수 있는 옵션에 나타나지 않습니다. 따라서 None을 선택해서 ItemSpawnRow C++ 파일을 만들어줍니다.

FTableRowBase
- 언리얼 엔진에서 “이 구조체는 데이터 테이블로 쓸 수 있다”라고 인식하게 해주는 베이스 구조체입니다.
TSoftClassPtr<AActor>
- 소프트 레퍼런스로, 클래스를 바로 로드하지 않고도 경로만 기억해둘 수 있습니다.
- 필요할 때 Get()을 통해 실제 UClass*를 얻어 인스턴스를 생성할 수 있습니다.

ItemSpawnRow.h

#pragma once

#include "CoreMinimal.h"
#include "Engine/DataTable.h" // FTableRowBase 정의가 들어있는 헤더
#include "ItemSpawnRow.generated.h"

USTRUCT(BlueprintType)
struct FItemSpawnRow : public FTableRowBase
{
	GENERATED_BODY()

public:
	// 아이템 이름
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
	FName ItemName;
	// 어떤 아이템 클래스를 스폰할지
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
	TSubclassOf<AActor> ItemClass;
	// 이 아이템의 스폰 확률
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
	float SpawnChance;
};

데이터 테이블 수정 하는 두 가지 방법 (언리얼 에디터에서 & CSV 파일로)

2️⃣언리얼 에디터에서 직접 데이터 테이블 수정하기

Content Browser 창에서 우클릭 → Miscellaneous → Data Table 선택

(Content Browser 에서 우클릭 -> Miscellaneous -> Data Table-> Pick Row Structure -> 위에서 만든 ItemSpawnRow 선택)

팝업창에서 Row Structure로 FItemSpawnRow를 선택하고 OK

새로 생성된 DataTable 에셋을 열면, 에디터 UI 상에서 아래처럼 Row 정보를 바로 편집 가능합니다.
- Add Row 버튼을 눌러 행을 추가하고, Row Name, Item Name, ItemClass, SpawnChance 등을 원하는 값으로 넣습니다.
- Row Name: Key 값으로 생각하시면 됩니다.고유 한 이름. !절대 중복될수 없습니다.(찾을 때 이 이름으로 찾습니다)
- Item Name: 일종의 참고 사항 같은 것. FName 형태

Iteam Class 의 경로 끝에 보면 .C 가 붙는데 참조를 하려면 이게 꼭 붙어 있어야 한다는 특징이 있습니다.

완성된 데이터 테이블의 모습:

하지만 이런 방식은 Excel처럼 대량의 데이터를 한 번에 편집하기는 불편할 수 있습니다.
상황에 따라 에디터 직접 편집 / CSV 임포트 모두 필요에 따라 병행할 수도 있습니다.

3️⃣CSV 파일 작성 및 임포트하기

엑셀을 열고 2열부터 Column 이름을 작성합니다.
1열은 “RowName”으로 인식됩니다. Key 값으로 사용할 값을 입력해줘야 합니다.
2열부터는 각 아이템 (데이터) 정보를 한 줄씩 기록합니다.
경로는 각 BP 클래스 우클릭 → Copy Reference 로 정확히 가져옵니다. 그리고 블루프린트의 경우 뒤에 "_C"가 붙어야 BP 클래스로 인식되니까 마지막에 반드시 붙여주세요.
- /Script/Engine.Blueprint'/Game/Blueprint/BP_BigCoinItem.BP_BigCoinItem'
- 그냥 복붙이후는 "_C" 가 안붙기 때문에 따로 꼭 붙여줘야 합니다.

Copy Reference는 언리얼 엔진 런타임에서 사용되는 “클래스/오브젝트” 경로입니다.
- 블루프린트/C++로 자산 로드 시 ConstructorHelpers::FClassFinder 등에서 활용.

CSV로 저장
- 언리얼 콘텐츠 폴더가 아니라 본인이 편한 로컬 위치에 파일명 ItemSpawnTable.csv 로 CSV UTF-8 (쉼표로 분리)로 저장합니다.

언리얼 에디터로 돌아와, Content Browser에서 Blueprints 폴더에서 우클릭 → Import to /Game/Blueprints 를 선택, 아래와 같이 옵션을 설정하고 Apply를 클릭해줍니다.
폴더 내에서 우클릭 후 Import to Current Folder 해도 괜찮습니다.

Coder 05 Manage Item and Data in an Unreal Engine Game | Unreal Engine 5.7 Documentation | Epic Developer Community

Learn to use Item Data Structs, Data Assets, and Data Tables to define items and store and organize item data for scalability in Unreal Engine.

dev.epicgames.com

스폰에 확률 적용하기

1️⃣ 데이터 테이블을 사용하여 스폰 로직 구현하기

SpawnVolume 클래스로 돌아와서, 확률 로직으로 “어떤 아이템을 스폰할지” 결정하는 코드로 다시 수정을 해봅시다.

SpawnRandomItem()
- “데이터 테이블에서 확률 계산으로 Row 하나 선택” + “스폰”을 분리해놓아 코드가 깔끔해집니다.
GetRandomItem()
- 테이블의 모든 Row를 가져와 확률합을 구하고, 확률에 따라 한 개를 뽑아 리턴합니다.
Algo::Accumulate
- 언리얼 엔진에서 추가한 C++ 템플릿 함수로, STL의 std::accumulate와 유사하게 작동합니다.
- 각 Row의 SpawnChance를 계속 더해 총 합을 구합니다.
- 이것을 이용해서 누적형태로 랜덤 뽑기를 실행합니다.

누적 확률 방식을 사용하는 이유는 컴퓨터가 연속된 난수(Random Number)를 단 한 번만 생성하여 여러 항목 중 하나를 가장 빠르고 정확하게 결정할 수 있기 때문입니다.

컴퓨터 친화적 계산: 컴퓨터는 0과 1 사이의 소수나 0~100 사이의 난수를 만드는 데 최적화되어 있습니다.
단 한 번의 난수 생성: 주사위를 여러 번 굴릴 필요 없이, 단 하나의 숫자로 당첨자를 바로 판별합니다.
유연한 확률 제어: 소수점 단위의 아주 미세한 확률(예: 0.001%)도 완벽하게 구현할 수 있습니다.

장점

빠른 속도 (성능 우수): 데이터를 정렬해 두면 이진 탐색(Binary Search) 알고리즘을 통해 수만 개의 아이템 중에서도 당첨 항목을 눈 깜짝할 사이에 찾습니다.
확률 수정의 용이성: 특정 아이템의 가중치만 바꾸면 전체 누적 합산만 다시 계산하면 되므로 기획 변경에 유연합니다.
정확성: 모든 확률의 총합이 100%가 되지 않더라도(예: 가중치 합이 450), 전체 가중치 합을 기준으로 난수를 만들면 비율에 맞춰 정확히 작동합니다.

단점

데이터 관리 비용: 아이템이 추가되거나 삭제될 때마다 누적 확률 배열을 매번 새로 계산(업데이트)해야 합니다.
직관성 부족: 코드를 처음 보는 개발자나 기획자에게는 단순 주사위 굴리기 방식보다 직관적으로 이해하기 어려울 수 있습니다.

이 로직을 이용해서 천장 시스템(Pity System 혹은 보정 확률) 사용자가 일정 횟수 이상 실패했을 때 최고 등급 아이템의 당첨 확률을 강제로 높이거나 확정 지급하는 안전장치를 구현하기도 합니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ItemSpawnRow.h"       // 우리가 정의한 구조체

#include "SpawnVolume.generated.h"

class UBoxComponent;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API ASpawnVolume : public AActor
{
	GENERATED_BODY()
	
public:	
	// Sets default values for this actor's properties
	ASpawnVolume();
	
	UFUNCTION(BlueprintCallable, Category = "Spawning")
	void SpawnRandomItem();
	
protected:
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Spawning")
    USceneComponent* Scene;
    // 스폰 영역을 담당할 박스 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Spawning")
    UBoxComponent* SpawningBox;
	
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Spawning")
	UDataTable* ItemDataTable;
	
	
	
	//
	FItemSpawnRow* GetRandomItem() const;
	
	// 특정 아이템 클래스를 스폰하는 함수
	UFUNCTION(BlueprintCallable, Category="Spawning")
	void SpawnItem(TSubclassOf<AActor> ItemClass);
	
	// 스폰 볼륨 내부에서 무작위 좌표를 얻어오는 함수
	UFUNCTION(BlueprintCallable, Category="Spawning")
	FVector GetRandomPointInVolume() const;	
	
	
};

#include "SpawnVolume.h"
#include "Components/BoxComponent.h"
#include "Engine/World.h"
#include "GameFramework/Actor.h"

ASpawnVolume::ASpawnVolume()
{
	PrimaryActorTick.bCanEverTick = false;

	// 박스 컴포넌트를 생성하고, 이 액터의 루트로 설정
	Scene = CreateDefaultSubobject<USceneComponent>(TEXT("Scene"));
	SetRootComponent(Scene);
    
	SpawningBox = CreateDefaultSubobject<UBoxComponent>(TEXT("SpawningBox"));
	SpawningBox->SetupAttachment(Scene);
}

void ASpawnVolume::SpawnRandomItem()
{
	if (FItemSpawnRow* SelectedRow = GetRandomItem())
	{
		if (UClass* ActualClass = SelectedRow->ItemClass.Get())
		{
			SpawnItem(ActualClass);
		}
	}
} 

FVector ASpawnVolume::GetRandomPointInVolume() const
{
	// 1) 박스 컴포넌트의 스케일된 Extent, 즉 x/y/z 방향으로 반지름(절반 길이)을 구함
	FVector BoxExtent = SpawningBox->GetScaledBoxExtent();
	// 2) 박스 중심 위치
	FVector BoxOrigin = SpawningBox->GetComponentLocation();

	// 3) 각 축별로 -Extent ~ +Extent 범위의 무작위 값 생성
	return BoxOrigin + FVector(
		FMath::FRandRange(-BoxExtent.X, BoxExtent.X),
		FMath::FRandRange(-BoxExtent.Y, BoxExtent.Y),
		FMath::FRandRange(-BoxExtent.Z, BoxExtent.Z)
	);
}


FItemSpawnRow* ASpawnVolume::GetRandomItem() const
{
	if (!ItemDataTable) 
		return nullptr;

	
	// 1) 모든 Row(행) 가져오기
	TArray<FItemSpawnRow*> AllRows;
	static const FString ContextString(TEXT("ItemSpawnContext")); // 디버깅 용도
	ItemDataTable->GetAllRows(ContextString, AllRows);

	if (AllRows.IsEmpty()) return nullptr; 

	// 2) 전체 확률 합 구하기
	float TotalChance = 0.0f; // 초기화
	for (const FItemSpawnRow* Row : AllRows) // AllRows 배열의 각 Row를 순회
	{
		if (Row) // Row가 유효한지 확인
		{
			TotalChance += Row->SpawnChance; // SpawnChance 값을 TotalChance에 더하기
		}
	}

	// 3) 0 ~ TotalChance 사이 랜덤 값
	const float RandValue = FMath::FRandRange(0.0f, TotalChance);
	float AccumulateChance = 0.0f; // 랜덤 값 보정
	//Algo::Accumulate( AllRows, AccumulateChance)
	
	// 4) 누적 확률로 아이템 선택
	for (FItemSpawnRow* Row : AllRows)
	{
		AccumulateChance += Row->SpawnChance;
		if (RandValue <= AccumulateChance)
		{
			return Row;
		}
	}

	return nullptr;
}

void ASpawnVolume::SpawnItem(TSubclassOf<AActor> ItemClass)
{
	if (!ItemClass) return;

	GetWorld()->SpawnActor<AActor>(
		ItemClass,
		GetRandomPointInVolume(),
		FRotator::ZeroRotator
	);
}

빌드 후, BP_SpawnVolume 로 돌아가서, 속성에서 Item Data Table에도 기존에 만들어둔 데이터테이블인 ItemSpawnTable 에셋을 할당해줍니다.

이벤트 그래프 SpawnRandomItem() 함수를 스크린샷과 같이 10번의 호출을 하도록 로직 노드를 생성합니다.

이후 플레이를 해보면 확률에 따라 5개의 아이템이 스폰되는 것을 확인할 수 있습니다.

2️⃣ 레벨마다 다른 확률 데이터 적용하기

원래 기획 취지에 의하면 레벨별로 다른 확률을 가져야 합니다. 이를 구현하는 방법은 여러 가지가 있습니다.

1.레벨별로 서로 다른 DataTable 에셋을 사용

CSV(또는 JSON)에 각각 다른 확률을 넣고, 레벨1 맵에서는 BP_SpawnVolume가 ItemSpawnTable_Level1을 바라보도록 설정.
레벨2 맵에서는 ItemSpawnTable_Level2 할당… 등등.
관리가 직관적이며 간단합니다.

2.단일 DataTable에 “레벨 구분” 컬럼 추가

예: CSV에 LevelIndex (또는 LevelName) 같은 컬럼을 하나 더 두고, 각각 어느 레벨에 해당하는지 적습니다.
코드를 수정하여, 현재 레벨이 1인지 2인지 확인 후 “필터링된 Row만” 확률 계산.
한 DataTable에서 모든 레벨 정보를 한 번에 관리할 수 있는 장점이 있으나, 코드가 약간 복잡해집니다.

번외 | GetWorld() 관련 찾아본 내용

- 액터 생성 (SpawnActor): 월드에 새로운 액터나 캐릭터를 동적으로 스폰할 때 사용합니다.코드를 사용할 때는 주의가 필요합니다.
  - GetWorld()->SpawnActor<AMyActor>(ActorClass, Location, Rotation);
- 타이머 매니저 (TimerManager): 일정 시간 뒤에 함수를 실행하거나 주기적으로 반복하는 타이머를 설정/해제합니다.코드를 사용할 때는 주의가 필요합니다.
  - GetWorld()->GetTimerManager().SetTimer(TimerHandle, this, &AMyClass::MyFunction, 2.0f, false);
- 게임 인스턴스 접근 (GetGameInstance): 씬 전환 시에도 유지되는 전역 데이터나 서브시스템을 가져올 때 사용합니다.코드를 사용할 때는 주의가 필요합니다.
  - UGameInstance* GameInst = GetWorld()->GetGameInstance();GetWorld()를 통해 게임 내 가상 공간의 인스턴스에 접근하고, 월드와 상호작용하는 다양한 관리자 및 시스템 함수를 사용할 수 있습니다. 주로 액터(Actor)나 컴포넌트(Component) 내부에서 사용됩니다.GetWorld()-> 뒤에 포인터 접근 연산자(->)를 붙여 아래와 같은 기능들을 주로 호출합니다.

주의사항

- nullptr 반환 가능성: 월드에 아직 배치되지 않은 순수 UObject나 일부 애니메이션 노티파이(NotifyState) 등에서는 GetWorld()가 유효하지 않아 nullptr을 반환할 수 있습니다. 호출 전 if (GetWorld() != nullptr) 검사를 하거나, 유효한 액터를 통해 간접 참조해야 합니다.
- 오브젝트에서 사용: 기본 UObject 클래스에서 GetWorld()를 사용하려면 클래스 기본 생성자 설정에서 bWantsInitializeOnBeginPlay를 활성화하거나 가상 함수를 오버라이딩해야 정상적으로 월드를 반환받을 수 있습니다.
언리얼 엔진의 전체적인 월드 관리 시스템에 대한 더 자세한 내용은 언리얼 엔진 UWorld API 문서를 참고할 수 있습니다.

주요 활용 기능

언리얼 엔진(UE)에서 GetWorld()->는 현재 게임 월드(UWorld) 객체에 접근하기 위해 호출하는 핵심 함수입니다.

충돌 이벤트로 획득되는 아이템 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

DevCol — Thu, 11 Jun 2026 01:29:41 +0900

충돌 이벤트로 획득되는 아이템 구현하기

이전 포스팅에서는 클래스 구조만 짜고 로직은 비여있던 상태.

이전 포스팅: [Unreal Engine/UE 기초] - 인터페이스 기반 아이템 클래스 설계하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

인터페이스 기반 아이템 클래스 설계하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

devcol.tistory.com

충돌 (Collision) 이벤트로 획득되는 아이템 구현하기

1️⃣ 충돌 (Collision) 이벤트 기반 아이템 획득 방식 이해하기

언리얼 엔진에서 아이템을 “플레이어가 가까이 다가가기만 해도 자동으로 획득”시키고 싶다면, 보통 콜리전 (충돌) 이벤트를 사용합니다. 충돌 영역을 설정해두면, 플레이어가 그 영역 안에 들어오거나 나갈 때 자동으로 이벤트를 발생시켜주기 때문에 별도의 함수 호출 없이도 간편하게 처리할 수 있습니다.

충돌 영역 (Collision Volume)
- 아이템 액터 주변에 SphereComponent나 BoxComponent 같은 충돌 컴포넌트를 붙여둡니다.
- 플레이어가 이 영역 안에 들어오면 Overlap 이벤트가 발생하고, 이를 감지해 아이템 획득 로직을 실행할 수 있습니다.
Overlap 이벤트 vs. Hit 이벤트
- Overlap 이벤트: 물리적으로 부딪히는 것 없이 액터들이 서로 “겹치기 시작”했을 때 발생합니다. 아이템 획득, 트리거 존 감지 같은 경우에 주로 사용합니다.
  - 겹쳤다가 빠져 나갔을 때 등등의 이벤트도 구현되어 있습니다.
- Hit 이벤트: 실제 물리 충돌이 일어날 때 발생합니다 (예: 탄환이 벽에 부딪히는 장면). 아이템 획득처럼 “겹침”만 감지하면 되는 경우에는 Overlap 이벤트가 더욱 적합합니다.
아이템 획득 처리
- 충돌 영역 안에 플레이어가 들어오면 (Overlap 시작 시점), 아이템이 즉시 사라지거나(DestroyItem()), 점수를 올리거나 체력을 회복하는 등 다양한 로직을 실행할 수 있습니다.
- 초중급 개발에서 많이 쓰이는 방식으로, 한 번 제대로 설정해두면 매우 편하게 사용할 수 있습니다.

2️⃣ItemInterface 인터페이스 함수 시그니처 수정

아이템들이 모두 가져야 할 최소한의 동작을 위한 인터페이스에 Overlap 이벤트 처리에 바인딩할 함수를 수정하도록 합니다.
OnItempOverlap과 OnItemEndOverlap 매개변수를 수정합니다.

ItemInterface.h

#pragma once

#include "CoreMinimal.h"
#include "UObject/Interface.h"
#include "ItemInterface.generated.h"

// This class does not need to be modified.
UINTERFACE(MinimalAPI)
class UItemInterface : public UInterface
{
	GENERATED_BODY()
};


class BC_CH3_ASSIGNMENT_5_API IItemInterface
{
	GENERATED_BODY()
	
public:
	// 구현할 아이템 종류 지뢰 , 힐링, 코인
	// 힐링, 코인: 즉시 발동형 | 오버랩
	// 지뢰: 5초뒤 발동 | 범위 내에 오버랩 
	
	
	// 플레이어가 이 아이템의 범위에 들어왔을 때 호출
	UFUNCTION()
	virtual void OnItemOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex,
			bool bFromSweep,
			const FHitResult& SweepResult) = 0;
	
	
	// 플레이어가 이 아이템의 범위를 벗어났을 때 호출
	UFUNCTION()
	virtual void OnItemEndOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex) = 0;
	
	
	// 아이템이 사용되었을 때 호출
	virtual void ActivateItem(AActor* Activator) = 0;
	// 이 아이템의 유형(타입)을 반환 (예: "Coin", "Mine" 등)
	virtual FName GetItemType() const = 0;
};

UPrimitiveComponent* OverlappedComp: // 자기 자신 (원형) // 현재: 아이템
AActor* OtherActor: // 부딪힌 Actor // 현재: 플레이어
UPrimitiveComponent* OtherComp: // 부딪힌 Actor에 붙어있던 1차적으로 충돌을 일으킨 원인인 컴포넌트

UFUNCTION(): 의 경우 Interface 에 만 선언해두면 이후에 받아서 구현하는 클래스는 생략해도됩니다.

3️⃣기본 아이템 클래스(BaseItem)에 충돌 컴포넌트와 메시 컴포넌트 추가

BaseItem 클래스는 모든 아이템(코인, 포션, 무기 등)에 공통으로 필요한 기능을 담는 부모 클래스입니다. 여기에는 다음과 같은 컴포넌트와 함수를 포함합니다.
- SceneComponent* Scene;
  - 액터(아이템)의 루트 컴포넌트로 사용합니다.
- USphereComponent* Collision;
  - 플레이어가 범위 안에 들어오면 Overlap 이벤트를 발생시킬 충돌 컴포넌트입니다.
- UStaticMeshComponent* StaticMesh;
  - 아이템이 월드에 표시될 때, 시각적인 모습을 담당합니다.

CollisionComponent->InitSphereRadius(100.0f);
- 테스트용으로 100.0f를 사용했습니다. 실사용 시 적절한 범위로 조정하세요.
CollisionComponent->SetCollisionProfileName(TEXT("OverlapAllDynamic"));
- SphereComponent가 다른 액터와 겹칠 때만 Overlap 이벤트를 발생시키도록 설정합니다. 물리적인 충돌(Hit)은 발생하지 않습니다.
OnComponentBeginOverlap.AddDynamic(this, &ABaseItem::OnItemOverlap);
- 플레이어가 범위 안에 들어올 때 자동으로 OnItemOverlap을 호출합니다.

원래는 Collision->OnComponentBeginOverlap() ; 인데 문제는 이렇게 할경우 매게변수가 매우 길어서 불편하기 때문에 AddDynamic를 사용.

Delegate 에 Binding 하는 함수
관련 UE 공식문서: https://dev.epicgames.com/documentation/unreal-engine/dynamic-delegates-in-unreal-engine?lang=ko

Dynamic Delegates in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Delegates that can be serialized and support reflection.

dev.epicgames.com

Event Binding의 장점

런타임 상에서 이벤트 바인딩이 이뤄지기 때문에 그런 동적으로 연결해서 여러 상황들에 대비가 가능합니다.

BaseItem.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ItemInterface.h"  // 만들어둔 인터페이스 헤더 포함

#include "BaseItem.generated.h"

class USphereComponent;

UCLASS()
class BC_CH3_ASSIGNMENT_5_API ABaseItem : public AActor, public IItemInterface
{
	GENERATED_BODY()
	
public:	
	// Sets default values for this actor's properties
	ABaseItem();

protected:
	// 아이템 유형(타입)을 편집 가능하게 지정
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
	FName ItemType;
	
	// 루트 컴포넌트 (씬)
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	USceneComponent* Scene;
	// 충돌 컴포넌트 (플레이어 진입 범위 감지용)
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	USphereComponent* Collision;
	// 아이템 시각 표현용 스태틱 메시
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Component")
	UStaticMeshComponent* StaticMesh;
	
	virtual void OnItemOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex,
			bool bFromSweep,
			const FHitResult& SweepResult) override;
	virtual void OnItemEndOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor,
			UPrimitiveComponent* OtherComp,
			int32 OtherBodyIndex) override;
	
	virtual void ActivateItem(AActor* Activator) override;
	virtual FName GetItemType() const override;
	
	// 아이템을 제거하는 공통 함수 (추가 이펙트나 로직을 넣을 수 있음)
	virtual void DestroyItem();

};

BaseItem.cpp

#include "BaseItem.h"
#include "Components/SphereComponent.h"

ABaseItem::ABaseItem()
{
	PrimaryActorTick.bCanEverTick = false;
    
	// 루트 컴포넌트 생성 및 설정
	Scene = CreateDefaultSubobject<USceneComponent>(TEXT("Scene"));
	SetRootComponent(Scene);

	// 충돌 컴포넌트 생성 및 설정
	Collision = CreateDefaultSubobject<USphereComponent>(TEXT("Collision"));
	// 겹침만 감지하는 프로파일 설정
	Collision->SetCollisionProfileName(TEXT("OverlapAllDynamic"));
	// 루트 컴포넌트로 설정
	Collision->SetupAttachment(Scene);
    
	// 스태틱 메시 컴포넌트 생성 및 설정
	StaticMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("StaticMesh"));
	StaticMesh->SetupAttachment(Collision);
	// 메시가 불필요하게 충돌을 막지 않도록 하기 위해, 별도로 NoCollision 등으로 설정할 수 있음.

	// Overlap 이벤트 바인딩
	Collision->OnComponentBeginOverlap.AddDynamic(this, &ABaseItem::OnItemOverlap);
	Collision->OnComponentEndOverlap.AddDynamic(this, &ABaseItem::OnItemEndOverlap);
}

void ABaseItem::OnItemOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor, 
			UPrimitiveComponent* OtherComp, 
			int32 OtherBodyIndex, 
			bool bFromSweep, 
			const FHitResult& SweepResult)
{
	// OtherActor가 플레이어인지 확인 ("Player" 태그 활용)
	if (OtherActor && OtherActor->ActorHasTag("Player"))
	{
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Overlap!!!")));
		// 아이템 사용 (획득) 로직 호출
		ActivateItem(OtherActor);
	}
}

void ABaseItem::OnItemEndOverlap(
			UPrimitiveComponent* OverlappedComp, 
			AActor* OtherActor, 
			UPrimitiveComponent* OtherComp, 
			int32 OtherBodyIndex)
{
}

void ABaseItem::ActivateItem(AActor* Activator)
{
	GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Overlap!!")));
}

FName ABaseItem::GetItemType() const
{
	return ItemType;
}

void ABaseItem::DestroyItem()
{
	Destroy();
}

아이템 Blueprint 생성 및 콜리전/메시 설정하기

1️⃣ 아이템 Blueprint 생성 및 Static Mesh 설정

C++ 클래스 기반 블루프린트 생성
- C++로 작성한 클래스들을 (BigCoinItem, SmallCoinItem, MineItem, HealingItem 4개만 해당) 언리얼 에디터에서 우클릭 → Create Blueprint Class based on…을 선택해 Blueprint를 생성합니다.
- 각 아이템들 블루프린트로 상속해서 만들기: BP_BigCoinItem, BP_SmallCoinItem, BP_MineItem, BP_HealingItem

Static Mesh 및 머티리얼 설정
- Components 패널에서 StaticMesh (UStaticMeshComponent)를 선택하세요.
- Details 패널에서 Static Mesh를 원하는 에셋으로 설정합니다.
- 메시를 선택한 상태에서 Details 패널을 보면, Material 항목이 있습니다. 원하는 머티리얼을 적용할 수 있습니다.

2️⃣ 콜리전 범위 (Sphere Radius) 조정

Components 패널에서 SphereComponent를 선택하세요. 기본적으로 ABaseItem 클래스 내에서 충돌 컴포넌트가 생성되어 있을 것이며, 이는 BP 상속 시 그대로 노출됩니다.
Details 패널에서 크기 조정
- Sphere Radius (또는 Box의 경우 Box Extent) 값을 변경하면 충돌 범위를 직관적으로 조절할 수 있습니다.
- 범위를 키우거나 줄일 때, 바로 뷰포트 상에서 확인 가능하므로 적절한 크기로 맞추세요.

3️⃣ 아이템 액터의 콜리전 프리셋 설정

콜리전 컴포넌트 설정 확인
- 생성한 BP (예: BP_BigCoin, BP_HealingItem 등)를 더블클릭하여 열고, Components 패널에서 SphereComponent(또는 BoxComponent)를 선택합니다.
- Details 패널에서 Collision 섹션을 찾습니다.
- Collision Presets가 어떤 값으로 설정되어 있는지 확인합니다. 부모 클래스(ABaseItem)에서 OverlapAllDynamic로 설정해두었습니다.
콜리전 프리셋 (Collision Preset)
- 언리얼 엔진은 여러 가지 콜리전 프리셋을 제공합니다. 이 프리셋을 통해 어떤 액터 (또는 채널)와 충돌을 Block할지, Overlap할지, Ignore할지를 손쉽게 설정할 수 있습니다.
- 주요 프리셋 옵션
  1. NoCollision
    - 충돌을 전혀 감지하지 않으므로, Overlap 또는 Hit 이벤트가 발생하지 않습니다.
    - 사용 예시: 단순 배경 오브젝트(하늘, 장식용 액터 등).
  2. BlockAll
    - 모든 객체와 충돌하여 막게 됩니다. 물리적으로 충돌하지만, Overlap 이벤트는 발생하지 않습니다.
    - 사용 예시: 벽, 바닥 같은 고정된 장치.
  3. OverlapAll
    - 모든 객체와 Overlap 이벤트를 발생시킵니다.
    - 사용 예시: 트리거 존, 감지 센서, 투명한 오브젝트.
  4. BlockAllDynamic
    - 움직이는 (Dynamic) 객체만 충돌을 막습니다. 고정된 객체와는 충돌하지 않습니다.
    - 사용 예시: 움직이는 플레이어나 물리 오브젝트와 상호작용하는 문, 벽. 고정된 환경 요소와는 무관하게 작동.
  5. OverlapAllDynamic
    - 움직이는 (Dynamic) 객체와 Overlap 이벤트를 발생시킵니다.
    - 사용 예시: 플레이어가 근처에 있는지 확인하는 아이템, 센서. Overlap 이벤트가 필요하지만, 물리 충돌이 필요 없는 경우.
  6. Pawn
    - 플레이어나 AI처럼 Pawn 타입 객체를 대상으로 충돌을 감지하거나 막습니다.
    - 사용 예시: 플레이어 전용 문, AI 전용 센서.
  7. Custom
    - 각 채널에 대해 충돌 응답(Overlap, Block, Ignore)을 객체별로 세부적으로 설정할 수 있습니다.
    - 보통은: 물리 반응 여부 (Collision Enabled)
      - 충돌이 켜져 있어도 물리적 반응이 없는 “Query Only”인지, 물리적인 반응까지 하는 “Query and Physics”인지 구분할 수 있습니다.
    - NoCollision: 충돌 비활성화
    - Query Only: Overlap, Hit 등 충돌 이벤트는 감지하지만, 물리적으로 튕기거나 밀리는 반응은 없음.
    - Physics Only: 물리 반응만 일어나고, 이벤트 (Overlap/Hit)는 발생하지 않음.
    - Query and Physics: 충돌 이벤트 + 물리 반응 모두 활성화

Collision Response Reference in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

Reference guide to the Collision Presets section in Unreal Engine.

dev.epicgames.com

4️⃣ 캐릭터 태그 부여 및 콜리전 프리셋 설정

플레이어 클래스에 “Player” 태그 부여
- Details 패널에서 플레이어 캐릭터를 선택하고, Actor 섹션의 Tags 항목에 "Player"를 추가합니다.
- C++ 코드에서 OtherActor->ActorHasTag("Player")를 통해 플레이어인지 간단히 판별할 수 있습니다.

플레이어 클래스 콜리전 채널 확인
- BP_SpartaCharacter의 Capsule Component를 선택하고, Details 패널의 Collision 섹션을 살펴보세요.
- Collision Presets가 Pawn으로 설정되어 있으며, 이는 “OverlapAllDynamic”와 대체로 호환되어 Overlap 이벤트를 발생시킵니다.
- 만약 Overlap 이벤트가 작동하지 않는다면, Project Settings > Collision 탭에서 Pawn 채널과 OverlapAllDynamic 채널의 상호작용을 재확인하거나 수정해야 합니다.

아이템 클래스 충돌 처리 구현하기

이제 아이템 클래스에서 실제로 Overlap 이벤트가 발생했을 때 어떤 로직을 수행할지 살펴봅시다. 예를 들어 코인 아이템이라면 점수를 주고, 힐링 아이템이라면 체력을 회복시키며, 지뢰 아이템이라면 폭발 타이머를 돌려서 데미지를 주는 등의 동작을 구현할 수 있습니다.

1️⃣ CoinItem 코인 아이템 공통 부모 클래스 충돌 처리

CoinItem은 “코인 아이템이 가져야 할 공통 기능(점수)”을 정의하고, 실제 점수 획득은 ActivateItem 함수에서 처리합니다.

#pragma once

#include "CoreMinimal.h"
#include "BaseItem.h"
#include "CoinItem.generated.h"

UCLASS()
class BC_CH3_ASSIGNMENT_5_API ACoinItem : public ABaseItem
{
	GENERATED_BODY()
	
public:
	ACoinItem();
	
protected:	
	// 코인 획득 시 얻을 점수 (자식 클래스에서 상속받아 값만 바꿔줄 예정)
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
	int32 PointValue;
	
	
	// 부모 클래스에서 상속받은 ActivateItem 함수를 오버라이드
	virtual void ActivateItem(AActor* Activator) override;
};

#include "CoinItem.h"

ACoinItem::ACoinItem()
{
	// 점수 기본값을 0으로 설정
	PointValue = 0;
	ItemType = "DefaultCoin";
}

void ACoinItem::ActivateItem(AActor* Activator)
{
	// 플레이어 태그 확인
	if (Activator && Activator->ActorHasTag("Player"))
	{
		// 점수 획득 디버그 메시지
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Player gained %d points!"), PointValue));
        
		// 부모 클래스 (BaseItem)에 정의된 아이템 파괴 함수 호출
		DestroyItem();
	}
}

2️⃣ BigCoinItem 빅 코인 아이템 충돌 처리

“빅 코인” 클래스는 CoinItem을 상속받아 점수만 50으로 설정해주면 됩니다.

#include "BigCoinItem.h"

ABigCoinItem::ABigCoinItem()
{
		// 상위 CoinItem의 PointValue를 50으로 덮어쓰기
    PointValue = 50;
    ItemType = "BigCoin";
}

void ABigCoinItem::ActivateItem(AActor* Activator)
{
    // 부모의 기본 점수 획득 로직 사용
    Super::ActivateItem(Activator);

    // 빅 코인만의 추가 동작(이펙트, 사운드 재생 등)을 여기서 추가할 수 있음
}

3️⃣ SmallCoinItem 스몰 코인 아이템 충돌 처리

“스몰 코인” 클래스도 CoinItem을 상속받아 점수를 10으로 지정합니다.

#include "SmallCoinItem.h"

ASmallCoinItem::ASmallCoinItem()
{
    PointValue = 10;
    ItemType = "SmallCoin";
}

void ASmallCoinItem::ActivateItem(AActor* Activator)
{
    // 부모의 기본 점수 획득 로직 사용
    Super::ActivateItem(Activator);

    // 스몰 코인만의 별도 동작은 여기에 추가
}

4️⃣ HealingItem 힐링 아이템 충돌 처리

#pragma once

#include "CoreMinimal.h"
#include "BaseItem.h"
#include "HealingItem.generated.h"

UCLASS()
class SPARTAPROJECT_API AHealingItem : public ABaseItem
{
    GENERATED_BODY()

public
    AHealingItem();

protected:
		// 회복량
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Healing")
    int32 HealAmount;

    virtual void ActivateItem(AActor* Activator) override;
};

#include "HealingItem.h"

AHealingItem::AHealingItem()
{
	HealAmount = 20.0f;
	ItemType = "Healing";
}

void AHealingItem::ActivateItem(AActor* Activator)
{
	if (Activator && Activator->ActorHasTag("Player"))
	{
		// 회복 디버그 메시지
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, 
			//FString::Printf(TEXT("Player Gained %d HP!"), HealAmount));
			FString::Printf(TEXT("Player Gained %i HP!"), HealAmount));
        
		DestroyItem();
	}
}

이후 Activator가 캐릭터라는 전제하에, 플레이어의 체력 변수 혹은 함수를 호출해 직접 체력 회복을 처리하는 구현을 해야합니다 (예: PlayerCharacter->Heal(HealAmount)).

5️⃣ MineItem (지뢰 아이템) 충돌 처리

이번에는 플레이어가 지뢰 범위에 들어오면 타이머를 시작하고, 일정 시간이 지난 후 폭발 범위 내 액터에게 데미지를 주는 지뢰 아이템입니다.
1. 플레이어가 지뢰 발동 범위에 들어가면 지뢰가 활성화되고 타이머가 시작됩니다.
2. 발동 후 5초가 지나면 폭발하며, 폭발 범위 내에 있는 액터를 확인합니다.
3. 폭발 범위 내에 있는 액터 중 발동 범위에 남아 있던 액터에게만 데미지를 입힙니다.
4. 지뢰는 폭발 후 사라집니다.

#pragma once

#include "CoreMinimal.h"
#include "BaseItem.h"
#include "MineItem.generated.h"


UCLASS()
class BC_CH3_ASSIGNMENT_5_API AMineItem : public ABaseItem
{
	GENERATED_BODY()
	
public:
	AMineItem();
	
protected:
	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Item|Component")
	USphereComponent* ExplosionCollision;
	
	// 폭발까지 걸리는 시간
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Mine")
	float ExplosionDelay;
	
	// 폭발 범위
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Mine")
	float ExplosionRadius;

	// 폭발 데미지
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Mine")
	int ExplosionDamage;
	
	// 지뢰 발동 여부
	FTimerHandle ExplosionTimerHandle;

	virtual void ActivateItem(AActor* Activator) override;
	
	void Explode();
};

bIsActivated: 이미 지뢰가 발동되었는지 여부를 체크하기 위한 불리언 변수입니다.
ActivateItem: 발동 이후 타이머를 설정하고, 폭발 함수를 스케줄링합니다.
Explode: 타이머가 만료되었을 때 실제 폭발 처리를 담당합니다.

#include "MineItem.h"
#include "Components/SphereComponent.h"

AMineItem::AMineItem()
{
	ExplosionDelay = 5.0f;
	ExplosionRadius = 300.0f;
	ExplosionDamage = 30.0f;
	ItemType = "Mine";
    
	ExplosionCollision = CreateDefaultSubobject<USphereComponent>(TEXT("ExplosionCollision"));
	ExplosionCollision->InitSphereRadius(ExplosionRadius);
	ExplosionCollision->SetCollisionProfileName(TEXT("OverlapAllDynamic"));
	ExplosionCollision->SetupAttachment(Scene);
}

void AMineItem::ActivateItem(AActor* Activator)
{
	// 5초 후 폭발 실행
	GetWorld()->GetTimerManager().SetTimer(ExplosionTimerHandle, this, &AMineItem::Explode, ExplosionDelay);
}

void AMineItem::Explode()
{
	TArray<AActor*> OverlappingActors;
	ExplosionCollision->GetOverlappingActors(OverlappingActors);

	for (AActor* Actor : OverlappingActors)
	{
		if (Actor && Actor->ActorHasTag("Player"))
		{
			GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("Player damaged %d by MineItem"), ExplosionDamage));
		}
	}

	// 지뢰 제거
	DestroyItem();
}

ActivateItem
- GetWorld()->GetTimerManager().SetTimer를 사용해 5초 후 Explode()가 자동 실행되도록 지연 호출 (Delayed Call)합니다.
Explode()
- 폭발이 일어날 때 주변 액터를 검사해, 지뢰 범위(ExplosionRadius) 안에 있고 지뢰 콜리전 컴포넌트와 여전히 Overlap 상태인 플레이어에게 데미지를 주는 예시입니다.
- 폭발 처리 후 DestroyItem()을 호출해 지뢰 아이템 자체를 제거합니다.

아이템 배치 및 충돌 체크하기

1️⃣ 콜리전 비주얼 디버깅

언리얼 에디터에서 Alt + C (기본 단축키)로 콜리전 디버그 모드를 켜면, Capsule Component뿐 아니라 Sphere, Box 같은 다른 콜리전 영역도 시각적으로 확인할 수 있습니다.
콜리전이 비정상적으로 설정되어 있을 경우, 이 기능을 통해 빠르게 확인해 보세요.

UE Collistion 관련 더 괜찮은 방식

현재는 ActorHasTag로 되어있어서, 중간에 Tag 변경, 오타, BP 에 잘못입력 등 실수하거나 확장성에 있어서 안좋기 때문에 추후에는 아래의 방식이 더 선호됩니다.


void ABaseItem::OnItemOverlap(
			UPrimitiveComponent* OverlappedComp,
			AActor* OtherActor, 
			UPrimitiveComponent* OtherComp, 
			int32 OtherBodyIndex, 
			bool bFromSweep, 
			const FHitResult& SweepResult)
{
	
	/*
	추가 팁: 인터페이스(Interface) 활용하기만약 플레이어뿐만 아니라 '데미지를 입을 수 있는 모든 대상'을 판별하고 싶다면, 
	Cast 대신 언리얼 인터페이스(UInterface)를 사용해 OtherActor->Implements<UMyDamageInterface>() 형태로 판별하는 것이 아키텍처 관점에서 훨씬 깔끔합니다.
	
	// 싱글 플레이어 게임이거나 0번 로컬 플레이어를 판별할 때 가장 간단하고 직관적인 방법입니다. 충돌한 액터가 현재 월드의 플레이어 폰과 같은지 메모리 주소를 직접 비교합니다.
	// 단점: 멀티플레이어 환경(다른 클라이언트의 플레이어 캐릭터)에서는 작동하지 않을 수 있습니다.
	if (OtherActor && OtherActor == GetWorld()->GetFirstPlayerController()->GetPawn())
	{		
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Blue, FString::Printf(TEXT("플레이어가 충돌했습니다!!!")));
	}  
	
	// 멀티플레이어 환경에서 적 플레이어, 아군 플레이어 구분 없이 '유저가 잡고 있는 캐릭터'를 모두 판별해 냅니다. 
	// AI 캐릭터(IsBotControlled)는 자동으로 걸러집니다.
	// #include "GameFramework/Pawn.h" // 다른 곳에서 선언된거랑 가능한한 여기서도 선언해두자
	if (OtherActor)
	{
		// 우선 APawn으로 캐스팅 (모든 캐릭터는 폰의 일종입니다)
		APawn* TouchedPawn = Cast<APawn>(OtherActor);
		
		// 폰이 맞고, 현재 플레이어 컨트롤러가 빙의(Possess)한 상태인지 확인
		if (TouchedPawn && TouchedPawn->IsPlayerControlled())
		{
			GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Red, FString::Printf(TEXT("플레이어가 조종 중인 액터입니다!!!")));
		}
	}	
	
	// 플레이어와 AI를 동시에 분기 처리하기
	// 하나의 충돌 함수 안에서 플레이어와 AI를 나누어 각각 다른 로직
	// (예: 플레이어면 UI 연출, AI면 데미지만 처리)을 실행하고 싶다면 다음과 같이 작성합니다.
	
	if (OtherActor)
	{
		APawn* TouchedPawn = Cast<APawn>(OtherActor);
			if (TouchedPawn)
			{
				if (TouchedPawn->IsPlayerControlled())
				{
					// 실제 플레이어 전용 로직
					UE_LOG(LogTemp, Log, TEXT("플레이어 충돌"));
				}
				else if (TouchedPawn->IsBotControlled())
				{
					//  AI 봇 전용 로직
					UE_LOG(LogTemp, Log, TEXT("AI 캐릭터 충돌"));
				}
			}
	}

	 */
	
	
	// OtherActor가 플레이어인지 확인 ("Player" 태그 활용)
	if (OtherActor && OtherActor->ActorHasTag("Player"))
	{
		GEngine->AddOnScreenDebugMessage(-1, 2.0f, FColor::Green, FString::Printf(TEXT("Overlap!!!")));
		// 아이템 사용 (획득) 로직 호출
		ActivateItem(OtherActor);
	}
}

DevCol (Development Collaboration)

파티클과 사운드로 게임 효과 연출하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

파티클과 사운드로 게임 효과 연출하기

파티클 시각 효과 추가하기

1️⃣ 파티클 시스템 (Particla System) 기본 개념 이해하기

2️⃣ 아이템 획득에 파티클 적용하기

그럼 언제 사운드를 직접 관리하나요?

정리

Item 관련 C++ 클래스 코드들

Debugging

문제: 게임 완성 후 테스팅 플레이 해봤는데 갑자기 게임이 크래쉬 해버렸다.

해결 방법: 많은 Null Check

느낀 점: 조심해서 코드를 짜자!

완성된 모습

추천

UI 애니메이션 효과 및 3D 위젯 UI 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

UI 애니메이션 효과 및 3D 위젯 UI 구현하기

UI 애니메이션 효과 디자인하기

1️⃣ UMG와 Animation에 대해 이해하기

2️⃣ Text 위젯에 애니메이션 적용하기

3️⃣ 애니메이션을 Blueprint 재생 함수로 묶어두기

게임 오버 UI 애니메이션 효과 추가하기

WidgetComponent로 캐릭터 체력 표시하기

1️⃣ WidgetComponent 개념 이해하기

2️⃣ Widget Blueprint 준비하기

3️⃣ Character 클래스에 WidgetComponent 추가하기

4️⃣ Character 클래스에서 WidgetComponent 위치 설정

5️⃣ 캐릭터 사망하였을 시 처리 로직 추가

0

Conclustion

추천

[페이지] Unreal Engine | 언리얼 엔진

게임 흐름에 맞춘 메뉴 UI 구현하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

게임 흐름에 맞춘 메뉴 UI 구현하기

게임 메뉴 UI 디자인하기

1️⃣ 메뉴 위젯 생성하고 버튼 추가하기

2️⃣ 메뉴 레벨 생성하고 설정하기

게임 흐름 내에 메뉴 UI 배치하기

1️⃣ PlayerController에 기본 위젯 오픈 함수 구현

2️⃣ GameState에서 게임 흐름에 따라 UI 호출

3️⃣ Start 버튼 클릭 이벤트에 함수 바인딩

추천

[페이지] Unreal Engine | 언리얼 엔진

UI 위젯 설계와 실시간 데이터 연동하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

UI 위젯 설계와 실시간 데이터 연동하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

UMG (User Widget) 위젯 기초 디자인 이해하기

1️⃣ HUD (Heads-Up Display)란?

2️⃣ 위젯 블루프린트 (Widget Blueprint)란?

3️⃣ UI 요소 (UI Elements)란?

4️⃣ 점수, 시간, 레벨 표시를 위한 UI Widget 디자인하기

HUD Widget을 생성해 화면에 표시하기

1️⃣ PlayerController에서 HUD 생성 로직 추가하기

HUD 위젯과 GameState 데이터 연동하기

1️⃣ GameState에서 점수 데이터 바인딩하기

2️⃣ SetText 방식으로 위젯 갱신하기

추천

[페이지] Unreal Engine | 언리얼 엔진

[TA] TA - Technical Artist (테크니컬 아티스트)란? | [언리얼 엔진 C++ (Unreal Engine C++)]

TA - Technical Artist 란?

TA-Technical Artist | 테크니컬 아티스트

클라이언트 개발자에게 TA 기초가 필요한 이유

소통에 원활한 도움을 줍니다

게임 화면을 구성하는 기본 요소들

Mesh

Texture

Material

Lighting

Animation

VFX (Visual Effects, 시각 특수 효과)

과제 (게임 분석): 게임 액션 하나를 선택하고 리소스 연결 구조 분석하기

추천

[페이지] Unreal Engine | 언리얼 엔진

TA | 아이템 시스템과 게임 흐름 로직 구현하기 | 코드 카타 (Code Kata): 둘만의 암호 | TIL 35th | 캠프 34일 차 | 06/11/2026 (Thur)

TA | 아이템 시스템과 게임 흐름 로직 구현하기 | 코드 카타 (Code Kata): 둘만의 암호

TA

아이템 시스템과 게임 흐름 로직 구현하기

코드 카타 (Code Kata) : 둘만의 암호

게임 루프 설계를 통한 게임 흐름 제어하기 | [언리얼 엔진 C++ (Unreal Engine C++)]

게임 루프 설계를 통한 게임 흐름 제어하기

GameState를 이용한 게임 루프 구현하기