hyunjunstar 님의 블로그

Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 최종

hyunjunstar — Thu, 28 May 2026 23:03:02 +0900

https://hyunjunstar.tistory.com/101

위 링크에서는 적 AI의 TargetActor 갱신 문제와 공격 데미지 타이밍 문제를 수정했다.

TargetActor가 한 번만 설정되던 문제는 SetTimer()를 반복 실행하도록 변경하여 해결했고,
BTTask_AttackTarget에서 ApplyDamage()를 즉시 호출하던 구조는 Anim Notify 시점에 데미지를 적용하는 방식으로 수정했다.

또한 Montage, Anim Notify, Anim Graph를 활용해 공격, 사망, 이동 애니메이션이 더 자연스럽게 연결되도록 개선했다.

이번 글에서는 최종적으로 완성된 적 AI의 전체 흐름과 코드를 정리하려고 한다.

적 AI 전체 흐름

1. 전체 통합 구조

적 AI는 EnemySpawner에서 생성된 뒤 EnemyCharacter, EnemyAIController, Blackboard, Behavior Tree를 거쳐 추적과 공격을 수행합니다.
실제 데미지는 공격 Task에서 바로 적용하지 않고, 공격 Montage의 Anim Notify 시점에 ApplyAttackDamage()를 호출해 처리합니다.

2. 스폰 흐름

EnemySpawner는 게임 시작 시 NavMesh 위의 랜덤 위치를 찾아 적을 생성합니다.
스폰 위치는 SpawnRadius 안에서 탐색하며, 충돌이 발생하면 가능한 위치로 조정하거나 스폰을 건너뛰도록 처리했습니다.

3. EnemyCharacter 초기 설정

EnemyCharacter는 HP, 방어력, 공격력, 탐지 범위, 공격 범위 등 적의 기본 전투 데이터를 관리합니다.
또한 Behavior Tree 참조, RVO 회피, 이동 방향 회전, 공격/사망 애니메이션 이벤트를 담당합니다.

4. 플레이어 탐지와 Blackboard 갱신

EnemyAIController는 적을 Possess한 뒤 Behavior Tree를 실행하고, 0.2초마다 플레이어를 탐지합니다.
플레이어가 DetectionRange 안에 있으면 Blackboard의 TargetActor에 저장하고, 범위 밖이면 TargetActor를 제거합니다.

5. Behavior Tree 판단 구조

Behavior Tree는 Blackboard의 TargetActor를 기준으로 현재 행동을 결정합니다.
TargetActor가 있고 공격 범위 안이면 공격 Sequence를 실행하고, 공격 범위 밖이면 Move To로 플레이어를 추적합니다.
TargetActor가 없으면 짧게 대기합니다.

6. 공격 범위 검사

BTDecorator_IsInAttackRange는 TargetActor와 적 사이의 거리를 계산해 공격 가능 여부를 판단합니다.
공격 범위 안이면 공격 Task가 실행되고, 범위 밖이면 추적 로직으로 넘어갑니다.

7. 공격 Task 실행

BTTask_AttackTarget은 공격이 가능한 상태인지 확인한 뒤, 적의 이동을 멈추고 플레이어 방향으로 회전시킵니다.
이후 PlayAttackAnimation()을 호출해 공격 Montage를 재생하고, MarkAttack()으로 공격 쿨타임을 기록합니다.

8. Montage와 Anim Notify

BP_EnemyCharacter에서는 C++에서 호출한 PlayAttackAnimation 이벤트를 받아 공격 Montage를 재생합니다.
공격 Montage 안에는 AttackHit Notify가 배치되어 있으며, 실제 타격 프레임에 데미지 함수가 호출되도록 연결했습니다.

9. Animation Blueprint 처리

ABP_ZombieEnemy는 적의 속도를 계산해 Idle / Walk / Run 애니메이션을 전환합니다.
또한 DefaultSlot을 통해 이동 애니메이션 위에 공격 및 사망 Montage가 재생될 수 있도록 구성했습니다.

10. 에디터 에셋 연결

최종적으로 BP_EnemyCharacter, ABP_ZombieEnemy, Blend Space, Attack Montage, Death Montage를 연결해 실제 게임에서 AI 캐릭터가 자연스럽게 움직이고 공격하도록 구성했습니다.

핵심 코드

1. EnemyAIController - 0.2초마다 TargetActor 갱신

// EnemyAIController.cpp

// 플레이어 감지 상태를 주기적으로 갱신
GetWorldTimerManager().SetTimer(
    FindPlayerTimerHandle,
    this,
    &AEnemyAIController::SetTargetPlayer,
    0.2f,
    true
);

2. EnemyAIController - 감지 범위에 따라 TargetActor 설정/제거

// EnemyAIController.cpp

// 적과 플레이어 사이의 거리를 계산
const float DistanceToPlayer = FVector::Dist2D(
    ControlledEnemy->GetActorLocation(),
    TargetPlayer->GetActorLocation()
);

// 감지 범위 안이면 플레이어를 TargetActor로 등록하고, 벗어나면 제거
if (DistanceToPlayer <= ControlledEnemy->DetectionRange)
{
    BB->SetValueAsObject(TEXT("TargetActor"), TargetPlayer);
}
else
{
    BB->ClearValue(TEXT("TargetActor"));
}

3. BTDecorator_IsInAttackRange - 공격 범위 판단

// BTDecorator_IsInAttackRange.cpp

// 적과 타겟 사이의 거리를 계산
const float Distance = FVector::Dist2D(
    Enemy->GetActorLocation(),
    TargetActor->GetActorLocation()
);

// 공격 범위 안이면 true, 아니면 false
return Distance <= Enemy->AttackRange;

4. BTTask_AttackTarget - 이동 정지, 회전, 공격 몽타주 실행

// BTTask_AttackTarget.cpp

// 공격 시작 전에 이동과 AI Focus를 정리
AIController->StopMovement();
AIController->ClearFocus(EAIFocusPriority::Gameplay);

// 이전 이동 입력이 남아 공격 방향을 방해하지 않도록 즉시 정지
Enemy->GetCharacterMovement()->StopMovementImmediately();

// 플레이어 방향으로 몸 돌리기
FVector Direction = TargetActor->GetActorLocation() - Enemy->GetActorLocation();
Direction.Z = 0.f;

if (!Direction.IsNearlyZero())
{
    // Z축을 제외한 방향으로 회전하여 적이 플레이어를 바라보게 함
    FRotator LookRotation = Direction.Rotation();

    Enemy->SetActorRotation(LookRotation);
    AIController->SetControlRotation(LookRotation);
}

// 공격 애니메이션 재생
Enemy->PlayAttackAnimation();

// 공격을 시작한 시점에 쿨타임 기록
Enemy->MarkAttack();

5. EnemyCharacter - Anim Notify 시점 실제 데미지 적용

// EnemyCharacter.cpp

// Notify가 늦게 호출되는 동안 플레이어가 멀리 도망간 경우 데미지를 주지 않음
const float DistanceToTarget = FVector::Dist2D(
    GetActorLocation(),
    TargetActor->GetActorLocation()
);

if (DistanceToTarget > AttackRange + 50.f)
{
    return;
}

// TargetActor는 플레이어이므로 플레이어의 TakeDamage가 호출됨
UGameplayStatics::ApplyDamage(
    TargetActor,
    AttackDamage,
    AIController,
    this,
    nullptr
);

6. EnemyCharacter - 사망 처리

// EnemyCharacter.cpp

// 사망 후 이동과 충돌을 막아 AI가 더 이상 움직이거나 막히지 않게 함
GetCharacterMovement()->DisableMovement();
GetCharacterMovement()->StopMovementImmediately();
GetCapsuleComponent()->SetCollisionEnabled(ECollisionEnabled::NoCollision);

// BP_EnemyCharacter에서 연결한 사망 몽타주 재생
PlayDeathAnimation();

// 사망 애니메이션이 보일 시간을 준 뒤 액터 제거
SetLifeSpan(2.5f);

프로젝트 개인 회고

이번 적 AI 구현은 수업에서 아직 자세히 다루지 않은 내용이라 처음에는 구조를 이해하는 데 어려움이 있었다.
그래서 Unreal Engine의 AIController, Blackboard, Behavior Tree, Anim Notify 관련 자료와 영상을 참고하면서 전체 흐름을 먼저 공부했다.

처음에는 적이 플레이어를 따라오고 공격하는 기능이 단순할 것이라고 생각했는데,

실제로 진행해보니 플레이어 탐지, TargetActor 갱신, 추적 조건, 공격 범위 판단, 공격 애니메이션, 데미지 적용 타이밍, 사망 처리까지 여러 요소가 연결되어야 자연스럽게 동작한다는 것을 알게 되었다.

특히 BTTask_AttackTarget에서 바로 데미지를 적용하는 방식과 Anim Notify 시점에 데미지를 적용하는 방식의 차이를 보면서,

게임 개발에서는 코드가 실행되는 시점뿐만 아니라 플레이어가 체감하는 애니메이션 타이밍도 중요하다는 점을 배웠다.

또한 EnemyAIController, Blackboard, Behavior Tree, EnemyCharacter가

각각 어떤 역할을 맡는지 정리하면서 Unreal Engine의 AI 구조를 더 명확하게 이해할 수 있었다.

이번 구현을 통해 아직 익숙하지 않은 기능도 자료를 찾아보고 흐름을 분석하면 프로젝트에 적용할 수 있다는 자신감을 얻었다.

다음 프로젝트 부터는 이 구조를 더 공부해서 여러 공격 패턴, 피격 애니메이션, 난이도별 AI 반응 속도 같은 기능도 직접 확장해보고 싶다.

Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 구조 정리 및 트러블슈팅

hyunjunstar — Tue, 26 May 2026 23:55:50 +0900

적 AI 구현

EnemySpawner

- NavMesh 위에 적 랜덤 생성

EnemyAIController
- 플레이어를 0.2초마다 탐지
- 감지되면 Blackboard.TargetActor에 저장

Behavior Tree
- TargetActor가 있으면 추적
- 공격 범위 안이면 공격 Task 실행

BTDecorator_IsInAttackRange
- 플레이어가 공격 범위 안인지 검사

BTTask_AttackTarget
- 이동 정지
- 플레이어 방향으로 회전
- 공격 애니메이션 실행

EnemyCharacter
- HP, 공격력, 탐지/공격 범위 관리
- Anim Notify 시점에 실제 데미지 적용

- 사망 시 점수 지급, 이동/충돌 비활성화

1. 적 캐릭터 구현

1-1. 체력 / 방어력 시스템 구현

- EnemyCharacter에서 MaxHP, CurrentHP, Defense 관리
- 피격 시 방어력을 반영해 최종 데미지 계산

1-2. 피격 / 사망 처리

- TakeDamage()로 데미지 수신
- HP가 0 이하가 되면 Die() 실행
- 사망 시 점수 지급, 이동 비활성화, 충돌 제거, 사망 애니메이션 재생

2. 플레이어 탐지

- EnemyAIController에서 플레이어를 0.2초마다 탐지
- 적과 플레이어 사이의 거리를 계산
- DetectionRange 안에 있으면 Blackboard의 TargetActor에 플레이어 저장
- 범위 밖이면 TargetActor 제거

3. 플레이어 추적

- Behavior Tree에서 TargetActor가 존재하면 추적 로직 실행
- Blackboard에 저장된 플레이어를 기준으로 이동
- NavMesh를 사용해 이동 가능한 경로를 따라 추적

4. 공격 범위 내 공격

- BTDecorator_IsInAttackRange에서 플레이어가 공격 범위 안에 있는지 검사
- 범위 안이면 BTTask_AttackTarget 실행
- 공격 Task에서 이동 정지
- 플레이어 방향으로 회전
- 공격 애니메이션 실행
- 실제 데미지는 애니메이션 Notify 시점에 ApplyAttackDamage()로 적용

5. NavMesh 기반 경로 탐색

- EnemySpawner가 NavMesh 위의 랜덤 위치를 찾아 적 생성
- AI 이동도 NavMesh 기반으로 처리
- 벽이나 이동 불가능한 영역을 피해 플레이어에게 접근

6. 장애물 회피

- EnemyCharacter의 CharacterMovement에 RVO Avoidance 적용
- 여러 적이 동시에 이동할 때 서로 겹치는 현상 완화
- 회피 반경을 설정해 적들이 자연스럽게 퍼져 이동하도록 처리

추가 리스트

1. 적 AI EnemySpawner

- 스폰할 적 클래스 EnemyClass 지정
- 스폰 개수 EnemySpawnCount 설정
- 스폰 반경 SpawnRadius 설정
- 충돌 시 스폰 실패 처리
- 무한 반복 방지를 위한 최대 스폰 시도 횟수 적용

2. 스킬 공격 / Grenade 추가 리스트

스킬공격 구현

CombatComponent.FireGrenade()
- 스킬 사용 가능 여부 확인
- 손 소켓(hand_rSocket) 위치 계산
- 카메라 기준 조준 방향 보정
- GrenadeProjectile 생성
- 데미지 / 폭발 반경 전달

GrenadeProjectile 코드 구조

CollisionComp
- 충돌 판정용 SphereComponent

MeshComp
- 외형 표시용 StaticMeshComponent

ProjectileMovement
- 속도, 중력, 바운스, 마찰 적용

FuseTimer
- 일정 시간 후 Explode 실행

Explode()
- 현재 위치에 폭발 이펙트 생성
- 폭발 사운드 재생
- ApplyRadialDamage로 범위 데미지 적용
- 투사체 Destroy

트러블슈팅

적 AI

문제 1. 공격 애니메이션과 데미지 타이밍이 안 맞음

// ========== 기존 코드 ========== // 

// BTTask_AttackTarget.cpp

UGameplayStatics::ApplyDamage(
    TargetActor,
    Enemy->AttackDamage,
    AIController,
    Enemy,
    nullptr
    );

// ========== 수정 후 코드 ========== // 

// BTTask_AttackTarget.cpp

Enemy->PlayAttackAnimation();
Enemy->MarkAttack();

// EnemyCharacter.h

UFUNCTION(BlueprintCallable, Category = "Enemy|Attack")
void ApplyAttackDamage();

// EnemyCharacter.cpp

void AEnemyCharacter::ApplyAttackDamage()
{
    if (bIsDead)
    {
        return;
    }
    AAIController* AIController = Cast<AAIController>(GetController());
    if (!AIController)
    {
        return;
    }
    UBlackboardComponent* BlackboardComp = AIController->GetBlackboardComponent();
    if (!BlackboardComp)
    {
        return;
    }

    AActor* TargetActor = Cast<AActor>(
        BlackboardComp->GetValueAsObject(TEXT("TargetActor"))
    );

    if (!TargetActor)
    {
        return;
    }

    UGameplayStatics::ApplyDamage(
        TargetActor,
        AttackDamage,
        AIController,
        this,
        nullptr
        );
}

- BTTask에서 바로 데미지를 주지 않고, Anim Notify에서 ApplyAttackDamage 호출로 해결

문제 2. 적이 죽은 뒤에도 움직이거나 공격하려고 함

// ========== 기존 코드 ========== // 

// EnemyCharacter.cpp

void AEnemyCharacter::Die()
{
    if (bIsDead)
    {
        return;
    }
    bIsDead = true;
    AShooterGameMode* GM = Cast<AShooterGameMode>(UGameplayStatics::GetGameMode(this));
     
    if (GM)
    {
        GM->AddScore(ScoreValue);
    }
    Destroy();
}

// ========== 수정후 코드 ========== // 

// BTTask_AttackTarget.cpp

AEnemyCharacter* Enemy = Cast<AEnemyCharacter>(AIController->GetPawn());
if (!Enemy || Enemy->IsDead())
{
    return EBTNodeResult::Failed;
}

// BTDecorator_IsInAttackRange.cpp

const AEnemyCharacter* Enemy = Cast<AEnemyCharacter>(AIController->GetPawn());
if (!Enemy || Enemy->IsDead())
{
    return false;
}

// EnemyCharacter.cpp

void AEnemyCharacter::Die()
{
    if (bIsDead)
    {
        return;
    }
    
    bIsDead = true;

    AShooterGameMode* GM = Cast<AShooterGameMode>(UGameplayStatics::GetGameMode(this));
    if (GM)
    {
        GM->AddScore(ScoreValue);
    }

    GetCharacterMovement()->DisableMovement();
    GetCharacterMovement()->StopMovementImmediately();
    GetCapsuleComponent()->SetCollisionEnabled(ECollisionEnabled::NoCollision);

    PlayDeathAnimation();

    SetLifeSpan(2.5f);
}

- IsDead 체크 추가, 사망 시 Movement/Collision 비활성화로 해결

문제 3. 플레이어가 공격 범위 밖으로 벗어나도 맞는 문제

// ========== 기존 코드 ========== // 

// BTDecorator_IsInAttackRange.cpp

const float Distance = FVector::Dist2D(
    Enemy->GetActorLocation(),
    TargetActor->GetActorLocation()
    );

return Distance <= Enemy->AttackRange;

// ========== 수정후 코드 ========== // 
  
// EnemyCharacter.cpp
void AEnemyCharacter::ApplyAttackDamage()
{
    if (bIsDead)
    {
        return;
    }

    AAIController* AIController = Cast<AAIController>(GetController());
    if (!AIController)
    {
        return;
    }

    UBlackboardComponent* BlackboardComp = AIController->GetBlackboardComponent();
    if (!BlackboardComp)
    {
        return;
    }

    AActor* TargetActor = Cast<AActor>(
        BlackboardComp->GetValueAsObject(TEXT("TargetActor"))
        );

    if (!TargetActor)
    {
        return;
    }

    const float DistanceToTarget = FVector::Dist2D(
        GetActorLocation(),
        TargetActor->GetActorLocation()
        );

    if (DistanceToTarget > AttackRange + 50.f)
    {
        return;
    }

    UGameplayStatics::ApplyDamage(
        TargetActor,
        AttackDamage,
        AIController,
        this,
        nullptr
    );
}

- Notify 시점에 AttackRange + 보정값으로 거리 재검사로 해결

문제 4. 여러 적이 겹쳐서 이동이 어색함

// ========== 기존 코드 ========== // 

// EnemyCharacter.cpp

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

    MaxHP = 100.f;
    CurrentHP = MaxHP;
    Defense = 0.f;
    ScoreValue = 1;
    AttackDamage = 10.f;
    DetectionRange = 1200.f;
    AttackRange = 150.f;
    AttackCooldown = 1.5f;
    bIsDead = false;
}

// ========== 수정후 코드 ========== // 

// EnemyCharacter.cpp

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

    MaxHP = 100.f;
    CurrentHP = MaxHP;
    Defense = 0.f;
    ScoreValue = 1;
    AttackDamage = 10.f;
    DetectionRange = 1200.f;
    AttackRange = 150.f;
    AttackCooldown = 1.5f;
    LastAttackTime = -AttackCooldown;
    bIsDead = false;

    GetCharacterMovement()->bUseRVOAvoidance = true;
    GetCharacterMovement()->AvoidanceConsiderationRadius = 300.f;

    bUseControllerRotationYaw = false;
    GetCharacterMovement()->bOrientRotationToMovement = true;
    GetCharacterMovement()->RotationRate = FRotator(0.f, 720.f, 0.f);
}

- CharacterMovement에 RVO Avoidance 적용으로 해결

스킬 공격

문제 1. 투사체로 변경 후 발사하자마자 플레이어와 충돌하는 문제

// ========== 기존 코드 ========== // 

// CombatComponent.cpp

FVector ExplodeLocation = BaseStart + (ShootDirection * 400.f);

TArray<AActor*> IgnoreActors;
IgnoreActors.Add(Owner);

UGameplayStatics::ApplyRadialDamage(
    GetWorld(),
    GrenadeDamage,
    ExplodeLocation,
    GrenadeRadius,
    UDamageType::StaticClass(),
    IgnoreActors,
    Owner,
    Owner->GetInstigatorController(),
    true
    );

// ========== 수정후 코드 ========== // 

// CombatComponent.cpp

FActorSpawnParameters SpawnParams;
SpawnParams.Owner = Owner;
SpawnParams.Instigator = Cast<APawn>(Owner);
SpawnParams.SpawnCollisionHandlingOverride =
    ESpawnActorCollisionHandlingMethod::AdjustIfPossibleButAlwaysSpawn;

AGrenadeProjectile* Grenade = GetWorld()->SpawnActor<AGrenadeProjectile>(
    GrenadeProjectileClass,
    SpawnLocation,
    ShootDirection.Rotation(),
    SpawnParams
    );
    
// GrenadeProjectile.cpp

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

    if (AActor* OwnerActor = GetOwner())
    {
        CollisionComp->IgnoreActorWhenMoving(OwnerActor, true);
    }

    GetWorldTimerManager().SetTimer(
        FuseTimerHandle,
        this,
        &AGrenadeProjectile::Explode,
        FuseTime,
        false
        );
  }

- GrenadeProjectile BeginPlay에서 OwnerActor를 충돌 무시 처리로 해결

문제 2. 조준 방향과 실제 발사 방향이 어긋남

// ========== 기존 코드 ========== // 

// CombatComponent.cpp

FVector ShootDirection = Owner->GetActorForwardVector();
FVector BaseStart = Owner->GetActorLocation();

if (CharOwner)
{
    if (APlayerController* PC = Cast<APlayerController>(CharOwner->GetController()))
    {
        FVector CameraLoc;
        FRotator CameraRot;
        PC->GetPlayerViewPoint(CameraLoc, CameraRot);

        ShootDirection = CameraRot.Vector();
        BaseStart = CameraLoc;
    }
}

FVector ExplodeLocation = BaseStart + (ShootDirection * 400.f);

// ========== 수정후 코드 ========== // 

// CombatComponent.cpp

ACharacter* CharOwner = Cast<ACharacter>(Owner);

FVector SpawnLocation = Owner->GetActorLocation();
FVector ShootDirection = Owner->GetActorForwardVector();

if (CharOwner)
{
    if (CharOwner->GetMesh()->DoesSocketExist(TEXT("hand_rSocket")))
    {
        SpawnLocation = CharOwner->GetMesh()->GetSocketLocation(TEXT("hand_rSocket"));
    }

    if (APlayerController* PC = Cast<APlayerController>(CharOwner->GetController()))
    {
        FVector CameraLoc;
        FRotator CameraRot;
        PC->GetPlayerViewPoint(CameraLoc, CameraRot);

        FVector TraceStart = CameraLoc;
        FVector TraceEnd = TraceStart + CameraRot.Vector() * 3000.f;

        FHitResult HitResult;
        FCollisionQueryParams Params;
        Params.AddIgnoredActor(Owner);

        bool bHit = GetWorld()->LineTraceSingleByChannel(
            HitResult,
            TraceStart,
            TraceEnd,
            ECC_Visibility,
            Params
            );

        FVector TargetPoint = bHit ? HitResult.ImpactPoint : TraceEnd;

        ShootDirection = (TargetPoint - SpawnLocation).GetSafeNormal();
    }
}

SpawnLocation += ShootDirection * 40.f;
SpawnLocation += FVector(0.f, 0.f, 10.f);

AGrenadeProjectile* Grenade = GetWorld()->SpawnActor<AGrenadeProjectile>(
    GrenadeProjectileClass,
    SpawnLocation,
    ShootDirection.Rotation(),
    SpawnParams
    );

- 카메라 LineTrace 기준으로 목표 지점을 계산하고 손 소켓에서 그 방향으로 발사로 해결

문제 3. 폭발 연출과 데미지 처리가 분리되어 어색함

// ========== 기존 코드 ========== // 

// CombatComponent.cpp

FVector ExplodeLocation = BaseStart + (ShootDirection * 400.f);

DrawDebugSphere(
    GetWorld(),
    ExplodeLocation,
    GrenadeRadius,
    16,
    FColor::Purple,
    false,
    2.0f,
    0,
    1.5f
    );

TArray<AActor*> IgnoreActors;
IgnoreActors.Add(Owner);

UGameplayStatics::ApplyRadialDamage(
    GetWorld(),
    GrenadeDamage,
    ExplodeLocation,
    GrenadeRadius,
    UDamageType::StaticClass(),
    IgnoreActors,
    Owner,
    Owner->GetInstigatorController(),
    true
    );

// ========== 수정후 코드 ========== // 

// CombatComponent.cpp

AGrenadeProjectile* Grenade = GetWorld()->SpawnActor<AGrenadeProjectile>(
    GrenadeProjectileClass,
    SpawnLocation,
    ShootDirection.Rotation(),
    SpawnParams
    );

if (Grenade)
{
    Grenade->SetExplosionData(GrenadeDamage, GrenadeRadius);
}

// GrenadeProjectile.cpp

void AGrenadeProjectile::SetExplosionData(float InDamage, float InRadius)
{
    ExplosionDamage = InDamage;
    ExplosionRadius = InRadius;
}

void AGrenadeProjectile::Explode()
{
    if (bHasExploded) return;
    bHasExploded = true;

    FVector ExplodeLocation = GetActorLocation();

    if (GrenadeEffect)
    {
        UGameplayStatics::SpawnEmitterAtLocation(
            GetWorld(),
            GrenadeEffect,
            ExplodeLocation
        );
    }

    if (GrenadeSound)
    {
        UGameplayStatics::PlaySoundAtLocation(
            GetWorld(),
            GrenadeSound,
            ExplodeLocation,
            GrenadeSoundVolume
            );
    }

    TArray<AActor*> IgnoreActors;
    if (GetOwner())
    {
        IgnoreActors.Add(GetOwner());
    }

    UGameplayStatics::ApplyRadialDamage(
        GetWorld(),
        ExplosionDamage,
        ExplodeLocation,
        ExplosionRadius,
        UDamageType::StaticClass(),
        IgnoreActors,
        this,
        GetInstigatorController(),
        true
        );

    Destroy();
}

- Explode 함수 안에서 이펙트, 사운드, 범위 데미지를 한 번에 처리로 해결

Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 4

hyunjunstar — Sat, 23 May 2026 02:37:02 +0900

https://hyunjunstar.tistory.com/100

이전 글인 위 링크의 Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 3 에서는 Behavior Tree와 Blackboard의 블루프린트 구조를 정리하고, EnemyCharacter 블루프린트를 생성 및 Nav Mesh Bounds Volume를 설정 하였다.

하지만 2, 3 단계 구조에는 첫번째로 TargetActor 갱신이 한번만 실행되는 문제와,

ApplyDamage()를 즉시 호출 하는 문제가 있었다.

이번 글에서는 이 부분을 수정하고,

Montage와 Anim Notify, Anim Graph를 사용하여 더 자연스러운 AI 캐릭터를 만들어 보려고 한다.

C++ Code

EnemyAIController.cpp

SetTimer()를 반복 실행으로 변경하였다.
이제 0.2초마다 플레이어를 감지하고, 플레이어가 감지 범위 안에 있을 때만 Blackboard의 TargetActor를 설정한다.
감지 범위 밖으로 나가면 TargetActor를 제거하도록 수정하였다.

GetWorldTimerManager().SetTimer(
    FindPlayerTimerHandle,
    this,
    &AEnemyAIController::SetTargetPlayer,
    0.2f,
    true
);

기존에는 마지막 인자가 false였기 때문에 SetTargetPlayer()가 한 번만 실행되었다.
그래서 이번에는 true로 변경해 0.2초마다 반복 실행되도록 했다.
또한 SetTargetPlayer()에서는 플레이어와 적 사이의 거리를 계산한다.

const float DistanceToPlayer = FVector::Dist(
    ControlledEnemy->GetActorLocation(),
    TargetPlayer->GetActorLocation()
);

그리고 감지 범위 안에 있을때만 TargetActor를 저장한다.

if (DistanceToPlayer <= ControlledEnemy->DetectionRange)
{
    BB->SetValueAsObject(TEXT("TargetActor"), TargetPlayer);
}
else
{
    BB->ClearValue(TEXT("TargetActor"));
}

이렇게 수정하면 플레이어가 감지 범위 밖으로 나갔을 때 Behavior Tree가 더 이상 추적이나 공격을 하지 않는다.

EnemyCharacter.h

공격 / 사망 애니메이션, 공격 쿨타임, 실제 데미지 적용을 위한 함수들을 추가하였다.

UFUNCTION(BlueprintImplementableEvent, BlueprintCallable, Category = "Enemy|Animation")
void PlayAttackAnimation();

UFUNCTION(BlueprintImplementableEvent, BlueprintCallable, Category = "Enemy|Animation")
void PlayDeathAnimation();

PlayAttackAnimation()과 PlayDeathAnimation()은 C++에서 호출하고,

실제 몽타주 재생은 BP_EnemyCharacter에서 구현하기 위해 BlueprintImplementableEvent로 선언하였다.
공격 쿨타임을 관리하기 위한 함수도 추가하였다.

bool CanAttack() const;
void MarkAttack();

그리고 공격 몽타주의 AttackHit Notify 시점에 실제 데미지를 적용할 함수도 추가하였다.

UFUNCTION(BlueprintCallable, Category = "Enemy|Attack")
void ApplyAttackDamage();

기존에는 BTTask_AttackTarget에서 바로 ApplyDamage()를 호출했지만,

이번에는 ApplyAttackDamage()에서 실제 데미지를 적용하도록 변경하였다.

EnemyCharacter.cpp

공격 쿨타임, RVO 회피, 회전 설정, 실제 데미지 적용, 사망 애니메이션 처리를 추가하였다.

// 공격 쿨타임 초기화
LastAttackTime = -AttackCooldown;

처음부터 바로 공격할 수 있도록 LastAttackTime을 -AttackCooldown으로 초기화 하였다.

// RVO 회피 설정
GetCharacterMovement()->bUseRVOAvoidance = true;
GetCharacterMovement()->AvoidanceConsiderationRadius = 300.f;

AI가 이동할 때 장애물에 막히거나 서로 겹치는 상황을 방지하기 위해 RVO를 활성화 하였다.

// 이동 방향 회전 설정
bUseControllerRotationYaw = false;
GetCharacterMovement()->bOrientRotationToMovement = true;
GetCharacterMovement()->RotationRate = FRotator(0.f, 720.f, 0.f);

AI가 이동할 때 이동 방향을 바라보도록 설정 하였다.

// 공격 쿨타임 처리
bool AEnemyCharacter::CanAttack() const
{
    const UWorld* World = GetWorld();
    if (!World)
    {
        return false;
    }

    return World->GetTimeSeconds() - LastAttackTime >= AttackCooldown;
}

void AEnemyCharacter::MarkAttack()
{
    const UWorld* World = GetWorld();
    if (!World)
    {
        return;
    }

    LastAttackTime = World->GetTimeSeconds();
}

CanAttack()은 마지막 공격 이후 AttackCooldown만큼 시간이 지났는지 계산 하도록 하였고,

MarkAttack()은 공격을 시작한 시간을 LastAttackTime에 저장하도록 하였다.

// 실제 데미지 적용
void AEnemyCharacter::ApplyAttackDamage()
{
    if (bIsDead)
    {
        return;
    }

    AAIController* AIController = Cast<AAIController>(GetController());
    if (!AIController)
    {
        return;
    }

    UBlackboardComponent* BlackboardComp = AIController->GetBlackboardComponent();
    if (!BlackboardComp)
    {
        return;
    }

    AActor* TargetActor = Cast<AActor>(
        BlackboardComp->GetValueAsObject(TEXT("TargetActor"))
    );

    if (!TargetActor)
    {
        return;
    }

    const float DistanceToTarget = FVector::Dist(
        GetActorLocation(),
        TargetActor->GetActorLocation()
    );

    if (DistanceToTarget > AttackRange + 50.f)
    {
        return;
    }

    UGameplayStatics::ApplyDamage(
        TargetActor,
        AttackDamage,
        AIController,
        this,
        nullptr
    );
}

ApplyAttackDamage()는 공격 몽타주의 AttackHit Notify에서 호출 되도록 하였고,
이 함수에서는 Blackboard의 TargetActor를 가져온 뒤, 공격 가능한 거리 안에 있는지 다시 확인한다.
공격 모션이 재생되는 동안 플레이어가 멀리 벗어날 수 있기 때문에 데미지를 적용하기 직전에 거리를 한 번 더 검사하였다.
조건을 만족하면 UGameplayStatics::ApplyDamage()를 호출해 플레이어에게 데미지를 주도록 하였다.

// 사망 처리 변경
GetCharacterMovement()->DisableMovement();
GetCharacterMovement()->StopMovementImmediately();
GetCapsuleComponent()->SetCollisionEnabled(ECollisionEnabled::NoCollision);

PlayDeathAnimation();

SetLifeSpan(3.0f);

적이 죽으면 이동을 비활성화하고 정지 시킨 후,

충돌을 제거한 뒤 PlayDeathAnimation()을 호출해 사망 몽타주를 재생한다.
그리고 사망 애니메이션이 보일 시간을 준 뒤 3초 후 제거하도록 변경하였다.

BTTask_AttackTarget.cpp

이전에는 공격 Task가 실행되면 바로 ApplyDamage()를 호출 하였는데,
이번에는 ApplyDamage()를 제거하고, 공격 몽타주만 재생하도록 변경하였다.

// 공격 쿨타임 확인
if (!Enemy->CanAttack())
{
    return EBTNodeResult::Failed;
}

공격 Task가 실행되기 전에 CanAttack()을 호출하여 쿨타임이 끝났는지 확인 하도록 하였다.

// 이동 정지
AIController->StopMovement();
AIController->ClearFocus(EAIFocusPriority::Gameplay);

Enemy->GetCharacterMovement()->StopMovementImmediately();

공격 중에는 이동하지 않도록 이동을 멈추고, CharacterMovement도 정지 시켰다.

// 플레이어 방향으로 회전
FVector Direction = TargetActor->GetActorLocation() - Enemy->GetActorLocation();
Direction.Z = 0.f;

if (!Direction.IsNearlyZero())
{
    FRotator LookRotation = Direction.Rotation();

    Enemy->SetActorRotation(LookRotation);
    AIController->SetControlRotation(LookRotation);
}

공격하기 직전에 플레이어 방향을 바라보도록 회전 시켰다.

// 공격 몽타주 재생
Enemy->PlayAttackAnimation();
Enemy->MarkAttack();

PlayAttackAnimation()을 호출해 BP_EnemyCharacter에서 공격 몽타주를 재생한다.
그리고 MarkAttack()으로 공격 시작 시간을 기록하고,
공격 몽타주의 AttackHit Anim Notify에서 ApplyAttackDamage()가 호출될 때 데미지를 주도록 하였다.

Montage

몽타주 원본 파일 우클릭 후 Create AnimMontage 선택해서 몽타주를 생성 하였고,

공격하는 모션이 실행 된 후 실제 타격이 발생하는 지점에 AttackHit Notify를 추가하였고,

이 Notify가 실행되는 시점에 EnemyCharacter의 ApplyAttackDamage()를 호출하여

플레이어에게 데미지를 입히도록 설정하였다.

Blueprint

ABP_EnemyCharacer

Event Graph

1. AnimNotify_AttackHit

공격 몽타주에 추가한 AttackHit Notify가 실행될 때 호출된다.
Try Get Pawn Owner로 현재 애니메이션 블루프린트를 사용하는 Pawn을 가져오고,

BP_EnemyCharacter로 Cast한다.

Cast에 성공하면 EnemyCharacter에 구현해둔 ApplyAttackDamage()를 호출한다.
이렇게 해서 공격 모션의 실제 타격 프레임에 플레이어에게 데미지가 들어가도록 만들었다.

2.Speed

Try Get Pawn Owner로 현재 애니메이션을 사용하는 Pawn을 가져오고, Is Valid로 유효한지 확인한다.
유효하면 Get Velocity로 캐릭터의 현재 속도 벡터를 가져온다.
이후 Vector Length XY를 사용해 Z축을 제외한 이동 속도를 계산하고, 그 값을 Speed 변수에 저장한다.

Speed 값 0 = Idle
Speed 값 증가 = Walk / Run

Anim Graph

EventGraph에서 계산한 Speed 값을 BS_MM_WalkRun Blend Space에 전달하여 Idle / Walk / Run 애니메이션이 전환되도록 하였다.
그리고 Blend Space 뒤에 Slot 'DefaultSlot'을 연결하였다.

이 Slot을 통해 공격 / 사망 몽타주가 기본 이동 애니메이션 위에 재생될 수 있도록 만들었다.
마지막으로 Slot의 결과를 Output Pose에 연결하여 AI 캐릭터의 최종 애니메이션으로 출력되도록 하였다.

BP_EnemyCharacer

Event Graph

1. Montage Attack

PlayAttackAnimation 이벤트는 C++의 EnemyCharacter에서 호출하는 Blueprint 이벤트다.

이 이벤트가 실행되면 Attack Montages 배열에 들어 있는 공격 몽타주 중 하나를 랜덤으로 선택한다.
먼저 배열의 Length가 0보다 큰지 확인하고,

배열이 비어 있지 않으면 Random Integer in Range로 랜덤 인덱스를 만든다.
그 후 Attack Montages 배열에서 해당 인덱스의 몽타주를 가져오고,

Mesh의 Anim Instance를 Target으로 넘겨 Montage Play를 실행한다.
공격할 때마다 Attack Montages 배열에 등록된 공격 모션 중 하나가 랜덤으로 재생되는 구조로 설계하였다.

2. Montage Damage

Event AnyDamage는 BP_EnemyCharacter가 데미지를 받았을 때 호출된다.

데미지가 정상적으로 들어오는지 확인하기 위해 Print String을 사용하였다.
Damage 값과 Current HP 값을 Append로 합쳐서 "Enemy Damage: / HP:" 형태의 문자열을 만들고,

화면에 출력하도록 설계하였다.

3. Montage Die

PlayDeathAnimation 이벤트는 C++의 EnemyCharacter::Die()에서 호출된다.
적의 HP가 0 이하가 되면 C++ 코드에서 이동과 충돌을 비활성화한 뒤 PlayDeathAnimation()을 호출한다.
BP_EnemyCharacter에서는 이 이벤트를 받아 Mesh의 Anim Instance를 가져오고,

Montage Play로 AM_Enemy_Die 사망 몽타주를 재생한다.

최종 변경 후 구조

최종 버전에서는 Behavior Tree 구조는 유지하면서,

TargetActor 갱신 방식과 공격 데미지 적용 방식을 개선하였다.

EnemyAIController
- Behavior Tree 실행
- 0.2초마다 플레이어 감지
- 감지 범위 안이면 Blackboard에 TargetActor 설정
- 감지 범위 밖이면 TargetActor 제거

EnemyCharacter
- Behavior Tree asset 소유
- ApplyDamage를 TakeDamage로 받아서 HP를 처리
- 공격 쿨타임 관리
- 공격 / 사망 몽타주 재생 이벤트 제공
- Anim Notify 시점에 실제 데미지 적용
- 사망 시 이동/충돌 비활성화 후 사망 몽타주 재생
- RVO 회피 및 이동 방향 회전 처리

BTDecorator_IsInAttackRange
- TargetActor가 공격 범위 안에 있는지 검사

BTTask_AttackTarget
- 공격 쿨타임 확인
- 이동 정지
- 플레이어 방향으로 회전
- 공격 몽타주 재생
- 직접 데미지를 주지 않음

Montage
- 공격 / 사망 애니메이션을 원하는 시점에 재생하기 위해 사용
- 공격 몽타주에 AttackHit Notify 추가
- Notify 시점에 실제 데미지 적용

ABP_EnemyCharacter
- Speed 값을 계산해 Idle / Walk / Run 전환
- AnimGraph에서 Blend Space와 DefaultSlot 연결
- AttackHit Notify 발생 시 ApplyAttackDamage() 호출

BP_EnemyCharacter
- PlayAttackAnimation 이벤트에서 공격 몽타주 랜덤 재생
- PlayDeathAnimation 이벤트에서 사망 몽타주 재생
- Event AnyDamage로 데미지 / HP 디버그 출력

1. EnemyAIController가 EnemyCharacter를 Possess
2. EnemyCharacter에 설정된 Behavior Tree 실행
3. 0.2초마다 플레이어 Pawn 탐색
4. 감지 범위 안이면 Blackboard에 TargetActor 저장
5. 감지 범위 밖이면 TargetActor 제거
6. Behavior Tree가 TargetActor를 기준으로 이동 / 공격 판단
7. BTDecorator_IsInAttackRange가 공격 거리 검사
8. 공격 범위 안이면 BTTask_AttackTarget 실행
9. BTTask_AttackTarget이 이동을 멈추고 플레이어 방향으로 회전
10. PlayAttackAnimation() 호출
11. BP_EnemyCharacter에서 공격 몽타주 랜덤 재생
12. 공격 몽타주의 AttackHit Notify 발생
13. ABP_EnemyCharacter의 AnimNotify_AttackHit에서 BP_EnemyCharacter로 Cast
14. ApplyAttackDamage() 호출
15. ApplyDamage()로 플레이어에게 실제 데미지 적용
16. 적 사망 시 PlayDeathAnimation() 호출
17. BP_EnemyCharacter에서 사망 몽타주 재생
18. 3초 뒤 액터 제거

이번 버전에서는 SetTargetPlayer()를 0.2초마다 반복 실행하도록 수정하고,

플레이어가 감지 범위 밖으로 나가면 Blackboard의 TargetActor를 제거하도록 변경하였다.

또한 BTTask_AttackTarget에서 직접 ApplyDamage()를 호출하던 구조를 제거하고,

PlayAttackAnimation()만 실행하도록 수정하였다.

실제 데미지는 공격 몽타주의 AttackHit Notify 시점에 ApplyAttackDamage()가 호출되면서 적용된다.

공격 쿨타임은 EnemyCharacter의 CanAttack(), MarkAttack()으로 관리하도록 옮겼고,

공격 시 이동 정지와 플레이어 방향 회전도 추가하였다.

사망 시에는 이동과 충돌을 끄고 PlayDeathAnimation()을 호출한 뒤 3초 후 제거되도록 변경하였다.

결론은 플레이어 감지 흐름이 더 자연스러워졌고, 공격 애니메이션과 실제 데미지 적용 타이밍을 맞출 수 있었다.

Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 3

hyunjunstar — Thu, 21 May 2026 21:55:30 +0900

https://hyunjunstar.tistory.com/99

이전 글인 위 링크의 Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 2 에서는 Behavior Tree와 Blackboard 기반으로 적 AI 캐릭터를 구현 하였다.

이번 글에서는 Behavior Tree와 Blackboard의 블루프린트 구조를 정리하고,

EnemyCharacter 블루프린트를 생성 해보려고 한다.

Blackboard

New Key로 TargetActor를 추가하여 Key Type은 Object로 설정하고,

Base Class에 Actor를 지정하였다.

TargetActor는 AI가 추적하거나 공격할 대상을 저장하는 값이며,
EnemyAIController에서 플레이어를 감지하면 Blackboard의 TargetActor에 플레이어 Pawn을 저장하고,

Behavior Tree는 이 값을 기준으로 추적과 공격을 판단한다.

Behavior Tree

Selector를 기준으로 공격, 추적, 대기 흐름을 나누었다.

TargetActor가 존재하고 공격 범위 안에 있으면 Sequence_Attack이 실행된다.
이 Sequence 안에서는 BTDecorator_IsInAttackRange 조건을 확인한 뒤,

BTTask_AttackTarget을 실행해 공격을 실행한다.

TargetActor는 존재하지만 공격 범위 밖이라면 Sequence_Chase가 실행된다.
이때 Move To 노드를 사용해 플레이어를 추적한다.

공격과 추적 조건을 모두 만족하지 않으면 Wait 노드가 실행되어 잠시 대기하도록 구성하였다.

BP_EnemyCharacter

EnemyCharacter를 상속받는 블루프린트 클래스 생성 후,

Class Defaults - Details - Pawn 에서 AI Controller Class에 EnemyAIController 지정 후,

Mesh에서 Skeletal Mesh Asset에 SKM_Manny를 지정해주었다.

ABP_EnemyCharacter

SK_Mannequin 스켈레톤 선택 후, AnimInstance를 상속받는 Animation Blueprint 클래스 생성

생성 후 BP_EnemyCharacter에 Class Defaults - Details - Mesh - Location Z축 -88, Rotation Z축 270도로 설정,

그리고 Animation - Anim Class에 ABP_EnemyCharacter 지정

Nav Mesh Bounds Volume

좌측 Place Actors에서 Nav Mesh Bounds Volume 검색 후 배치를 해주었다.

이렇게 C++로 구현한 적 AI 기능을 기반으로,

Unreal Editor에서 Blackboard, Behavior Tree, BP_EnemyCharacter, ABP_EnemyCharacter를 설정하였다.

Blackboard에는 AI가 추적할 대상을 저장하기 위해 TargetActor 키를 추가하였고,

Behavior Tree에서는 이 값을 기준으로 공격, 추적, 대기 흐름을 구성하였다.

또한 EnemyCharacter를 상속받는 블루프린트를 생성하고 EnemyAIController, SKM_Manny, ABP_EnemyCharacter를 연결하여 적 캐릭터가 AI 컨트롤러와 애니메이션 블루프린트를 기반으로 동작할 수 있도록 설정하였다.

Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 2

hyunjunstar — Wed, 20 May 2026 23:55:12 +0900

https://hyunjunstar.tistory.com/97

이전 글인 위 링크 의 Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 1 에서는 초기 구현을 정리하였다.

초기 버전에는 EnemyAIController가 Tick에서 매 프레임마다 플레이어와 거리를 계산하고,

그에 맞는 상태를(Idle / Chase / Attack / Dead) 직접 관리하는 코드 방식으로 구현했다.

이번 글에서는 구조를 개선하여 Behavior Tree와 Blackboard를 사용하고,

NavMesh 기반 경로 탐색과 장애물 회피까지 포함한 AI 구조를 구현해보려고 한다.

Behavior Tree 사용 후 변경된 부분

기존 구조에서는 EnemyAIController가 모든 판단을 직접 처리했다.

EnemyAIController가 Tick()에서 직접 플레이어와의 거리를 계산하고,

Idle / Chase / Attack / Dead 상태를 관리하는 구조였다.

이번에는 이 구조를 개선해서 Behavior Tree와 Blackboard를 사용하도록 변경하였다.

EnemyAIController.h

처음에 구현했던 AIController가 직접 판단하고 관리하는 코드들을 제거하고,

Behavior Tree 실행, Blackboard에 TargetActor 설정 하는 식으로 변경하였다.

// EnemyAIController.h

#pragma once

#include "CoreMinimal.h"
#include "AIController.h"
#include "TimerManager.h"
#include "EnemyAIController.generated.h"

UCLASS()
class CH3_PROJECT_API AEnemyAIController : public AAIController
{
      GENERATED_BODY()

public:
      AEnemyAIController();

protected:
      // 적 캐릭터를 조종하기 시작할 때 호출
      virtual void OnPossess(APawn* InPawn) override;

private:
      // 현재 추적 중인 플레이어 Pawn
      UPROPERTY()
      APawn* TargetPlayer;

      // 현재 조종 중인 적 캐릭터
      UPROPERTY()
      class AEnemyCharacter* ControlledEnemy;

      // 주기적으로 플레이어를 찾아 Blackboard에 갱신하기 위한 타이머
      FTimerHandle FindPlayerTimerHandle;

      // 현재 월드의 플레이어 Pawn을 찾음
      void FindPlayer();

      // 감지 범위에 따라 Blackboard의 TargetActor를 설정하거나 제거
      void SetTargetPlayer();
};

EnemyAIController.cpp

RunBehaviorTree()를 사용하여 적 캐릭터에 지정된 Behavior Tree를 실행하고,

SetValueAsObject()를 사용하여 Blackboard에 플레이어를 TargetActor로 저장했다.

이렇게 Behavior Tree는 플레이어를 기준으로 추적, 공격 등 상황을 판단하고 실행하게 하였다.

// EnemyAIController.cpp

#include "EnemyAIController.h"
#include "EnemyCharacter.h"
#include "Kismet/GameplayStatics.h"
#include "BehaviorTree/BehaviorTree.h"
#include "BehaviorTree/BlackboardComponent.h"

// AIController 기본값 설정
AEnemyAIController::AEnemyAIController()
{
    // Behavior Tree가 판단을 담당하므로 Tick 비활성화
    PrimaryActorTick.bCanEverTick = false;

    TargetPlayer = nullptr;
    ControlledEnemy = nullptr;
}

// 적 캐릭터를 조종하기 시작할 때 호출
void AEnemyAIController::OnPossess(APawn* InPawn)
{
    Super::OnPossess(InPawn);

    // 현재 조종할 적 캐릭터 저장
    ControlledEnemy = Cast<AEnemyCharacter>(InPawn);
    if (!ControlledEnemy)
    {
        return;
    }

    // 적 캐릭터에 Behavior Tree가 없으면 실행 불가
    if (!ControlledEnemy->BehaviorTree)
    {
        UE_LOG(LogTemp, Warning, TEXT("BehaviorTree is null"));
        return;
    }

    // 적 캐릭터에 지정된 Behavior Tree 실행
    RunBehaviorTree(ControlledEnemy->BehaviorTree);

    // 일정 시간 뒤 플레이어를 찾아 Blackboard에 저장
    GetWorldTimerManager().SetTimer(
        FindPlayerTimerHandle,
        this,
        &AEnemyAIController::SetTargetPlayer,
        0.2f,
        false
    );
}

// 현재 월드의 플레이어 Pawn 찾기
void AEnemyAIController::FindPlayer()
{
    TargetPlayer = UGameplayStatics::GetPlayerPawn(this, 0);
}

// Blackboard에 TargetActor 설정
void AEnemyAIController::SetTargetPlayer()
{
    FindPlayer();

    UE_LOG(LogTemp, Warning, TEXT("TargetPlayer: %s"), *GetNameSafe(TargetPlayer));

    UBlackboardComponent* BB = GetBlackboardComponent();
    if (!BB)
    {
        UE_LOG(LogTemp, Warning, TEXT("BlackboardComponent is null"));
        return;
    }

    if (!TargetPlayer)
    {
        UE_LOG(LogTemp, Warning, TEXT("TargetPlayer is still None"));
        return;
    }

    // Behavior Tree에서 사용할 TargetActor 저장
    BB->SetValueAsObject(TEXT("TargetActor"), TargetPlayer);

    UE_LOG(LogTemp, Warning, TEXT("Blackboard TargetActor Set: %s"),
        *GetNameSafe(TargetPlayer));
}

EnemyCharacter.h

Behavior Tree를 사용하기 위해 변수를 추가하였고,

UGameplayStatics::ApplyDamage()와 연결하기 위해 TakeDamage()를 override했다.

// EnemyCharacter.h

#pragma once

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

class UBehaviorTree;

UCLASS()
class CH3_PROJECT_API AEnemyCharacter : public ACharacter
{
    GENERATED_BODY()

public:
    AEnemyCharacter();

    // 최대 HP
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Stat")
    float MaxHP;

    // 현재 HP
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Enemy|Stat")
    float CurrentHP;

    // 방어력
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Stat")
    float Defense;

    // 처치 시 획득 점수
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Reward")
    int32 ScoreValue;

    // 공격 데미지
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Attack")
    float AttackDamage;

    // 플레이어 감지 범위
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|AI")
    float DetectionRange;

    // 공격 가능 범위
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|AI")
    float AttackRange;

    // AIController가 실행할 Behavior Tree
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Enemy|AI")
    UBehaviorTree* BehaviorTree;

    // 공격 쿨타임
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Attack")
    float AttackCooldown;

    // Unreal 기본 데미지 시스템으로 받은 데미지를 HP에 반영
    virtual float TakeDamage(
        float DamageAmount,
        struct FDamageEvent const& DamageEvent,
        AController* EventInstigator,
        AActor* DamageCauser) override;

    // 방어력 계산 후 실제 HP를 감소시키는 함수
    UFUNCTION(BlueprintCallable)
    void TakeDamageFromEnemy(float Damage);

    // 현재 적이 사망 상태인지 확인
    bool IsDead() const;

protected:
    // 게임 시작 시 초기화
    virtual void BeginPlay() override;

    // 사망 처리
    void Die();

private:
    // 중복 사망 처리를 막기 위한 상태값
    bool bIsDead;
};

EnemyCharacter.cpp

처음에는 적이 죽으면 Destroy()로 바로 제거 하였는데,

체력이 0이 되면 이동과 충돌을 비활성화 시키고, 2초 뒤에 제거 되도록 수정하였다.

// EnemyCharacter.cpp

#include "EnemyCharacter.h"
#include "CH3_Project/ShooterGameMode.h"
#include "Kismet/GameplayStatics.h"
#include "Components/CapsuleComponent.h"
#include "GameFramework/CharacterMovementComponent.h"

// 적 기본 스탯 설정
AEnemyCharacter::AEnemyCharacter()
{
    PrimaryActorTick.bCanEverTick = false;

    MaxHP = 100.f;
    CurrentHP = MaxHP;
    Defense = 0.f;
    ScoreValue = 1;
    AttackDamage = 10.f;
    DetectionRange = 1200.f;
    AttackRange = 150.f;
    AttackCooldown = 1.5f;
    bIsDead = false;
}

// 시작 시 현재 HP를 최대 HP로 설정
void AEnemyCharacter::BeginPlay()
{
    Super::BeginPlay();

    CurrentHP = MaxHP;
}

// ApplyDamage로 들어온 데미지를 적 체력 시스템에 반영
float AEnemyCharacter::TakeDamage(
    float DamageAmount,
    FDamageEvent const& DamageEvent,
    AController* EventInstigator,
    AActor* DamageCauser)
{
    const float ActualDamage = Super::TakeDamage(
        DamageAmount,
        DamageEvent,
        EventInstigator,
        DamageCauser
    );

    // 기존 데미지 처리 함수로 연결
    TakeDamageFromEnemy(DamageAmount);

    return ActualDamage;
}

// 받은 데미지에서 방어력을 뺀 후 HP 감소
void AEnemyCharacter::TakeDamageFromEnemy(float Damage)
{
    if (bIsDead)
    {
        return;
    }

    const float FinalDamage = FMath::Max(Damage - Defense, 1.f);
    CurrentHP -= FinalDamage;

    if (CurrentHP <= 0.f)
    {
        Die();
    }
}

// 현재 사망 상태 반환
bool AEnemyCharacter::IsDead() const
{
    return bIsDead;
}

// 점수 지급 후 액터 제거
void AEnemyCharacter::Die()
{
    if (bIsDead)
    {
        return;
    }

    bIsDead = true;

    AShooterGameMode* GM = Cast<AShooterGameMode>(UGameplayStatics::GetGameMode(this));
    if (GM)
    {
        GM->AddScore(ScoreValue);
    }

    // 사망 후 이동과 충돌 비활성화
    GetCharacterMovement()->DisableMovement();
    GetCapsuleComponent()->SetCollisionEnabled(ECollisionEnabled::NoCollision);

    // 2초 후 제거
    SetLifeSpan(2.0f);
}

BTDecorator_IsInAttackRange.h

플레이어가 공격 범위 안에 있는지 확인 후,

범위 안에 있으면 BTTask_AttackTarget이 실행할 수 있게 해주는 역할이다.

// BTDecorator_IsInAttackRange.h

#pragma once

#include "CoreMinimal.h"
#include "BehaviorTree/BTDecorator.h"
#include "BTDecorator_IsInAttackRange.generated.h"

UCLASS()
class CH3_PROJECT_API UBTDecorator_IsInAttackRange : public UBTDecorator
{
    GENERATED_BODY()

public:
    UBTDecorator_IsInAttackRange();

protected:
    // Behavior Tree가 이 Decorator 조건을 검사할 때 호출
    virtual bool CalculateRawConditionValue(
        UBehaviorTreeComponent& OwnerComp,
        uint8* NodeMemory
    ) const override;
};

BTDecorator_IsInAttackRange.cpp

const float Distance = FVector::Dist(
    Enemy->GetActorLocation(),
    TargetActor->GetActorLocation()
);

return Distance <= Enemy->AttackRange;

위 코드가 true 일때만 공격 Task를 실행할 수 있다.

// BTDecorator_IsInAttackRange.cpp

#include "AI/BTDecorator_IsInAttackRange.h"
#include "AI/EnemyCharacter.h"
#include "AIController.h"
#include "BehaviorTree/BlackboardComponent.h"

// Behavior Tree에서 보일 노드 이름
UBTDecorator_IsInAttackRange::UBTDecorator_IsInAttackRange()
{
    NodeName = TEXT("Is In Attack Range");
}

// TargetActor가 적의 공격 범위 안에 있는지 확인
bool UBTDecorator_IsInAttackRange::CalculateRawConditionValue(
    UBehaviorTreeComponent& OwnerComp,
    uint8* NodeMemory
) const
{
    // 현재 Behavior Tree를 실행 중인 AIController 가져오기
    const AAIController* AIController = OwnerComp.GetAIOwner();
    if (!AIController)
    {
        return false;
    }

    // AIController가 조종 중인 Pawn을 EnemyCharacter로 변환
    const AEnemyCharacter* Enemy = Cast<AEnemyCharacter>(AIController->GetPawn());
    if (!Enemy || Enemy->IsDead())
    {
        return false;
    }

    // Blackboard에서 TargetActor 가져오기
    const UBlackboardComponent* BlackboardComp = OwnerComp.GetBlackboardComponent();
    if (!BlackboardComp)
    {
        return false;
    }

    const AActor* TargetActor = Cast<AActor>(
        BlackboardComp->GetValueAsObject(TEXT("TargetActor"))
    );

    if (!TargetActor)
    {
        return false;
    }

    // 적과 타겟 사이의 거리를 계산
    const float Distance = FVector::Dist(
        Enemy->GetActorLocation(),
        TargetActor->GetActorLocation()
    );

    // 공격 범위 안이면 true, 아니면 false
    return Distance <= Enemy->AttackRange;
}

BTTask_AttackTarget.h

이 코드는 Behavior Tree에서 공격 노드가 실행 될 때 호출되게 하였다.

// BTTask_AttackTarget.h

#pragma once

#include "CoreMinimal.h"
#include "BehaviorTree/BTTaskNode.h"
#include "BTTask_AttackTarget.generated.h"

UCLASS()
class CH3_PROJECT_API UBTTask_AttackTarget : public UBTTaskNode
{
    GENERATED_BODY()

public:
    UBTTask_AttackTarget();

protected:
    // Behavior Tree가 공격 Task를 실행할 때 호출
    virtual EBTNodeResult::Type ExecuteTask(
        UBehaviorTreeComponent& OwnerComp,
        uint8* NodeMemory
    ) override;
};

BTTask_AttackTarget.cpp

공격 Task가 실행되면 바로 데미지를 적용시켰다.

BTTask_AttackTarget 실행 > Blackboard에서 TargetActor 가져오기 > 이동 정지 >

타겟 바라보기 > ApplyDamage() 호출 > 플레이어에게 데미지 적용

// BTTask_AttackTarget.cpp

#include "AI/BTTask_AttackTarget.h"
#include "AI/EnemyCharacter.h"
#include "AIController.h"
#include "BehaviorTree/BlackboardComponent.h"
#include "Kismet/GameplayStatics.h"

// Behavior Tree에서 보일 노드 이름 설정
UBTTask_AttackTarget::UBTTask_AttackTarget()
{
    NodeName = TEXT("Attack Target");
}

// TargetActor에게 데미지를 주는 공격 Task
EBTNodeResult::Type UBTTask_AttackTarget::ExecuteTask(
    UBehaviorTreeComponent& OwnerComp,
    uint8* NodeMemory
)
{
    // 현재 Behavior Tree를 실행 중인 AIController 가져오기
    AAIController* AIController = OwnerComp.GetAIOwner();
    if (!AIController)
    {
        return EBTNodeResult::Failed;
    }

    // AIController가 조종 중인 Pawn을 EnemyCharacter로 변환
    AEnemyCharacter* Enemy = Cast<AEnemyCharacter>(AIController->GetPawn());
    if (!Enemy || Enemy->IsDead())
    {
        return EBTNodeResult::Failed;
    }

    // Blackboard에서 TargetActor 가져오기
    UBlackboardComponent* BlackboardComp = OwnerComp.GetBlackboardComponent();
    if (!BlackboardComp)
    {
        return EBTNodeResult::Failed;
    }

    AActor* TargetActor = Cast<AActor>(
        BlackboardComp->GetValueAsObject(TEXT("TargetActor"))
    );

    if (!TargetActor)
    {
        return EBTNodeResult::Failed;
    }

    // 공격 중에는 이동을 멈추고 타겟을 바라보게 함
    AIController->StopMovement();
    AIController->SetFocus(TargetActor);

    // Unreal 기본 데미지 시스템으로 플레이어에게 데미지 적용
    UGameplayStatics::ApplyDamage(
        TargetActor,
        Enemy->AttackDamage,
        AIController,
        Enemy,
        nullptr
    );

    UE_LOG(
        LogTemp,
        Warning,
        TEXT("Enemy BT Attack: %.1f Damage"),
        Enemy->AttackDamage
    );

    // Task 성공 처리
    return EBTNodeResult::Succeeded;
}

변경 후 구조

Behavior Tree를 사용하면서 구조가 아래처럼 바뀌었다.

EnemyAIController
- Behavior Tree 실행
- Blackboard에 TargetActor 설정

EnemyCharacter
- Behavior Tree asset 보유
- ApplyDamage를 TakeDamage로 받아 HP 처리
- 사망 시 이동/충돌 비활성화 후 제거

BTDecorator_IsInAttackRange
- TargetActor가 공격 범위 안에 있는지 검사

BTTask_AttackTarget
- TargetActor에게 데미지 적용

1. EnemyAIController가 EnemyCharacter를 Possess
2. EnemyCharacter에 설정된 Behavior Tree 실행
3. 플레이어 Pawn 탐색
4. Blackboard에 TargetActor 저장
5. Behavior Tree가 TargetActor를 기준으로 이동 / 공격 판단
6. BTDecorator_IsInAttackRange가 공격 거리 검사
7. 공격 범위 안이면 BTTask_AttackTarget 실행
8. ApplyDamage()로 플레이어에게 데미지 적용

이번 단계에서는 EnemyAIController가 직접 처리하던 AI 판단을 Behavior Tree와 Blackboard 기반 구조로 분리하였다.
근데 아직 TargetActor 갱신이 한 번만 실행되고, 공격 Task에서 즉시 데미지를 적용하는 구조라 이후 수정을 할 예정이다.

Unreal C++ 싱글플레이 FPS 슈터 게임 팀 프로젝트 적 AI - 1

hyunjunstar — Tue, 19 May 2026 20:50:59 +0900

AI 구조

적 AI에서 아래 기능들을 구현 하였다.

- 적 캐릭터 구현
- 체력/방어력 시스템

- 피격/사망 처리
- 플레이어 탐지
- 플레이어 추적
- 공격 범위 내 공격
- NavMesh 기반 경로 탐색
- 장애물 회피

AI 폴더 구조

구현한 코드

맨 처음 구현했던 코드는 EnemyAIController가 모든 판단을 직접 처리하게끔 구현하였다.

플레이어와의 거리를 매 프레임마다 계산 후 거리에 따라 상태를 변경하였다.

EnemyAIController.h

enum을 사용해서 적이 현재 어떤 상태인지를 구분하였다.

// EnemyAIController.h

#pragma once

#include "CoreMinimal.h"
#include "AIController.h"
#include "EnemyAIController.generated.h"

// 적 AI가 가질 수 있는 상태
UENUM(BlueprintType)
enum class EEnemyAIState : uint8
{
    Idle,   // 대기
    Chase,  // 추적
    Attack, // 공격
    Dead    // 사망
};

UCLASS()
class CH3_PROJECT_API AEnemyAIController : public AAIController
{
    GENERATED_BODY()

public:
    AEnemyAIController();

protected:
    // 적 캐릭터를 조종하기 시작할 때 호출
    virtual void OnPossess(APawn* InPawn) override;

    // 매 프레임 AI 판단을 실행
    virtual void Tick(float DeltaTime) override;

private:
    // 추적할 플레이어
    UPROPERTY()
    APawn* TargetPlayer;

    // 현재 조종 중인 적 캐릭터
    UPROPERTY()
    class AEnemyCharacter* ControlledEnemy;

    // 현재 AI 상태
    EEnemyAIState CurrentState;

    // 마지막 공격 시간
    float LastAttackTime;

    // 플레이어 찾기
    void FindPlayer();

    // AI 상태 갱신
    void UpdateAI();

    // 상태 변경
    void ChangeState(EEnemyAIState NewState);

    // 공격 가능 여부 확인
    bool CanAttack() const;

    // 공격 실행
    void PerformAttack();
};

EnemyAIController.cpp

UpdateAI()를 사용하여 매 프레임마다 플레이어와의 거리를 계산 후 거리에 따라 상태를 변경하였다.

// EnemyAIController.cpp

#include "EnemyAIController.h"
#include "EnemyCharacter.h"
#include "Kismet/GameplayStatics.h"

AEnemyAIController::AEnemyAIController()
{
    // Tick에서 매 프레임 AI를 갱신하기 위해 활성화
    PrimaryActorTick.bCanEverTick = true;

    TargetPlayer = nullptr;
    ControlledEnemy = nullptr;
    CurrentState = EEnemyAIState::Idle;
    LastAttackTime = 0.f;
}

void AEnemyAIController::OnPossess(APawn* InPawn)
{
    Super::OnPossess(InPawn);

    // 조종할 Pawn을 EnemyCharacter로 캐스팅
    ControlledEnemy = Cast<AEnemyCharacter>(InPawn);

    // 플레이어 참조 저장
    FindPlayer();
}

void AEnemyAIController::Tick(float DeltaTime)
{
    Super::Tick(DeltaTime);

    // 매 프레임 AI 판단 실행
    UpdateAI();
}

void AEnemyAIController::FindPlayer()
{
    // 0번 플레이어 Pawn 찾기
    TargetPlayer = UGameplayStatics::GetPlayerPawn(this, 0);
}

void AEnemyAIController::UpdateAI()
{
    // 조종 중인 적이 없으면 중단
    if (!ControlledEnemy)
    {
        return;
    }

    // 플레이어가 없으면 다시 찾기
    if (!TargetPlayer)
    {
        FindPlayer();
        return;
    }

    // 적이 죽었으면 Dead 상태로 변경
    if (ControlledEnemy->IsDead())
    {
        ChangeState(EEnemyAIState::Dead);
        StopMovement();
        return;
    }

    // 적과 플레이어 사이의 거리 계산
    const float Distance = FVector::Dist(
        ControlledEnemy->GetActorLocation(),
        TargetPlayer->GetActorLocation()
    );

    // 공격 범위 안이면 공격
    if (Distance <= ControlledEnemy->AttackRange)
    {
        ChangeState(EEnemyAIState::Attack);
        StopMovement();
        PerformAttack();
    }
    // 감지 범위 안이면 추적
    else if (Distance <= ControlledEnemy->DetectionRange)
    {
        ChangeState(EEnemyAIState::Chase);
        MoveToActor(TargetPlayer);
    }
    // 감지 범위 밖이면 대기
    else
    {
        ChangeState(EEnemyAIState::Idle);
        StopMovement();
    }
}

void AEnemyAIController::ChangeState(EEnemyAIState NewState)
{
    // 같은 상태면 변경하지 않음
    if (CurrentState == NewState)
    {
        return;
    }

    CurrentState = NewState;
}

bool AEnemyAIController::CanAttack() const
{
    if (!ControlledEnemy || !GetWorld())
    {
        return false;
    }

    // 마지막 공격 이후 쿨타임이 지났는지 확인
    const float CurrentTime = GetWorld()->GetTimeSeconds();
    return CurrentTime - LastAttackTime >= ControlledEnemy->AttackCooldown;
}

void AEnemyAIController::PerformAttack()
{
    // 공격 쿨타임이 안 지났으면 공격하지 않음
    if (!CanAttack() || !GetWorld())
    {
        return;
    }

    // 마지막 공격 시간 갱신
    LastAttackTime = GetWorld()->GetTimeSeconds();

    // 초기 버전에서는 공격 로그만 출력
    UE_LOG(LogTemp, Warning, TEXT("Enemy Attack"));
}

EnemyCharacter.h

적 캐릭터의 기본 스탯 값들을 설정하였다.

// EnemyCharacter.h

#pragma once

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

UCLASS()
class CH3_PROJECT_API AEnemyCharacter : public ACharacter
{
    GENERATED_BODY()

public:
    AEnemyCharacter();

    // 최대 체력
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Stat")
    float MaxHP;

    // 현재 체력
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Enemy|Stat")
    float CurrentHP;

    // 방어력
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Stat")
    float Defense;

    // 처치 시 지급 점수
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Reward")
    int32 ScoreValue;

    // 공격 데미지
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Attack")
    float AttackDamage;

    // 플레이어 감지 범위
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|AI")
    float DetectionRange;

    // 공격 가능 범위
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|AI")
    float AttackRange;

    // 공격 쿨타임
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Enemy|Attack")
    float AttackCooldown;

    // 데미지 처리 함수
    UFUNCTION(BlueprintCallable)
    void TakeDamageFromEnemy(float Damage);

    // 사망 여부 반환
    bool IsDead() const;

protected:
    // 게임 시작 시 호출
    virtual void BeginPlay() override;

    // 사망 처리
    void Die();

private:
    // 중복 사망 처리를 막기 위한 변수
    bool bIsDead;
};

EnemyCharacter.cpp

적 캐릭터의 기본 스탯을 초기화 및 각종 상태 처리 구현,

적 캐릭터 사망시 GameMode에 점수를 지급 한 후 Destroy()로 제거 하였다.

// EnemyCharacter.cpp

#include "EnemyCharacter.h"
#include "CH3_Project/ShooterGameMode.h"
#include "Kismet/GameplayStatics.h"

AEnemyCharacter::AEnemyCharacter()
{
    // 적 캐릭터 자체는 Tick을 사용하지 않음
    PrimaryActorTick.bCanEverTick = false;

    // 기본 스탯 설정
    MaxHP = 100.f;
    CurrentHP = MaxHP;
    Defense = 0.f;
    ScoreValue = 1;
    AttackDamage = 10.f;
    DetectionRange = 1200.f;
    AttackRange = 150.f;
    AttackCooldown = 1.5f;
    bIsDead = false;
}

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

    // 게임 시작 시 체력을 최대 체력으로 초기화
    CurrentHP = MaxHP;
}

void AEnemyCharacter::TakeDamageFromEnemy(float Damage)
{
    // 이미 죽었으면 데미지 무시
    if (bIsDead)
    {
        return;
    }

    // 방어력을 적용한 최종 데미지 계산
    const float FinalDamage = FMath::Max(Damage - Defense, 1.f);
    CurrentHP -= FinalDamage;

    // 체력이 0 이하가 되면 사망 처리
    if (CurrentHP <= 0.f)
    {
        Die();
    }
}

bool AEnemyCharacter::IsDead() const
{
    return bIsDead;
}

void AEnemyCharacter::Die()
{
    // 중복 사망 처리 방지
    if (bIsDead)
    {
        return;
    }

    bIsDead = true;

    // GameMode에 점수 추가
    AShooterGameMode* GM = Cast<AShooterGameMode>(UGameplayStatics::GetGameMode(this));
    if (GM)
    {
        GM->AddScore(ScoreValue);
    }

    // 초기 버전에서는 죽으면 바로 제거
    Destroy();
}

CH3_Project.Build.cs

AI 사용을 위해 AIModule, NavigationSystem, GameplayTasks 추가

// CH3_Project.Build.cs
// Copyright Epic Games, Inc. All Rights Reserved.

using UnrealBuildTool;

public class CH3_Project : ModuleRules
{
	public CH3_Project(ReadOnlyTargetRules Target) : base(Target)
	{
		PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
	
		PublicDependencyModuleNames.AddRange(new string[] { "Core", 
			"CoreUObject", 
			"Engine", 
			"InputCore", 
			"EnhancedInput",
			"UMG",
			"AIModule",
            "NavigationSystem",
            "GameplayTasks" });

		PrivateDependencyModuleNames.AddRange(new string[] {  });
        PublicIncludePaths.AddRange(new string[] {"CH3_Project"});
        // 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
    }
}

정리하자면 위 코드들은 아래처럼 설계 되었다.

1. EnemyAIController가 EnemyCharacter를 Possess
2. 플레이어 Pawn 찾기
3. Tick에서 매 프레임 UpdateAI 실행
4. 플레이어와 적 사이 거리 계산
5. 공격 범위 안이면 Attack
6. 감지 범위 안이면 Chase
7. 감지 범위 밖이면 Idle
8. 적 체력이 0 이하가 되면 Dead
9. 점수 지급 후 Destroy

EnemyAIController의 역할

플레이어 탐색 > 거리 계산 > 상태 변경 > 이동 > 공격 쿨타임 관리 > 공격

EnemyCharacter

기본 스탯 관리 > 방어력 적용 > 공격 및 감지 범위 값 적용 > 사망 처리 > 점수 지급

이렇게 초기 구현은 EnemyAIController 중심으로 구현 하였다.

Unreal C++ 게임 루프 및 UI 설계 후 코인 획득 게임 구현 트러블슈팅

hyunjunstar — Thu, 30 Apr 2026 22:10:51 +0900

1. 맵 이름 변경 후 Start 버튼이 동작하지 않는 문제

처음에는 기존 맵 이름이 BasicLevel이었는데, 과제 진행 중 맵 이름을 Level1로 변경하였다.
하지만 게임 시작 버튼을 눌러도 다음 레벨로 이동하지 않고, 로그에 Invalid URL 관련 오류가 발생하였다.

원인을 확인해보니 StartGame() 함수와 레벨 이동 배열 쪽에서 아직 이전 맵 이름을 참조하고 있었다.

// SpartaPlayerController

UGameplayStatics::OpenLevel(GetWorld(), FName("BasicLevel")); 
// 위 코드에서 맵 이름을 Level1로 변경했으니 코드에서도 동일하게 수정해주었다.

UGameplayStatics::OpenLevel(GetWorld(), FName("Level1"));

// 그리고 GameState에서 사용하는 LevelMapNames 배열도 에디터에서 Level1, Level2, Level3로 다시 확인해주었다.

이 문제를 통해 맵 이름을 변경할 때는 에디터의 맵 파일명뿐 아니라,

코드와 블루프린트에서 참조하는 이름도 같이 확인해야 한다는 것을 알게 되었다.

2. 지뢰 아이템이 바로 사라져서 폭발 처리가 되지 않는 문제

처음에는 MineItem에서도 부모 클래스인 BaseItem의 ActivateItem()을 그대로 사용하려고 했다.
하지만 BaseItem::ActivateItem() 안에서는 파티클과 사운드를 재생한 뒤 바로 DestroyItem()을 호출하고 있었다.

// BaseItem.cpp

void ABaseItem::ActivateItem(AActor* Activator)
{
    // 파티클, 사운드 처리

    DestroyItem();
}

이 구조를 지뢰 아이템에 그대로 사용하니, 지뢰가 폭발 타이머를 기다리기 전에 액터가 먼저 제거되는 문제가 생겼다.

그래서 MineItem에서는 Super::ActivateItem()을 호출하지 않고, 지뢰 전용 로직을 따로 구현하였다.

// MineItem.cpp

void AMineItem::ActivateItem(AActor* Activator)
{
    if (bHasExploded) return;

    bHasExploded = true;

    if (Collision)
    {
        Collision->SetCollisionEnabled(ECollisionEnabled::NoCollision);
    }

    GetWorld()->GetTimerManager().SetTimer(
        ExplosionTimerHandle,
        this,
        &AMineItem::Explode,
        ExplosionDelay,
        false
    );
}

이렇게 수정하니 지뢰가 플레이어와 충돌하면 바로 사라지지 않고, 일정 시간이 지난 뒤 정상적으로 폭발하도록 되었다.

3. 웨이브가 넘어갈 때 파티클이 남아있는 문제

아이템 획득이나 지뢰 폭발 시 파티클을 생성했는데, 웨이브가 끝나거나 레벨이 바뀌어도 파티클이 남아있는 문제가 있었다.

처음에는 각 아이템에서 타이머로 파티클을 제거하려고 했지만,

웨이브나 레벨 전환 시점과 파티클 제거 타이밍이 겹치면서 에디터가 강제로 종료되면서 오류가 발생하며 관리가 복잡해졌다.

그래서 생성된 파티클을 GameState에 등록해두고, 웨이브나 레벨이 끝날 때 한 번에 정리하는 방식으로 수정하였다.

// SpartaGameState.cpp

void ASpartaGameState::RegisterParticle(UParticleSystemComponent* Particle)
{
    if (Particle)
    {
        ActiveParticles.Add(Particle);
    }
}

void ASpartaGameState::ClearActiveParticles()
{
    for (TWeakObjectPtr<UParticleSystemComponent>& WeakParticle : ActiveParticles)
    {
        if (WeakParticle.IsValid())
        {
            WeakParticle->DeactivateSystem();
            WeakParticle->DestroyComponent();
        }
    }

    ActiveParticles.Empty();
}

그리고 EndWave()와 EndLevel()에서 ClearActiveParticles()를 호출하여 남아있는 파티클을 정리하였다.

// SpartaGameState.cpp

void ASpartaGameState::EndWave()
{
    ClearActiveParticles();

    GetWorldTimerManager().ClearTimer(LevelTimerHandle);
}

이렇게 수정하니 웨이브 전환 시 화면에 남아있던 파티클들이 깔끔하게 제거되었다.

마무리

이번 과제에서는 단순히 아이템을 스폰하고 획득하는 기능을 넘어서,

게임 전체 흐름을 GameState에서 관리하는 구조를 만들어보았다.

레벨과 웨이브 진행, 제한 시간, 코인 획득 조건, 다음 레벨 이동, 게임오버 처리까지 하나의 흐름으로 연결하면서 게임 루프가 어떻게 구성되는지 더 이해할 수 있었다.

또한 SpawnVolume과 데이터테이블을 활용해 아이템 스폰 확률을 관리하고, 레벨이 올라갈수록 지뢰와 회복 아이템의 난이도가 달라지도록 구현하면서 데이터 기반 설계의 편리함도 느낄 수 있었다.

UI 부분에서는 처음에는 GameState에서 직접 HUD 텍스트를 수정했지만,

점점 코드가 복잡해져서 SpartaHUDWidget과 SpartaMainMenuWidget으로 분리하였다.
덕분에 게임 진행 로직과 UI 표시 로직을 나누어 관리할 수 있었고, 코드 구조도 더 깔끔해졌다.

작업 중 맵 이름 변경으로 인한 레벨 이동 오류, 지뢰 아이템이 바로 사라지는 문제, 웨이브 전환 시 파티클이 남아 충돌하는 문제 등이 있었지만, 하나씩 원인을 찾아 수정하면서 언리얼에서 액터의 생명주기, 타이머, 위젯 관리가 얼마나 중요한지 알게 되었다.

이번 과제를 통해 GameState, PlayerController, Widget, DataTable, Timer가 서로 어떻게 연결되는지 직접 경험할 수 있었고,

이전보다 게임 구조를 조금 더 이해할 수 있게 된 것 같다.

Unreal C++ 게임 루프 및 UI 설계 후 코인 획득 게임 구현

hyunjunstar — Wed, 29 Apr 2026 23:22:52 +0900

오늘은 Unreal C++ 과제로 기존 프로젝트에 게임 루프와 UI를 재설계 하는 작업을 진행했다.

GameState에서 레벨과 웨이브 흐름을 관리,

SpawnVolume과 데이터 테이블을 활용해서 아이템들이 확률 기반으로 스폰 되도록 구현 하였으며,

HUD와 메인 메뉴를 별도 위젯 클래스로 분리하여 점수, 시간, 레벨, 웨이브, 게임오버 메뉴 등을 구현하였다.

게임 루프

- GameState에서 레벨과 웨이브 진행 관리
- 각 레벨마다 3개의 웨이브 진행
- 웨이브별 제한 시간과 아이템 스폰 수 설정
- 시간이 끝나거나 코인을 모두 획득하면 다음 웨이브로 이동
- 모든 웨이브가 끝나면 다음 레벨로 이동
- 마지막 레벨 종료 시 게임오버 메뉴 출력

아이템 스폰

- SpawnVolume을 활용한 랜덤 위치 스폰
- 데이터테이블 기반 아이템 확률 관리
- 코인, 회복 아이템, 지뢰 아이템 스폰
- 스폰된 아이템에 현재 레벨 난이도 적용

아이템

- BaseItem에서 공통 충돌, 파티클, 사운드 처리
- 코인 아이템 획득 시 점수 증가
- 회복 아이템은 레벨이 올라갈수록 회복량 감소
- 지뢰 아이템은 레벨이 올라갈수록 폭발 시간 감소 및 데미지 증가
- 웨이브 전환 시 남은 파티클 정리

UI

- SpartaHUDWidget으로 HUD 관리
- 점수, 시간, 레벨, 웨이브 표시
- 캐릭터 머리 위에 체력 텍스트와 HP바 표시
- SpartaMainMenuWidget으로 메인 메뉴와 게임오버 메뉴 관리
- 시작, 재시작, 메인 메뉴로 돌아가기, 종료 버튼 기능 연결

1. GameState - 웨이브, 레벨 시작 종료 및 파티클 정리

// SpartaGameState.h

#pragma once

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

class UParticleSystemComponent; // 파티클 컴포넌트 클래스 전방 선언

UCLASS()
class SPARTA_API ASpartaGameState : public AGameState
{
    GENERATED_BODY()

public:
    ASpartaGameState();

    virtual void BeginPlay() override;

    // 현재 점수 반환
    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();

    // HUD 갱신
    void UpdateHUD();

    // 웨이브 시작
    void StartWave();

    // 웨이브 시간 종료 처리
    void OnWaveTimeUp();

    // 웨이브 종료 및 다음 웨이브 이동
    void EndWave();

    // 파티클 등록
    void RegisterParticle(UParticleSystemComponent* Particle);

public:
    // 현재 레벨 점수
    UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category = "Score")
    int32 Score;

    // 현재 웨이브에서 생성된 코인 수
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Coin")
    int32 SpawnedCoinCount;

    // 현재 웨이브에서 획득한 코인 수
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Coin")
    int32 CollectedCoinCount;

    // 현재 웨이브 제한 시간
    UPROPERTY(EditAnywhere, 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;

    // 현재 웨이브 인덱스
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Wave")
    int32 CurrentWaveIndex;

    // 한 레벨의 최대 웨이브 수
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Wave")
    int32 MaxWaves;

protected:
    // 현재 웨이브에서 스폰할 아이템 수
    int32 ItemToSpawn;

    // 웨이브 제한 시간 타이머
    FTimerHandle LevelTimerHandle;

    // HUD 갱신 타이머
    FTimerHandle HUDUpdateTimerHandle;

    // 생성된 파티클 목록을 가져옴
    TArray<TWeakObjectPtr<UParticleSystemComponent>> ActiveParticles;

    // 등록된 파티클 제거
    void ClearActiveParticles();

    // 레벨에 따라 아이템 난이도 조절
    void ApplyItemDifficulty(AActor* SpawnedActor);
};

// SpartaGameState.cpp

#include "SpartaGameState.h"
#include "SpartaGameInstance.h"
#include "SpartaPlayerController.h"
#include "SpawnVolume.h"
#include "BaseItem.h"
#include "CoinItem.h"
#include "MineItem.h"
#include "HealingItem.h"
#include "SpartaHUDWidget.h"
#include "SpartaCharacter.h"
#include "Kismet/GameplayStatics.h"
#include "Particles/ParticleSystemComponent.h"

// 게임 정보
ASpartaGameState::ASpartaGameState()
{
    Score = 0;
    
    LevelDuration = 0;
    ItemToSpawn = 0;

    CurrentWaveIndex = 0;
    MaxWaves = 3;
    
    CurrentLevelIndex = 0;
    MaxLevels = 3;
}

// ======================================== // 

// 게임 시작 시 레벨 시작 및 HUD 갱신 타이머 실행
void ASpartaGameState::BeginPlay()
{
    Super::BeginPlay();

    // 현재 레벨 시작
    StartLevel();

    // HUD를 0.1초마다 갱신
    GetWorldTimerManager().SetTimer(
        HUDUpdateTimerHandle,
        this,
        &ASpartaGameState::UpdateHUD,
        0.1f,
        true
    );
}

// ======================================== // 

// 현재 점수 반환
int32 ASpartaGameState::GetScore() const
{
    return Score;
}

// ======================================== // 

// GameInstance에 점수 누적
void ASpartaGameState::AddScore(int32 Amount)
{
    // 현재 GameInstance 정보 가져오기
    if (UGameInstance* GameInstance = GetGameInstance())
    {
        // 프로젝트 전용 GameInstance로 캐스팅
        if (USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(GameInstance))
        {
            // 총점수에 점수 누적
            SpartaGameInstance->AddToScore(Amount);
        }
    }
}

// ======================================== // 

// 레벨 시작 HUD 표시, 현재 레벨 인덱스 불러오기, 1웨이브 시작
void ASpartaGameState::StartLevel()
{
    // 플레이어 컨트롤러 가져오기
    if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
    {
        // 프로젝트 전용 PlayerController로 캐스팅
        if (ASpartaPlayerController* SpartaPlayerController = Cast<ASpartaPlayerController>(PlayerController))
        {
            // 게임 HUD 표시
            SpartaPlayerController->ShowGameHUD();
        }
    }

    // GameInstance에서 현재 레벨 인덱스 가져오기
    if (UGameInstance* GameInstance = GetGameInstance())
    {
        if (USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(GameInstance))
        {
            CurrentLevelIndex = SpartaGameInstance->CurrentLevelIndex;
        }
    }

    // 레벨 시작 시 코인 카운트 초기화
    SpawnedCoinCount = 0;
    CollectedCoinCount = 0;

    // 1웨이브부터 시작
    CurrentWaveIndex = 1;

    // 첫 웨이브 시작
    StartWave();
}

// ======================================== // 

// 웨이브 시작: 웨이브별 시간과 아이템 수 설정 후 아이템 스폰
void ASpartaGameState::StartWave()
{
    // 월드에 배치된 SpawnVolume 검색
    TArray<AActor*> FoundVolumes;
    UGameplayStatics::GetAllActorsOfClass(GetWorld(), ASpawnVolume::StaticClass(), FoundVolumes);

    // 웨이브마다 코인 카운트 초기화
    SpawnedCoinCount = 0;
    CollectedCoinCount = 0;

    // 1웨이브 설정
    if (CurrentWaveIndex == 1)
    {
        // 화면에 웨이브 시작 메시지 출력
        if (GEngine)
        {
            GEngine->AddOnScreenDebugMessage(
                -1,
                2.0f,
                FColor::Green,
                FString::Printf(TEXT("Wave %d 시작"), CurrentWaveIndex)
            );
        }

        // 제한 시간, 아이템 개수 설정
        LevelDuration = 40.0f;
        ItemToSpawn = 40;

        // 설정된 개수만큼 아이템 스폰
        for (int32 i = 0; i < ItemToSpawn; i++)
        {
            // SpawnVolume이 존재하는지 확인
            if (FoundVolumes.Num() > 0)
            {
                // 첫 번째 SpawnVolume 사용
                ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
                if (SpawnVolume)
                {
                    // 랜덤 아이템 스폰
                    AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();

                    // 스폰된 아이템에 레벨 난이도 적용
                    ApplyItemDifficulty(SpawnedActor);

                    // 스폰된 아이템이 코인이면 코인 수 증가
                    if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
                    {
                        SpawnedCoinCount++;
                    }
                }
            }
        }
    }

    // 2웨이브 설정
    else if (CurrentWaveIndex == 2)
    {
        if (GEngine)
        {
            GEngine->AddOnScreenDebugMessage(
                -1,
                2.0f,
                FColor::Green,
                FString::Printf(TEXT("Wave %d 시작"), CurrentWaveIndex)
            );
        }

        LevelDuration = 35.0f;
        ItemToSpawn = 45;

        for (int32 i = 0; i < ItemToSpawn; i++)
        {
            if (FoundVolumes.Num() > 0)
            {
                ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
                if (SpawnVolume)
                {
                    AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();

                    ApplyItemDifficulty(SpawnedActor);

                    if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
                    {
                        SpawnedCoinCount++;
                    }
                }
            }
        }
    }

    // 3웨이브 설정
    else if (CurrentWaveIndex == 3)
    {
        if (GEngine)
        {
            GEngine->AddOnScreenDebugMessage(
                -1,
                2.0f,
                FColor::Green,
                FString::Printf(TEXT("Wave %d 시작"), CurrentWaveIndex)
            );
        }

        LevelDuration = 30.0f;
        ItemToSpawn = 50;

        for (int32 i = 0; i < ItemToSpawn; i++)
        {
            if (FoundVolumes.Num() > 0)
            {
                ASpawnVolume* SpawnVolume = Cast<ASpawnVolume>(FoundVolumes[0]);
                if (SpawnVolume)
                {
                    AActor* SpawnedActor = SpawnVolume->SpawnRandomItem();

                    ApplyItemDifficulty(SpawnedActor);

                    if (SpawnedActor && SpawnedActor->IsA(ACoinItem::StaticClass()))
                    {
                        SpawnedCoinCount++;
                    }
                }
            }
        }
    }

    // 웨이브 제한 시간 타이머 설정
    GetWorldTimerManager().SetTimer(
        LevelTimerHandle,
        this,
        &ASpartaGameState::OnWaveTimeUp,
        LevelDuration,
        false
    );
}

// ======================================== // 

// 웨이브 시간이 끝났을 때 호출
void ASpartaGameState::OnWaveTimeUp()
{
    // 웨이브 종료
    EndWave();
}

// ======================================== // 

// 레벨 시간이 끝났을 때 호출
void ASpartaGameState::OnLevelTimeUp()
{
    // 레벨 종료
    EndLevel();
}

// ======================================== // 

// 코인 획득 시 획득 수를 증가시키고, 모두 획득하면 웨이브 종료
void ASpartaGameState::OnCoinCollected()
{
    // 획득한 코인 수 증가
    CollectedCoinCount++;

    // 현재 코인 획득 상황 로그 출력
    UE_LOG(LogTemp, Warning,
        TEXT("획득한 코인 : %d / %d"),
        CollectedCoinCount,
        SpawnedCoinCount
    );

    // 모든 코인을 획득하면 웨이브 종료
    if (SpawnedCoinCount > 0 && CollectedCoinCount >= SpawnedCoinCount)
    {
        EndWave();
    }
}

// ======================================== // 

// 웨이브 종료 남은 파티클/아이템 정리 후 다음 웨이브 또는 레벨 종료
void ASpartaGameState::EndWave()
{
    // 남아있는 파티클 제거
    ClearActiveParticles();

    // 웨이브 타이머 정리
    GetWorldTimerManager().ClearTimer(LevelTimerHandle);

    // 월드에 남아있는 모든 BaseItem 검색
    TArray<AActor*> Actors;
    UGameplayStatics::GetAllActorsOfClass(GetWorld(), ABaseItem::StaticClass(), Actors);

    // 남은 아이템 제거
    for (AActor* Item : Actors)
    {
        if (ABaseItem* BaseItem = Cast<ABaseItem>(Item))
        {
            BaseItem->Destroy();
        }
    }

    // 다음 웨이브로 이동
    CurrentWaveIndex++;

    // 남은 웨이브가 있으면 다음 웨이브 시작
    if (CurrentWaveIndex <= MaxWaves)
    {
        StartWave();
    }
    // 모든 웨이브가 끝나면 레벨 종료
    else
    {
        EndLevel();
    }

}

// ======================================== // 

// 레벨 종료 남은 오브젝트 정리 후 다음 레벨 이동 또는 게임오버
void ASpartaGameState::EndLevel()
{
    // 남아있는 파티클 제거
    ClearActiveParticles();

    // 웨이브 타이머 정리
    GetWorldTimerManager().ClearTimer(LevelTimerHandle);

    // 월드에 남아있는 모든 BaseItem 검색
    TArray<AActor*> Actors;
    UGameplayStatics::GetAllActorsOfClass(GetWorld(), ABaseItem::StaticClass(), Actors);

    // 남은 아이템 제거
    for (AActor* Item : Actors)
    {
        if (ABaseItem* BaseItem = Cast<ABaseItem>(Item))
        {
            // 아이템 내부 타이머 정리
            BaseItem->ClearTimer();

            // 아이템 제거
            BaseItem->Destroy();
        }
    }

    // GameInstance 가져오기
    if (UGameInstance* GameInstance = GetGameInstance())
    {
        // 프로젝트 전용 GameInstance로 캐스팅
        USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(GameInstance);
        if (SpartaGameInstance)
        {
            // 현재 레벨 점수 반영
            AddScore(Score);

            // 다음 레벨 인덱스로 증가
            CurrentLevelIndex++;
            SpartaGameInstance->CurrentLevelIndex = CurrentLevelIndex;

            // 최대 레벨을 넘으면 게임오버
            if (CurrentLevelIndex >= MaxLevels)
            {
                OnGameOver();
                return;
            }

            // 다음 레벨 맵이 존재하면 이동
            if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
            {
                UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
            }
            // 맵 이름이 없으면 게임오버
            else
            {
                OnGameOver();
            }
        }
    }
}

// ======================================== // 

// 생성된 파티클을 GameState에 등록
void ASpartaGameState::RegisterParticle(UParticleSystemComponent* Particle)
{
    // 유효한 파티클만 배열에 저장
    if (Particle)
    {
        ActiveParticles.Add(Particle);
    }
}

// ======================================== // 

// 웨이브, 레벨 전환 시 남아있는 파티클 제거
void ASpartaGameState::ClearActiveParticles()
{
    // 등록된 파티클 순회
    for (TWeakObjectPtr<UParticleSystemComponent>& WeakParticle : ActiveParticles)
    {
        // 아직 살아있는 파티클만 제거
        if (WeakParticle.IsValid())
        {
            WeakParticle->DeactivateSystem();
            WeakParticle->DestroyComponent();
        }
    }

    // 배열 비우기
    ActiveParticles.Empty();
}

// ======================================== // 

// 레벨에 따라 아이템 난이도 조정
void ASpartaGameState::ApplyItemDifficulty(AActor* SpawnedActor)
{
    // 스폰 실패 시 종료
    if (!SpawnedActor)
    {
        return;
    }

    // 지뢰 아이템이면 폭발 시간/데미지 조정
    if (AMineItem* MineItem = Cast<AMineItem>(SpawnedActor))
    {
        MineItem->ApplyLevelDifficulty(CurrentLevelIndex);
    }

    // 회복 아이템이면 회복량 조정
    if (AHealingItem* HealingItem = Cast<AHealingItem>(SpawnedActor))
    {
        HealingItem->ApplyLevelDifficulty(CurrentLevelIndex);
    }
}

// ======================================== // 

// 게임 종료 후 메뉴 표시
void ASpartaGameState::OnGameOver()
{
    // 첫 번째 플레이어 컨트롤러 가져오기
    if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
    {
        // 프로젝트 전용 PlayerController로 캐스팅
        if (ASpartaPlayerController* SpartaPlayerController = Cast<ASpartaPlayerController>(PlayerController))
        {
            // 게임 일시정지
            SpartaPlayerController->SetPause(true);

            // 게임오버 메뉴 표시
            SpartaPlayerController->ShowMainMenu(true);
        }
    }

}

// ======================================== // 

// HUD에 시간, 점수, 레벨, 웨이브, 체력 정보 전달
void ASpartaGameState::UpdateHUD()
{   
    // 첫 번째 플레이어 컨트롤러 가져오기
    APlayerController* PlayerController = GetWorld()->GetFirstPlayerController();

    // 프로젝트 전용 PlayerController로 캐스팅
    ASpartaPlayerController* SpartaPlayerController = Cast<ASpartaPlayerController>(PlayerController);

    // 캐스팅 실패 시 종료
    if (!SpartaPlayerController)
    {
        return;
    }

    // HUD 위젯 가져오기
    USpartaHUDWidget* HUDWidget = SpartaPlayerController->GetHUDWidget();

    // HUD가 없으면 종료
    if (!HUDWidget)
    {
        return;
    }

    // 총점 기본값
    int32 TotalScore = 0;

    // GameInstance에서 총점 가져오기
    if (USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(GetGameInstance()))
    {
        TotalScore = SpartaGameInstance->TotalScore;
    }

    // 남은 시간 계산
    float RemainingTime = GetWorldTimerManager().GetTimerRemaining(LevelTimerHandle);
    RemainingTime = FMath::Max(0.0f, RemainingTime);

    // 체력 기본값
    float Health = 0.0f;
    float MaxHealth = 100.0f;

    // 플레이어 캐릭터 가져오기
    if (ASpartaCharacter* PlayerCharacter = Cast<ASpartaCharacter>(UGameplayStatics::GetPlayerCharacter(GetWorld(), 0)))
    {
        Health = PlayerCharacter->GetHealth();
        MaxHealth = PlayerCharacter->GetMaxHealth();
    }

    // HUD 위젯에 표시할 값 전달
    HUDWidget->UpdateHUD(
        RemainingTime,
        TotalScore,
        CurrentLevelIndex,
        CurrentWaveIndex,
        Health,
        MaxHealth
    );
}

2. SpawnVolume - 데이터테이블 기반 아이템 랜덤 스폰

// SpawnVolume.h

#pragma once

#include "CoreMinimal.h"
// 아이템 데이터 테이블 구조체 인클루드
#include "ItemSpawnRow.h"
#include "GameFramework/Actor.h"
#include "SpawnVolume.generated.h"

class UBoxComponent;    // 박스 충돌 컴포넌트 클래스 전방 선언

UCLASS()
class SPARTA_API ASpawnVolume : public AActor
{
	GENERATED_BODY()
	
public:	
	ASpawnVolume();

    // 스폰 볼륨의 루트 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Spawning")
    USceneComponent* SceneComp;

    // 아이템이 생성될 범위를 나타내는 박스 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Spawning")
    UBoxComponent* SpawningBox;

    // 아이템 클래스와 스폰 확률을 저장한 데이터 테이블
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Spawning")
    UDataTable* ItemDataTable;

    // 데이터 테이블의 확률을 기준으로 랜덤 아이템을 스폰
    UFUNCTION(BlueprintCallable, Category = "Spawning")
    AActor* SpawnRandomItem();

    // 데이터 테이블에서 확률 계산으로 스폰할 아이템 Row 선택
    FItemSpawnRow* GetRandomItem() const;

    // 전달받은 아이템 클래스를 실제 월드에 생성
    AActor* SpawnItem(TSubclassOf<AActor> ItemClass);

    // SpawningBox 내부의 랜덤 위치 반환
    FVector GetRandomPointInVolume() const;
};

// SpawnVolume.cpp

#include "SpawnVolume.h"
#include "Components/BoxComponent.h"

// 스폰 볼륨 컴포넌트 초기화
ASpawnVolume::ASpawnVolume()
{
    // 매 프레임 Tick이 필요 없으므로 비활성화
    PrimaryActorTick.bCanEverTick = false;

    // 루트 컴포넌트 생성
    SceneComp = CreateDefaultSubobject<USceneComponent>(TEXT("SceneComponent"));
    SetRootComponent(SceneComp);

    // 아이템 스폰 범위로 사용할 박스 컴포넌트 생성
    SpawningBox = CreateDefaultSubobject<UBoxComponent>(TEXT("Spawning Box"));
    SpawningBox->SetupAttachment(SceneComp);

    // 데이터 테이블 기본값 초기화
    ItemDataTable = nullptr;
}

// ======================================== //

// 데이터 테이블 확률에 따라 랜덤 아이템 스폰
AActor* ASpawnVolume::SpawnRandomItem()
{
    // 확률 계산으로 선택된 데이터 Row 가져오기
    if (FItemSpawnRow* SelectedRow = GetRandomItem())
    {
        // Row에 저장된 아이템 클래스 가져오기
        if (UClass* ActualClass = SelectedRow->ItemClass.Get())
        {
            // 선택된 아이템을 실제로 월드에 스폰
            return SpawnItem(ActualClass);
        }
    }

    // 실패 시 nullptr 반환
    return nullptr;
}

// ======================================== //

// 데이터 테이블에서 확률 기반으로 아이템 Row 선택
FItemSpawnRow* ASpawnVolume::GetRandomItem() const
{
    // DataTable이 있어야 실행(없으면 바로 종료)
    if (!ItemDataTable) return nullptr;

    // 모든 Row를 저장할 배열
    TArray<FItemSpawnRow*> AllRows;

    // GetAllRows에 필요한 컨텍스트 문자열
    static const FString ContextString(TEXT("ItemSpawnContext"));

    // 데이터 테이블의 모든 Row 가져오기
    ItemDataTable->GetAllRows(ContextString, AllRows);

    // 데이터가 없으면 종료
    if (AllRows.IsEmpty()) return nullptr;

    // 전체 확률 합산용 변수
    float TotalChance = 0.0f;

    // 모든 아이템의 스폰 확률 합산
    for (const FItemSpawnRow* Row : AllRows)
    {
        // 아이템 목록이 유효한지 확인
        if (Row)
        {
            // 아이템들의 확률을 더해서 총합 계산
            TotalChance += Row->Spawnchance;
        }
    }

    // 0 ~ 전체 확률 사이 랜덤값 생성
    const float RandValue = FMath::FRandRange(0.0f, TotalChance);

    // 누적 확률 계산용 변수
    float AccumulateChance = 0.0f;

    // 누적 확률 방식으로 선택된 Row 찾기
    for (FItemSpawnRow* Row : AllRows)
    {
        // 현재 Row의 확률을 누적
        AccumulateChance += Row->Spawnchance;

        // 랜덤 값이 현재 누적 확률 구간에 포함되면 해당 아이템 선택
        if (RandValue <= AccumulateChance)
        {
            // 선택된 아이템을 반환
            return Row;
        }
    }

    // 선택 실패 시 nullptr 반환
    return nullptr;
}

// ======================================== //

// SpawningBox 내부의 랜덤 위치 반환
FVector ASpawnVolume::GetRandomPointInVolume() const
{
    // 박스의 실제 크기 가져오기
    FVector BoxExtent = SpawningBox->GetScaledBoxExtent();

    // 박스의 월드 위치 가져오기
    FVector BoxOrigin = SpawningBox->GetComponentLocation();

    // 박스 범위 안에서 랜덤 좌표 생성
    return BoxOrigin + FVector(
        FMath::FRandRange(-BoxExtent.X, BoxExtent.X),
        FMath::FRandRange(-BoxExtent.Y, BoxExtent.Y),
        FMath::FRandRange(-BoxExtent.Z, BoxExtent.Z)
    );
}

// ======================================== //

// 전달받은 아이템 클래스를 월드에 스폰
AActor* ASpawnVolume::SpawnItem(TSubclassOf<AActor> ItemClass)
{
    // 클래스가 없으면 스폰하지 않음
    if (!ItemClass) return nullptr;

    // 랜덤 위치에 아이템 액터 생성
    AActor* SpawnedActor = GetWorld()->SpawnActor<AActor>(
        ItemClass,
        GetRandomPointInVolume(),
        FRotator::ZeroRotator
    );

    // 생성된 액터 반환
    return SpawnedActor;
}

3. BaseItem - 아이템 공통 부모 클래스

// BaseItem.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ItemInterface.h"
#include "BaseItem.generated.h"

class USphereComponent; // 충돌 감지용 Sphere 컴포넌트 전방 선언
class UParticleSystemComponent; // 파티클 컴포넌트 전방 선언

UCLASS()
class SPARTA_API ABaseItem : public AActor, public IItemInterface
{
    GENERATED_BODY()

public:
    ABaseItem();

    // 파티클 삭제 타이머 정리
    void ClearTimer();

protected:
    // 아이템 종류 구분용 이름
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
    FName ItemType;

    // 아이템의 루트 씬 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Item|Component")
    USceneComponent* Scene;

    // 플레이어와의 Overlap 감지용 충돌 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Item|Component")
    USphereComponent* Collision;

    // 아이템 외형 표시용 스태틱 메시
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Item|Component")
    UStaticMeshComponent* StaticMesh;

    // 아이템 획득 시 재생할 파티클
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
    UParticleSystem* PickupParticle;

    // 아이템 획득 시 재생할 사운드
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item|Effects")
    USoundBase* PickupSound;

    // 파티클 삭제 타이머 핸들
    FTimerHandle DestroyParticleTimerHandle;

    // 아이템과 다른 액터가 겹치기 시작했을 때 호출
    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;

    // 아이템 액터 제거
    void DestroyItem();

    // 생성된 파티클 제거
    void DestroyParticle(UParticleSystemComponent* Particle);
};

// BaseItem.cpp

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

// 아이템 기본 컴포넌트와 Overlap 이벤트 설정
ABaseItem::ABaseItem()
{
    PrimaryActorTick.bCanEverTick = false;

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

    // 충돌 컴포넌트 생성 및 설정
    Collision = CreateDefaultSubobject<USphereComponent>(TEXT("Collision"));

    // 충돌은 막지 않고 Overlap만 감지
    Collision->SetCollisionProfileName(TEXT("OverlapAllDynamic"));

    // 루트 컴포넌트로 설정
    Collision->SetupAttachment(Scene);

    // 스태틱 메시 컴포넌트 생성 및 설정
    StaticMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("StaticMesh"));
    StaticMesh->SetupAttachment(Collision);
    StaticMesh->SetCollisionEnabled(ECollisionEnabled::NoCollision);
    // 메시가 불필요하게 충돌을 막지 않도록 하기 위해, 별도로 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);
    }
}

// ======================================== //

// Overlap 종료 시 호출, 현재는 별도 기능 없음
void ABaseItem::OnItemEndOverlap(
    UPrimitiveComponent* OverlappedComp,
    AActor* OtherActor,
    UPrimitiveComponent* OtherComp,
    int32 OtherBodyIndex)
{
}

// ======================================== //

// 아이템 능력 실행
void ABaseItem::ActivateItem(AActor* Activator)
{
    // 획득 파티클이 있으면 생성
    if (PickupParticle)
    {
        UParticleSystemComponent* Particle = UGameplayStatics::SpawnEmitterAtLocation(
            GetWorld(),
            PickupParticle,
            GetActorLocation(),
            GetActorRotation(),
            false
        );

        // 파티클 생성 성공 시
        if (Particle)
        {
            // GameState에 파티클 등록
            if (ASpartaGameState* SpartaGameState = GetWorld()->GetGameState<ASpartaGameState>())
            {
                SpartaGameState->RegisterParticle(Particle);
            }

            // 파티클 안전 참조용 Weak Pointer 생성
            TWeakObjectPtr<UParticleSystemComponent> WeakParticle = Particle;

            // 지역 타이머 핸들 생성
            FTimerHandle LocalParticleTimerHandle;

            // 2초 뒤 파티클 제거
            GetWorld()->GetTimerManager().SetTimer(
                LocalParticleTimerHandle,
                FTimerDelegate::CreateLambda([WeakParticle]()
                    {
                        // 파티클이 아직 유효하면 제거
                        if (WeakParticle.IsValid())
                        {
                            WeakParticle->DeactivateSystem();
                            WeakParticle->DestroyComponent();
                        }
                    }),
                2.0f,
                false
            );
        }
    }

    // 획득 사운드가 있으면 재생
    if (PickupSound)
    {
        UGameplayStatics::PlaySoundAtLocation(
            GetWorld(),
            PickupSound,
            GetActorLocation()
        );
    }

    // 아이템 액터 제거
    DestroyItem();
}

// ======================================== //

// 아이템 타입 반환
FName ABaseItem::GetItemType() const
{
    return ItemType;
}

// ======================================== //

// 아이템 액터 제거
void ABaseItem::DestroyItem()
{
    Destroy();
}

// ======================================== //

// 파티클 제거 함수
void ABaseItem::DestroyParticle(UParticleSystemComponent* Particle)
{
    // 기존 파티클 타이머 정리
    ClearTimer();

    // 파티클이 유효하면 제거
    if (IsValid(Particle))
    {
        Particle->DestroyComponent();
    }
}

// ======================================== //

// 파티클 삭제 타이머 정리
void ABaseItem::ClearTimer()
{   
    // 월드가 유효하면 타이머 제거
    if (GetWorld())
    {
        GetWorld()->GetTimerManager().ClearTimer(DestroyParticleTimerHandle);
    }
}

4. MineItem - 지뢰 데미지 조절

// MineItem.h

#pragma once

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

UCLASS()
class SPARTA_API AMineItem : public ABaseItem
{
    GENERATED_BODY()

public:
    AMineItem();

    // 레벨에 따라 폭발 시간과 데미지 조정
    void ApplyLevelDifficulty(int32 LevelIndex);

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();
};

// MineItem.cpp


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

// 지뢰 기본값과 폭발 범위 컴포넌트 설정
AMineItem::AMineItem()
{
    // 기본 폭발 대기 시간
    ExplosionDelay = 3.0f;

    // 기본 폭발 범위
    ExplosionRadius = 300.0f;

    // 기본 폭발 데미지
    ExplosionDamage = 30.0f;

    // 아이템 타입 설정
    ItemType = "Mine";

    // 지뢰 발동 여부 초기화
    bHasExploded = false;

    // 폭발 범위 감지용 컴포넌트 생성
    ExplosionCollision = CreateDefaultSubobject<USphereComponent>(TEXT("ExplosionCollision"));
    // 폭발 범위 설정
    ExplosionCollision->InitSphereRadius(ExplosionRadius);
    // Overlap 감지용 충돌 프로파일 설정
    ExplosionCollision->SetCollisionProfileName(TEXT("OverlapAllDynamic"));
    // Scene 컴포넌트에 부착
    ExplosionCollision->SetupAttachment(Scene);
}

// ======================================== //

// 레벨에 따라 지뢰 난이도 조정
void AMineItem::ApplyLevelDifficulty(int32 LevelIndex)
{
    // 레벨이 오를수록 폭발 시간이 짧아짐, 최소 0.5초 유지
    ExplosionDelay = FMath::Max(0.5f, 1.5f - LevelIndex * 0.5f);

    // 레벨이 오를수록 데미지 증가
    ExplosionDamage = 30 + LevelIndex * 10;
}

// ======================================== //

// 플레이어가 지뢰에 닿았을 때 호출
void AMineItem::ActivateItem(AActor* Activator)
{
    // 이미 발동된 지뢰면 중복 실행 방지
    if (bHasExploded) return;

    // 지뢰 발동 상태로 변경
    bHasExploded = true;

    // 기본 충돌을 꺼서 중복 Overlap 방지
    if (Collision)
    {
        Collision->SetCollisionEnabled(ECollisionEnabled::NoCollision);
    }

    // 일정 시간 후 폭발 실행
    GetWorld()->GetTimerManager().SetTimer(
        ExplosionTimerHandle,
        this,
        &AMineItem::Explode,
        ExplosionDelay,
        false
    );

    // 지뢰 발동 사운드 재생
    if (PickupSound)
    {
        UGameplayStatics::PlaySoundAtLocation(
            GetWorld(),
            PickupSound,
            GetActorLocation()
        );
    }
}

// ======================================== //

// 지뢰 폭발 처리
void AMineItem::Explode()
{
    // 생성된 폭발 파티클 저장용
    UParticleSystemComponent* Particle = nullptr;

    // 폭발 파티클 생성
    if (ExplosionParticle)
    {
        Particle = UGameplayStatics::SpawnEmitterAtLocation(
            GetWorld(),
            ExplosionParticle,
            GetActorLocation(),
            GetActorRotation(),
            false
        );
    }

    // 폭발 사운드 재생
    if (ExplosionSound)
    {
        UGameplayStatics::PlaySoundAtLocation(
            GetWorld(),
            ExplosionSound,
            GetActorLocation()
        );
    }

    // 폭발 범위 안에 있는 액터 배열
    TArray<AActor*> OverlappingActors;

    // 폭발 범위에 겹쳐 있는 액터 가져오기
    ExplosionCollision->GetOverlappingActors(OverlappingActors);

    // 겹쳐 있는 액터 순회
    for (AActor* Actor : OverlappingActors)
    {
        // 플레이어 태그가 있는 액터만 데미지 적용
        if (Actor && Actor->ActorHasTag("Player"))
        {
            UGameplayStatics::ApplyDamage(
                Actor,
                ExplosionDamage,
                nullptr,
                this,
                UDamageType::StaticClass()
            );
        }
    }

    // 파티클이 생성되었을 경우
    if (Particle)
    {
        // GameState에 파티클 등록
        if (ASpartaGameState* SpartaGameState = GetWorld()->GetGameState<ASpartaGameState>())
        {
            SpartaGameState->RegisterParticle(Particle);
        }

        // 파티클 안전 참조용 Weak Pointer
        TWeakObjectPtr<UParticleSystemComponent> WeakParticle = Particle;

        // 파티클 삭제용 지역 타이머
        FTimerHandle LocalParticleTimerHandle;

        // 2초 뒤 파티클 제거
        GetWorld()->GetTimerManager().SetTimer(
            LocalParticleTimerHandle,
            FTimerDelegate::CreateLambda([WeakParticle]()
                {
                    // 파티클이 아직 유효하면 제거
                    if (WeakParticle.IsValid())
                    {
                        WeakParticle->DeactivateSystem();
                        WeakParticle->DestroyComponent();
                    }
                }),
            2.0f,
            false
        );
    }

    // 폭발 후 지뢰 제거
    DestroyItem();
}

5. HealingItem - 회복량 조절

// HealingItem.h

#pragma once

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

UCLASS()
class SPARTA_API AHealingItem : public ABaseItem
{
    GENERATED_BODY()

public:
    AHealingItem();

    // 레벨에 따라 회복량 조정
    void ApplyLevelDifficulty(int32 LevelIndex);

protected:
    // 회복량
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Healing")
    int32 HealAmount;

    // 플레이어가 아이템을 획득했을 때 회복 효과 실행
    virtual void ActivateItem(AActor* Activator) override;
};

// HealingItem.cpp

#include "HealingItem.h"
#include "SpartaCharacter.h"


// 회복 아이템 기본값 설정
AHealingItem::AHealingItem()
{
    HealAmount = 20.0f;
    ItemType = "Healing";
}

// ======================================== //

// 레벨에 따라 회복량 조정
void AHealingItem::ApplyLevelDifficulty(int32 LevelIndex)
{
    // 레벨이 올라갈수록 회복량 감소, 최소 10 유지
    HealAmount = FMath::Max(10, 30 - LevelIndex * 5);
}

// ======================================== //

// 플레이어가 회복 아이템을 획득했을 때 호출
void AHealingItem::ActivateItem(AActor* Activator)
{
    // 부모 클래스의 공통 효과 실행
    // 파티클, 사운드 재생 및 아이템 제거 처리
    Super::ActivateItem(Activator);

    // 획득한 액터가 플레이어인지 확인
    if (Activator && Activator->ActorHasTag("Player"))
    {
        // 플레이어 캐릭터로 캐스팅
        if (ASpartaCharacter* PlayerCharacter = Cast<ASpartaCharacter>(Activator))
        {
            // 체력 회복 적용
            PlayerCharacter->AddHealth(HealAmount);
        }

        // 아이템 제거
        DestroyItem();
    }
}

6. PlayerController - 메뉴/HUD 위젯 전환

// SpartaPlayerController.h

#pragma once

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

class UInputMappingContext; // IMC 관련 전방 선언
class UInputAction; // IA 관련 전방 선언
class USpartaHUDWidget; // HUDWidget 클래스 전방 선언
class USpartaMainMenuWidget; // 메인메뉴Widget 클래스 전방 선언

UCLASS()
class SPARTA_API ASpartaPlayerController : public APlayerController
{
    GENERATED_BODY()

public:
    ASpartaPlayerController();

    // 에디터 입력 매핑 컨텍스트
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
    UInputMappingContext* InputMappingContext;

    // 이동 입력 액션
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
    UInputAction* MoveAction;

    // 점프 입력 액션
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
    UInputAction* JumpAction;

    // 시점 회전 입력 액션
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
    UInputAction* LookAction;

    // 달리기 입력 액션
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Input")
    UInputAction* SprintAction;

    // HUD 위젯 블루프린트 클래스
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "HUD")
    TSubclassOf<USpartaHUDWidget> HUDWidgetClass;

    // 실제 생성된 HUD 위젯 인스턴스
    UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category = "HUD")
    USpartaHUDWidget* HUDWidgetInstance;

    // HUD 위젯 반환
    UFUNCTION(BlueprintPure, Category = "HUD")
    USpartaHUDWidget* GetHUDWidget() const;

    // 메인 메뉴 위젯 블루프린트 클래스
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Menu")
    TSubclassOf<USpartaMainMenuWidget> MainMenuWidgetClass;

    // 실제 생성된 메인 메뉴 위젯 인스턴스
    UPROPERTY(VisibleAnywhere, BlueprintReadWrite, Category = "Menu")
    USpartaMainMenuWidget* MainMenuWidgetInstance;

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

    // 메인 메뉴 또는 게임오버 메뉴 표시
    UFUNCTION(BlueprintCallable, Category = "Menu")
    void ShowMainMenu(bool bIsRestart);

    // 게임 시작 또는 재시작
    UFUNCTION(BlueprintCallable, Category = "Menu")
    void StartGame();

    // 메인 메뉴 맵으로 이동
    UFUNCTION(BlueprintCallable, Category = "Menu")
    void ReturnToMainMenu();

    // 게임 종료
    UFUNCTION(BlueprintCallable, Category = "Menu")
    void QuitGame();

protected:
    // 게임 시작 시 입력 매핑 및 메뉴 표시 처리
    virtual void BeginPlay() override;
};

// SpartaPlayerController.cpp

#include "SpartaPlayerController.h"
#include "EnhancedInputSubsystems.h"
#include "SpartaHUDWidget.h"
#include "SpartaMainMenuWidget.h"
#include "SpartaGameState.h"
#include "Components/TextBlock.h"
#include "SpartaGameInstance.h"
#include "Kismet/GameplayStatics.h"
#include "Kismet/KismetSystemLibrary.h"

// 포인터 변수 기본값 초기화
ASpartaPlayerController::ASpartaPlayerController()
    : InputMappingContext(nullptr),
    MoveAction(nullptr),
    JumpAction(nullptr),
    LookAction(nullptr),
    SprintAction(nullptr),
    HUDWidgetClass(nullptr),
    HUDWidgetInstance(nullptr),
    MainMenuWidgetClass(nullptr),
    MainMenuWidgetInstance(nullptr)
    // 아직 에디터에서 값이 할당되지 않아서
    // 이상한 값이 들어갈 수도 있으니 기본값을 nullptr로 초기화
{
}

// ======================================== //

// 게임 시작 시 입력 매핑과 메뉴 표시 처리
void ASpartaPlayerController::BeginPlay()
{
    Super::BeginPlay();

    // 현재 PlayerController에 연결된 Local Player 객체를 가져옴    
    if (ULocalPlayer* LocalPlayer = GetLocalPlayer())
    {
        // Local Player에서 Enhanced Input Subsystem 가져오ㅁ
        if (UEnhancedInputLocalPlayerSubsystem* Subsystem =
            LocalPlayer->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>())
        {
            // 입력 매핑 컨텍스트가 있으면 적용
            if (InputMappingContext)
            {
                // Subsystem을 통해 IMC를 활성화(입력 매핑 적용)
                // 0은 가장 높은 우선순위(Priority)
                Subsystem->AddMappingContext(InputMappingContext, 0);
            }
        }
    }

    // 현재 맵 이름 확인
    FString CurrentMapName = GetWorld()->GetMapName();

    // 메뉴 레벨이면 메인 메뉴 표시
    if (CurrentMapName.Contains("MenuLevel"))
    {
        ShowMainMenu(false);
    }
}

// ======================================== //

// 메인 메뉴 또는 게임오버 메뉴 표시
void ASpartaPlayerController::ShowMainMenu(bool bIsRestart)
{
    // 기존 HUD 제거
    if (HUDWidgetInstance)
    {
        HUDWidgetInstance->RemoveFromParent();
        HUDWidgetInstance = nullptr;
    }

    // 기존 메뉴 제거
    if (MainMenuWidgetInstance)
    {
        MainMenuWidgetInstance->RemoveFromParent();
        MainMenuWidgetInstance = nullptr;
    }

    // 메뉴 위젯 클래스가 설정되어 있으면 생성
    if (MainMenuWidgetClass)
    {
        MainMenuWidgetInstance = CreateWidget<USpartaMainMenuWidget>(this, MainMenuWidgetClass);
        if (MainMenuWidgetInstance)
        {
            // 메뉴를 화면에 추가
            MainMenuWidgetInstance->AddToViewport();

            // 마우스 커서 표시 및 UI 입력 모드 설정
            bShowMouseCursor = true;
            SetInputMode(FInputModeUIOnly());

            // 총점수 기본값
            int32 TotalScore = 0;

            // GameInstance에서 총점 가져오기
            if (USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(UGameplayStatics::GetGameInstance(this)))
            {
                TotalScore = SpartaGameInstance->TotalScore;
            }

            // 메뉴 상태 설정
            MainMenuWidgetInstance->SetupMenu(bIsRestart, TotalScore);
        }
    }
}

// ======================================== //

// 게임 HUD 표시
void ASpartaPlayerController::ShowGameHUD()
{
    // 기존 HUD 제거
    if (HUDWidgetInstance)
    {
        HUDWidgetInstance->RemoveFromParent();
        HUDWidgetInstance = nullptr;
    }

    // 기존 메뉴 제거
    if (MainMenuWidgetInstance)
    {
        MainMenuWidgetInstance->RemoveFromParent();
        MainMenuWidgetInstance = nullptr;
    }

    // HUD 위젯 클래스가 설정되어 있으면 생성
    if (HUDWidgetClass)
    {
        HUDWidgetInstance = CreateWidget<USpartaHUDWidget>(this, HUDWidgetClass);
        if (HUDWidgetInstance)
        {
            // HUD를 화면에 추가
            HUDWidgetInstance->AddToViewport();

            // 마우스 커서 숨김 및 게임 입력 모드 설정
            bShowMouseCursor = false;
            SetInputMode(FInputModeGameOnly());
        }

        // HUD 생성 직후 한 번 갱신
        ASpartaGameState* SpartaGameState = GetWorld() ? GetWorld()->GetGameState<ASpartaGameState>() : nullptr;
        if (SpartaGameState)
        {
            SpartaGameState->UpdateHUD();
        }
    }
}

// ======================================== //

// 게임 시작 또는 재시작
void ASpartaPlayerController::StartGame()
{
    // GameInstance 점수와 레벨 인덱스 초기화
    if (USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(UGameplayStatics::GetGameInstance(this)))
    {
        SpartaGameInstance->CurrentLevelIndex = 0;
        SpartaGameInstance->TotalScore = 0;
    }

    // 첫 번째 레벨로 이동
    UGameplayStatics::OpenLevel(GetWorld(), FName("Level1"));

    // 일시정지 해제
    SetPause(false);
}

// ======================================== //

// HUD 위젯 인스턴스 반환
USpartaHUDWidget* ASpartaPlayerController::GetHUDWidget() const
{
    return HUDWidgetInstance;
}

// ======================================== //

// 메인 메뉴 맵으로 이동
void ASpartaPlayerController::ReturnToMainMenu()
{
    UGameplayStatics::OpenLevel(GetWorld(), FName("MenuLevel"));
}

// ======================================== //

// 게임 종료
void ASpartaPlayerController::QuitGame()
{
    UKismetSystemLibrary::QuitGame(this, this, EQuitPreference::Quit, false);
}

7. HUDWidget / MainMenuWidget - UI 관리

// SpartaHUDWidget.h

#pragma once

#include "CoreMinimal.h"
#include "Blueprint/UserWidget.h"
#include "SpartaHUDWidget.generated.h"

class UTextBlock;   // HUD에 표시할 텍스트 위젯 전방 선언
class UProgressBar; // 체력바 표시용 ProgressBar 전방 선언

UCLASS()
class SPARTA_API USpartaHUDWidget : public UUserWidget
{
	GENERATED_BODY()

public:
    // GameState에서 전달받은 값으로 HUD를 갱신
    void UpdateHUD(
        float RemainingTime,
        int32 TotalScore,
        int32 LevelIndex,
        int32 WaveIndex,
        float Health,
        float MaxHealth
    );

protected:
    // 남은 시간 표시 텍스트
    UPROPERTY(meta = (BindWidget))
    UTextBlock* TimeValue;

    // 점수 표시 텍스트
    UPROPERTY(meta = (BindWidget))
    UTextBlock* ScoreValue;

    // 현재 레벨 표시 텍스트
    UPROPERTY(meta = (BindWidget))
    UTextBlock* Level;

    // 현재 웨이브 표시 텍스트
    UPROPERTY(meta = (BindWidget))
    UTextBlock* Wave;

    // 체력 수치 표시 텍스트
    UPROPERTY(meta = (BindWidget))
    UTextBlock* HealthValue;

    // 체력 비율 표시 바
    UPROPERTY(meta = (BindWidget))
    UProgressBar* HealthBar;
};

// SpartaHUDWidget.cpp

#include "SpartaHUDWidget.h"
#include "Components/TextBlock.h"
#include "Components/ProgressBar.h"

// HUD에 표시할 값들을 갱신하는 함수
void USpartaHUDWidget::UpdateHUD(
    float RemainingTime,
    int32 TotalScore,
    int32 LevelIndex,
    int32 WaveIndex,
    float Health,
    float MaxHealth
)
{
    // 남은 시간 텍스트 갱신
    if (TimeValue)
    {
        TimeValue->SetText(FText::FromString(FString::Printf(TEXT("Time: %.1f"), RemainingTime)));
    }

    // 점수 텍스트 갱신
    if (ScoreValue)
    {
        ScoreValue->SetText(FText::FromString(FString::Printf(TEXT("Score: %d"), TotalScore)));
    }

    // 레벨 텍스트 갱신
    // LevelIndex는 0부터 시작하므로 화면에는 +1해서 표시
    if (Level)
    {
        Level->SetText(FText::FromString(FString::Printf(TEXT("Level: %d"), LevelIndex + 1)));
    }

    // 웨이브 텍스트 갱신
    if (Wave)
    {
        Wave->SetText(FText::FromString(FString::Printf(TEXT("Wave: %d"), WaveIndex)));
    }

    // 체력 수치 텍스트 갱신
    if (HealthValue)
    {
        HealthValue->SetText(FText::FromString(FString::Printf(TEXT("HP: %.0f / %.0f"), Health, MaxHealth)));
    }

    // 체력바 비율 갱신
    if (HealthBar)
    {
        // 최대 체력이 0보다 클 때만 비율 계산
        const float HealthPercent = MaxHealth > 0.0f ? Health / MaxHealth : 0.0f;

        // ProgressBar는 0.0 ~ 1.0 비율로 표시
        HealthBar->SetPercent(HealthPercent);
    }
}

// SpartaMainMenuWidget.h

#pragma once

#include "CoreMinimal.h"
#include "Blueprint/UserWidget.h"
#include "SpartaMainMenuWidget.generated.h"

class UTextBlock;
class UButton;

UCLASS()
class SPARTA_API USpartaMainMenuWidget : public UUserWidget
{
    GENERATED_BODY()

public:
    void SetupMenu(bool bIsRestart, int32 TotalScore);

protected:
    UPROPERTY(BlueprintReadOnly, meta = (BindWidget), Category = "Menu")
    UTextBlock* StartButtonText;

    UPROPERTY(BlueprintReadOnly, meta = (BindWidget), Category = "Menu")
    UTextBlock* GameOverText;

    UPROPERTY(BlueprintReadOnly, meta = (BindWidget), Category = "Menu")
    UTextBlock* TotalScoreText;

    UPROPERTY(BlueprintReadOnly, meta = (BindWidget), Category = "Menu")
    UButton* MainMenuButton;
};

// SpartaMainMenuWidget.cpp

#include "SpartaMainMenuWidget.h"
#include "Components/TextBlock.h"
#include "Components/Button.h"

void USpartaMainMenuWidget::SetupMenu(bool bIsRestart, int32 TotalScore)
{
    if (StartButtonText)
    {
        StartButtonText->SetText(FText::FromString(bIsRestart ? TEXT("Restart") : TEXT("Start")));
    }

    if (GameOverText)
    {
        GameOverText->SetVisibility(bIsRestart ? ESlateVisibility::Visible : ESlateVisibility::Hidden);
    }

    if (TotalScoreText)
    {
        TotalScoreText->SetVisibility(bIsRestart ? ESlateVisibility::Visible : ESlateVisibility::Hidden);

        if (bIsRestart)
        {
            TotalScoreText->SetText(FText::FromString(
                FString::Printf(TEXT("Total Score: %d"), TotalScore)
            ));
        }
    }

    if (MainMenuButton)
    {
        MainMenuButton->SetVisibility(bIsRestart ? ESlateVisibility::Visible : ESlateVisibility::Hidden);
    }
}

타이머 실행중에 레벨이 바뀌면 에디터가 종료되는 오류

hyunjunstar — Tue, 21 Apr 2026 22:39:38 +0900

언리얼 C++에서 타이머를 이용해서 일정 시간이 지나면 파티클이 제거되게끔 구현을 하였다.

아래는 구현한 코드

// BaseItem.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ItemInterface.h"
#include "BaseItem.generated.h"

class USphereComponent;

UCLASS()
class SPARTA_API ABaseItem : public AActor, public IItemInterface
{
    GENERATED_BODY()

public:
    ABaseItem();

protected:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
    FName ItemType;
    // 루트 컴포넌트 (씬)
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Item|Component")
    USceneComponent* Scene;
    // 충돌 컴포넌트 (플레이어 진입 범위 감지용)
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Item|Component")
    USphereComponent* Collision;
    // 아이템 시각 표현용 스태틱 메시
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, 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;

    void DestroyItem();
};

// 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->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)
{
    UParticleSystemComponent* Particle = nullptr;

    if (PickupParticle)
    {
        Particle = UGameplayStatics::SpawnEmitterAtLocation(
            GetWorld(),
            PickupParticle,
            GetActorLocation(),
            GetActorRotation(),
            true
        );
    }

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

    if (Particle)
    {
        FTimerHandle DestroyParticleTimerHandle;

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

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

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

// MineItem.h

#pragma once

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

UCLASS()
class SPARTA_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;

    // 폭발까지 걸리는 시간 (5초)
    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();
};

// 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->SetupAttachment(Scene);
}

void AMineItem::ActivateItem(AActor* Activator)
{
    if (bHasExploded) return;

    Super::ActivateItem(Activator);

    GetWorld()->GetTimerManager().SetTimer(
        ExplosionTimerHandle,
        this,
        &AMineItem::Explode,
        ExplosionDelay,
        false
    );

    bHasExploded = true;
}

void AMineItem::Explode()
{
    UParticleSystemComponent* Particle = nullptr;


    if (ExplosionParticle)
    {
        Particle = UGameplayStatics::SpawnEmitterAtLocation(
            GetWorld(),
            ExplosionParticle,
            GetActorLocation(),
            GetActorRotation(),
            false
        );
    }

    if (ExplosionSound)
    {
        UGameplayStatics::PlaySoundAtLocation(
            GetWorld(),
            ExplosionSound,
            GetActorLocation()
        );
    }

    TArray<AActor*> OverlappingActors;
    ExplosionCollision->GetOverlappingActors(OverlappingActors);

    for (AActor* Actor : OverlappingActors)
    {
        if (Actor && Actor->ActorHasTag("Player"))
        {
            UGameplayStatics::ApplyDamage(
                Actor,
                ExplosionDamage,
                nullptr,
                this,
                UDamageType::StaticClass()
            );
        }
    }

    // 지뢰 제거
    DestroyItem();

    /*if (Particle)
    {
        FTimerHandle DestroyParticleTimerHandle;

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

구현이 다 끝나고 게임 실행을 해서 테스트를 해보니,

레벨이 바뀔때 갑자기 에디터가 종료되고 비주얼스튜디오에서 아래 코드로 이동되면서 디버깅이 실행이 되었다.

	// faster than GetValueOnAnyThread()
	T GetValueOnRenderThread() const
	{
		UE::AccessDetection::ReportAccess(UE::AccessDetection::EType::CVar);
#if !defined(__clang__) // @todo Mac: figure out how to make this compile
		// compiled out in shipping for performance (we can change in development later), if this get triggered you need to call GetValueOnGameThread() or GetValueOnAnyThread(), the last one is a bit slower
		cvarCheckCode(ensure(IsInParallelRenderingThread()));	// ensure to not block content creators, #if to optimize in shipping
#endif
		return ShadowedValue[1];
	}

cvarCheckCode(ensure(IsInParallelRenderingThread()));	// ensure to not block content creators, #if to optimize in shipping

case FTimerDelegateVariant::IndexOfType<FTimerFunction>():
	{
		if (const FTimerFunction& TimerFunction = VariantDelegate.Get<FTimerFunction>())
		{
			QUICK_SCOPE_CYCLE_COUNTER(STAT_FTimerUnifiedDelegate_Execute);
			TimerFunction();
		}
		break;
	}
default:
	break;
}

계속 테스트 해보면서 원인을 찾아보니 파티클을 제거하는 타이머가 실행중일때 다음 레벨로 바뀌면서 오류가 뜨는거였다.

레벨1 > 레벨2로 바뀌면서 레벨1에 있던 기존 액터들이 전부 제거되고 레벨2에서 새로운 액터들이 생성 되는 구조인데,

레벨2로 바뀌면서 제거된 후 레벨1에서 타이머 작동중인 액터가 있었을때 타이머가 그 액터로 접근을 하면서 오류가 실행 된 것이다.

문제라고 생각한 코드

// BaseItem.cpp

void ABaseItem::ActivateItem(AActor* Activator)
{
    UParticleSystemComponent* Particle = nullptr;

    if (Particle)
    {
        FTimerHandle DestroyParticleTimerHandle;

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

// MineItem.cpp

void AMineItem::Explode()
{
    UParticleSystemComponent* Particle = nullptr;

    if (Particle)
    {
        FTimerHandle DestroyParticleTimerHandle;

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

이 두 코드의 타이머가 제거가 안된 상태에서,

레벨이 넘어가며 삭제된 파티클 삭제 타이머에 접근하여 오류가 난 것이라고 생각이 들어서

아래처럼 함수와 변수를 추가해주었고 코드를 수정 하였다

// BaseItem.h

UCLASS()
class SPARTA_API ABaseItem : public AActor, public IItemInterface
{
    GENERATED_BODY()

public:
    ABaseItem();
	
    // ActivateItem 함수 안에서 지역변수로 사용하던 타이머핸들을
    // 멤버 변수로 분리하여 다른 함수에서도 사용 가능하게 정의
    FTimerHandle DestroyParticleTimerHandle;
    
    // 파티클 삭제를 위한 함수
    // 람다 내부에서 직접 처리하지 않고 함수로 분리하여 사용
    void DestroyParticle(UParticleSystemComponent* Particle);
    
    // DestroyParticleTimerHandle를 삭제하는 함수 
    // 레벨 변경시 타이머로 인한 오류 발생 방지
    void ClearTimer();
};

// BaseItem.cpp

// 파티클이 생성된 경우
if (Particle)
{   // 일정시간(2초) 후 DestroyParticle(Particle); 함수 실행
    GetWorld()->GetTimerManager().SetTimer(
        DestroyParticleTimerHandle,
        [Particle, this]()
	{   // 기존 Particle->DestroyComponent(); 대신
    	    // 파티클과 타이머 삭제 함수를 만들어서 사용
    	    DestroyParticle(Particle);
        },
        2.0f,
        false
    );
}

// 파티클과 파티클 삭제 타이머를 제거하는 함수
void ABaseItem::DestroyParticle(UParticleSystemComponent* Particle)
{
    // 파티클 삭제 타이머 함수 호출(타이머 삭제)
    ClearTimer();
    // 생성된 파티클 컴포넌트 삭제
    Particle->DestroyComponent();
}

// 파티클 삭제 타이머를 제거하는 함수
void ABaseItem::ClearTimer()
{   // DestroyParticleTimerHandle에 등록된 타이머를 제거
    // 레벨 전환시 살아있는 타이머 때문에 생기는 오류 방지
    GetWorld()->GetTimerManager().ClearTimer(DestroyParticleTimerHandle);
}

// MineItem.cpp

if (Particle)
{
    GetWorld()->GetTimerManager().SetTimer(
        DestroyParticleTimerHandle,
        [Particle, this]()
        {
            ABaseItem::DestroyParticle(Particle);
        },
        2.0f,
        false
    );
}

위와 같이 코드를 수정하고 변수와 함수를 새로 추가해주었고,

레벨이 변경되는 시점에 코드를 추가해주었따.

아래는 수정 전 코드

// GameState.cpp

void ASpartaGameState::EndLevel()
{
    GetWorldTimerManager().ClearTimer(LevelTimerHandle);

    if (UGameInstance* GameInstance = GetGameInstance())
    {
        USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(GameInstance);
        if (SpartaGameInstance)
        {
            AddScore(Score);
            CurrentLevelIndex++;
            SpartaGameInstance->CurrentLevelIndex = CurrentLevelIndex;

            if (CurrentLevelIndex >= MaxLevels)
            {
                OnGameOver();
                return;
            }

            if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
            {
                UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
            }
            else
            {
                OnGameOver();
            }
        }
    }
}

아래는 수정한 코드

// GameState.cpp

void ASpartaGameState::EndLevel()
{
    GetWorldTimerManager().ClearTimer(LevelTimerHandle);
    {   // 현재 월드 내에 존재하는 모든 액터를 찾기 위한 배열 정의
        TArray<AActor*> Actors;
        // BaseItem 클래스를 상속받은 모든 액터를 찾아서 Actors 배열에 저장
        UGameplayStatics::GetAllActorsOfClass(GetWorld(), ABaseItem::StaticClass(), Actors);

        // 찾은 모든 액터를 순회
        for (AActor* Item : Actors)
        {   // AActor를 ABaseItem으로 캐스팅
            if (ABaseItem* BaseItem = Cast<ABaseItem>(Item))
            {   // 액터들에 설정되어 있는 파티클 삭제 타이머를 제거
                BaseItem->ClearTimer();
            }
        }
    }

    if (UGameInstance* GameInstance = GetGameInstance())
    {
        USpartaGameInstance* SpartaGameInstance = Cast<USpartaGameInstance>(GameInstance);
        if (SpartaGameInstance)
        {
            AddScore(Score);
            CurrentLevelIndex++;
            SpartaGameInstance->CurrentLevelIndex = CurrentLevelIndex;

            if (CurrentLevelIndex >= MaxLevels)
            {
                OnGameOver();
                return;
            }

            if (LevelMapNames.IsValidIndex(CurrentLevelIndex))
            {
                UGameplayStatics::OpenLevel(GetWorld(), LevelMapNames[CurrentLevelIndex]);
            }
            else
            {
                OnGameOver();
            }
        }
    }
}

이번 문제를 발견하고 해결하면서 타이머는 액터가 삭제되더라도 자동으로 정리되지 않으며,

레벨 전환시 타이머를 직접 관리를 해줘야 한다는 것을 알게 되었다.

Unreal C++ 기초 8. 아이템 스폰 및 레벨 데이터 구현

hyunjunstar — Fri, 17 Apr 2026 23:59:35 +0900

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

레벨 위에 아이템을 직접 하나하나 배치하는 방식이 아니라,

지정한 영역 내에서 랜덤 위치에 아이템이 생성되도록 구현해보았다.
이를 위해 SpawnVolume이라는 액터를 생성하고 해당 영역 안에서 아이템이 랜덤으로 스폰되도록 설정했다.

레벨 셋팅

우선 Resources - Maps 폴더에 있는 3개의 레벨을 Content - Maps 폴더로 이동 >

Project Settings > Maps&Modes > Editor Startup Map, Game Default Map을 BasicLevel 적용

각 레벨은 난이도에 따라 구분되어 있으며, 난이도가 올라갈수록 맵 크기가 작아진다.

BasicLevel -> IntermediateLevel -> AdvancedLevel 순서

액터 생성

상단 툴바 > Tools 클릭 > New C++ Class 클릭 > Actor 클릭 > 이름 SpawnVolume으로 지정 후 생성

생성 후 Visual Studio 코드 작성(각 코드 설명은 주석처리)

// SpawnVolume.h

#pragma once

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

// 박스 컴포넌트 전방선언
class UBoxComponent;

UCLASS()
class SPARTAPROJECT_API ASpawnVolume : public AActor
{
    GENERATED_BODY()

public:
    ASpawnVolume();
	
    // 루트 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Spawning")
    USceneComponent* Scene;
    // 아이템이 생성될 영역 박스 컴포넌트
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Spawning")
    UBoxComponent* SpawningBox;

    // SpawnVolume 범위 내에 랜덤 좌표 반환하는 함수
    UFUNCTION(BlueprintCallable, Category = "Spawning")
    FVector GetRandomPointInVolume() const;
    
    // 아이템 스폰 함수
    UFUNCTION(BlueprintCallable, Category = "Spawning")
    void SpawnItem(TSubclassOf<AActor> ItemClass);
};

// SpawnVolume.cpp

#include "SpawnVolume.h"
// UBoxComponent 사용을 위한 인클루드
#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
{
    // 박스의 절반 크기값을 벡터로 가져옴
    FVector BoxExtent = SpawningBox->GetScaledBoxExtent();
    // 박스의 기준 좌표이며 중심 위치값을 벡터로 가져옴
    FVector BoxOrigin = SpawningBox->GetComponentLocation();
	
    // 아이템 최종 스폰 위치
    // 중심 위치 + 랜덤 값(-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	// 기본 방향(0, 0, 0)을 기준으로 생성
    );
}

SpawnVolume 영역 지정

생성한 C++ 클래스 SpawnVolume 좌클릭 > Create Blueprint class based on SpawnVolume 클릭 >

BP_SpawnVolume으로 이름 지정후 생성

기존 레벨에 배치한 액터들 전부 삭제 후 BP_SpawnVolume를 각 레벨에 배치

SpawnVolume 크기

BasicLevel - Location(0, 0, 100) / Scale(90, 90, 3)

IntermediateLevel - Location(0, 0, 100) / Scale(61, 61, 3)

AdvancedLevel - Location(0, 0, 100) / Scale(77, 77, 3)

2. 아이템 스폰 확률 데이터 테이블 생성 및 적용

Item Data 구조체 생성

아이템 스폰 확률을 코드에 직접 작성(하드코딩)하면 값을 수저알 때마다 빌드를 해줘야 해서 비효율적임

그래서 언리얼 엔진의 Data Table을 사용해서 아이템 정보와 확률을 외부 데이터(CSV, JSON 파일 등)로 관리해서

엔진 안으로 임포트 하여 코드나 블루프린트에서 쉽게 사용 가능하다.

이렇게 외부 데이터를 사용하면 기획자도 쉽게 직접 수정이 가능하다.

상단 툴바 > Tools 클릭 > New C++ Class 클릭 > None 클릭 > 이름을 ItemSpawnRow로 지정하여 생성

// ItemSpawnRow.h

#pragma once

#include "CoreMinimal.h"
// Data Table에서 Row로 사용하기 위한 FTableRowBase 정의
#include "Engine/DataTable.h"
#include "ItemSpawnRow.generated.h"

// DataTable에서 사용할 Row 구조체이며, 
// FTableRowBase를 상속해야 DataTable로 사용 가능
USTRUCT(BlueprintType)
struct FItemSpawnRow : public FTableRowBase
{
    GENERATED_BODY()

public:
    // 아이템 이름
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName ItemName;

    // 하드 레퍼런스 : TSubclassOf
    // - 클래스가 메모리에 바로 로드(빠르게 사용 가능, 소규모 프로젝트)
    // 소프트 레퍼런스 : TSoftClassPtr
    // - 경로만 저장하고 필요할 때 로드(메모리 절약, 대규모 프로젝트)

    // 스폰할 아이템 클래스(AActor를 상속한 클래스만 가능)
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TSubclassOf<AActor> ItemClass;

    // 스폰될 아이템 확률
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float Spawnchance;
};

아이템 확률 적용(CSV, JSON 임포트 및 언리얼 에디터에서 직접 수정)

CSV 파일로 임포트

엑셀 파일 실행 후 데이터 입력 > 이름 ItemSpawnTable로 지정 > CSV파일로 저장 > 언리얼 에디터로 이동 >

	ItemName	ItemClass	Spawnchance
SmallCoinItem	SmallCoinItem	BP클래스 우클릭 > Copy Reference > 붙여넣기 >	30
BigCoinItem	BigCoinItem	맨 뒤에 _C 붙여주기(아래 예시 참고)	10
MineItem	MineItem	/Script/Engine.Blueprint'/Game/Blueprints/BP_MineItem.BP_MineItem_C'	40
HealingItem	HealingItem	위 예시처럼 카피 레퍼런스로 가져와서 뒤에 _C 꼭 붙여주기	20

데이터 테이블을 생성할 폴더로 이동 > Import to /Game/Blueprints...(경로) 클릭 > ItemSpawnTable.csv 열기 >

아래 사진처럼 설정 후 Apply 클릭

언리얼 에디터에서 직접 수정

Blueprints 폴더로 들어가서 빈 공간 우클릭 > Miscellaneous > Data Table 검색 > 이름 ItemSpawnTable 지정후 생성 >

팝업창에 Row Structure를 FItemSpawnRow 선택 후 생성 > 생성된 데이터 테이블 더블클릭 >

상단 바에 +Add 클릭해서 직접 수정 가능(Item Class는 선택 해줘야함)

SpawnVolume에 확률 적용하기

// SpawnVolume.h

#pragma once

#include "CoreMinimal.h"
// 아이템 데이터 테이블 구조체 인클루드
#include "ItemSpawnRow.h"
#include "GameFramework/Actor.h"
#include "SpawnVolume.generated.h"

class UBoxComponent;

UCLASS()
class SPARTA_API ASpawnVolume : public AActor
{
    GENERATED_BODY()
	
public:	
    ASpawnVolume();

    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Spawning")
    USceneComponent* SceneComp;
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Spawning")
    UBoxComponent* SpawningBox;

    // 아이템 데이터 테이블 
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Spawning")
    UDataTable* ItemDataTable;

    // 데이터 테이블의 확률 기반으로 랜덤 아이템을 스폰하는 함수
    UFUNCTION(BlueprintCallable, Category = "Spawning")
    void SpawnRandomItem();

    // 데이터 테이블에서 확률 계산을 통해 하나의 아이템 Row(줄)를 선택하는 함수
    // 누적 확률 방식으로 랜덤 선택
    FItemSpawnRow* GetRandomItem() const;

    void SpawnItem(TSubclassOf<AActor> ItemClass);
    FVector GetRandomPointInVolume() const;
};

// SpawnVolume.cpp

#include "SpawnVolume.h"
#include "Components/BoxComponent.h"

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

    SceneComp = CreateDefaultSubobject<USceneComponent>(TEXT("SceneComponent"));
    SetRootComponent(SceneComp);

    SpawningBox = CreateDefaultSubobject<UBoxComponent>(TEXT("Spawning Box"));
    SpawningBox->SetupAttachment(SceneComp);

    // 초기값 nullptr
    ItemDataTable = nullptr;
}

void ASpawnVolume::SpawnRandomItem()
{
    // 데이터 테이블에서 확률 계산 후 아이템 선택
    // 선택한 아이템 SelectedRow에 저장
    if (FItemSpawnRow* SelectedRow = GetRandomItem())
    {
        // 선택된 아이템을 실제로 꺼냄
        // TusbclassOf -> UClass로 변환
        if (UClass* ActualClass = SelectedRow->ItemClass.Get())
        {
            // 선택된 아이템을 실제로 월드에 스폰
            SpawnItem(ActualClass);
        }
    }
}

FItemSpawnRow* ASpawnVolume::GetRandomItem() const
{
    // DataTable이 있어야 실행(없으면 바로 종료)
    if (!ItemDataTable) return nullptr;

    // 모든 아이템을 담을 배열 생성
    TArray<FItemSpawnRow*> AllRows;

    static const FString ContextString(TEXT("ItemSpawnContext"));

    // 데이터 테이블에 있는 모든 아이템 가져오기
    ItemDataTable->GetAllRows(ContextString, AllRows);

    // 데이터가 없으면 종료
    if (AllRows.IsEmpty()) return nullptr;

    // 전체 확률 합을 저장하는 변수
    float TotalChance = 0.0f;

    // 아이템 반복문 시작
    for (const FItemSpawnRow* Row : AllRows)
    {
        // 아이템 목록이 유효한지 확인
        if (Row)
        {
            // 아이템들의 확률을 더해서 총합 계산
            TotalChance += Row->Spawnchance;
        }
    }

    // 0 ~ 전체 확률 사이 랜덤값 생성
    const float RandValue = FMath::FRandRange(0.0f, TotalChance);

    // 누적 확률 계산용 변수
    float AccumulateChance = 0.0f;

    // 어떤 아이템을 선택할지 반복문 시작
    for (FItemSpawnRow* Row : AllRows)
    {
        // 누적된 확률 값 생성
        AccumulateChance += Row->Spawnchance;

        // 랜덤 값이 현재 누적 확률 구간에 포함되면 해당 아이템 선택
        if (RandValue <= AccumulateChance)
        {
            // 선택된 아이템을 반환
            return Row;
        }
    }

    return nullptr;
}

FVector ASpawnVolume::GetRandomPointInVolume() const
{
    FVector BoxExtent = SpawningBox->GetScaledBoxExtent();
    FVector BoxOrigin = SpawningBox->GetComponentLocation();

    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
    );
}

코드 작성 후 엑셀파일 열어서 데이터 입력후 csv 파일 3개 생성(레벨별 데이터 관리) >

에디터로 돌아와서 Content - DataTables 폴더 생성 > 해당 폴더에 생성한 csv 파일 세개 임포트 >

각 레벨(총 3개)별로 BP_SpawnVolume 설치 후 클릭 > 우측중단 Details 탭 > item 검색 > Spawning > Item Data Table 적용

엑셀 파일에서 데이터 확률이나 추가 등 수정한건 DataTable 더블클릭 > 좌측상단 툴바에 Reimort 클릭하면 반영

3. 이벤트 그래프 로직 설정

BP_SpawnVolume 더블클릭 > 이벤트 그래프에서

아래처럼 하면 게임 시작시 3초마다 아이템이 1개씩 생성

아래처럼 하면 게임 시작시 10개 생성