📘TIL - 에픽 몬스터 구현 마무리 & 리팩토링

목차

1. 오늘 작업 개요
2. 공통 코드 하드코딩 제거 (리팩토링 설계)
3. 공통 StateTree Task에서 EpicMonsterCharacter 직접 의존 제거
4. Build.cs 에디터 모듈 의존성 누락 수정
5. DataTable 필드명 호환성 복구 및 develop 구조 정렬
6. develop 머지 충돌 해결 전략
7. 에픽 기본 공격 태그 누락 버그
8. 그로기 시스템 3종 버그 수정
9. Treant 특수 스킬 투사체/VFX 오류 수정
10. HP Bar 동기화 문제 수정
11. WBP_MonsterHealthBar 레이아웃 재정렬
12. 오늘 변경 파일 요약
13. 내일 할 일

---

오늘 작업 개요

에픽 몬스터 3종(Dragon, Magma, Treant) 구현을 완료한 뒤, 공통 코드에 섞인 에픽 전용 로직을 분리하는 리팩토링을 진행했다. 이후 origin/develop 최신 사항과 머지하는 과정에서 발생한 충돌 해결, 기본 공격 버그 수정, 그로기 시스템 전반 수정, Treant 투사체/VFX 오류 수정까지 이어서 진행했다.

전체 흐름은 다음과 같다:
1. 공통 코드 하드코딩 제거 및 virtual 훅 구조 설계
2. Build.cs 에디터 모듈 의존성 누락 수정
3. DataTable 필드명 호환성 복구 및 develop 구조 정렬
4. develop 머지 및 충돌 해결
5. 에픽 기본 공격 태그 누락 버그 수정
6. 그로기 시스템 3종 버그 수정
7. Treant 투사체 VFX 오류 수정
8. HP Bar 동기화 문제 수정
9. WBP_MonsterHealthBar 레이아웃 재정렬 시도

---

1. 공통 코드 하드코딩 제거 (리팩토링 설계)

배경

에픽 몬스터 3종 구현을 완료한 직후, 로컬 체인지에는 공통 파일(EnemyCombatComponent, GA_ShootProjectiles, StateTreeTask_*)이 대거 수정되어 있었다. 문제는 이 파일들이 일반 몬스터·보스 몬스터에서도 사용하는 공통 파일이라는 점이었다.

구체적으로 EnemyCombatComponent.cpp에는 아래 같은 코드가 들어가 있었다:

// 잘못된 예 - 공통 컴포넌트에 에픽 row 이름 하드코딩
if (PatternRow->RowName == TEXT("Dragon_Bite") || PatternRow->RowName == TEXT("Dragon_AerialFireball"))
{
    Priority = 100;
}
if (PatternRow->RowName == TEXT("Treant_FloodBarrage"))
{
    MaxRange = 2500.f;
}

GA_ShootProjectiles.cpp에도 에셋 경로가 박혀 있었다:

// 잘못된 예 - 공통 GA에 에픽 전용 에셋 경로 하드코딩
if (PatternRow->RowName.ToString().Contains("Dragon"))
{
    ProjectileClass = StaticLoadClass(AEnemyProjectile::StaticClass(), nullptr,
        TEXT("/Game/Retrieve/AI/Boss/Projectiles/BP_LavaProjectile.BP_LavaProjectile_C"));
    StatusEffectClass = StaticLoadClass(UGameplayEffect::StaticClass(), nullptr,
        TEXT("/Game/Retrieve/AbilitySystem/Enemy/GE_Burn.GE_Burn_C"));
}
else if (PatternRow->RowName.ToString().Contains("Magma"))
{
    // GE_Cold ...
}

이 구조는 세 가지 문제를 만든다:

• 일반/보스 몬스터가 이 공통 코드를 타는 순간, 의도치 않게 에픽 분기에 걸릴 수 있다.
• 팀원들이 일반/보스 몬스터 작업 중 이 파일을 건드릴 때 병합 충돌이 크게 발생한다.
• row 이름을 바꾸거나 새 에픽 몬스터를 추가할 때마다 공통 코드를 수정해야 한다.

해결 방향

"공통 런타임 코드는 데이터만 읽는다"는 원칙 아래 다음 구조로 변경했다.

FMonsterPatternRow에 신규 필드 추가:

// RetrieveDataTableTypes.h
USTRUCT(BlueprintType)
struct FMonsterPatternRow : public FTableRowBase
{
    // ... 기존 필드 ...

    // 에픽 몬스터 전용 확장 필드 (일반/보스는 기본값 nullptr/None)
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TSubclassOf<AEnemyProjectile> ProjectileClass;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TSubclassOf<UGameplayEffect> StatusEffectClass;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    EProjectileSpawnPattern SpawnPattern = EProjectileSpawnPattern::Single;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FMonsterProjectilePatternConfig ProjectileConfig;
};

FMonsterProjectilePatternConfig에는 투사체 패턴 세부 설정을 데이터화했다:

USTRUCT(BlueprintType)
struct FMonsterProjectilePatternConfig
{
    UPROPERTY(EditAnywhere)
    int32 RadialProjectileCount = 8;       // RadialSpread 발수

    UPROPERTY(EditAnywhere)
    float SpreadSpeedMultiplierMin = 0.9f;

    UPROPERTY(EditAnywhere)
    float SpreadSpeedMultiplierMax = 1.2f;

    UPROPERTY(EditAnywhere)
    float GroundPillarSpawnDepth = -80.f;  // GroundPillar 지면 오프셋

    UPROPERTY(EditAnywhere)
    bool bRainFromAbove = false;

    UPROPERTY(EditAnywhere)
    bool bReflectable = false;
};

GA_ShootProjectiles.cpp 정리 후:

// 정리 후 - row에서 데이터만 읽음
void UGA_ShootProjectiles::ScheduleProjectiles(const FMonsterPatternRow* PatternRow)
{
    // C++ 분기 없음, 데이터 테이블이 결정
    TSubclassOf<AEnemyProjectile> ResolvedClass = PatternRow->ProjectileClass
        ? PatternRow->ProjectileClass
        : DefaultProjectileClass;

    switch (PatternRow->SpawnPattern)
    {
        case EProjectileSpawnPattern::RadialSpread:
            SpawnRadialVolley(ResolvedClass, PatternRow->ProjectileConfig.RadialProjectileCount,
                              PatternRow->ProjectileConfig.SpreadSpeedMultiplierMin,
                              PatternRow->ProjectileConfig.SpreadSpeedMultiplierMax);
            break;
        case EProjectileSpawnPattern::GroundPillar:
            SpawnGroundPillar(ResolvedClass, PatternRow->ProjectileConfig.GroundPillarSpawnDepth);
            break;
        default:
            SpawnSingle(ResolvedClass);
    }
}

EnemyCombatComponent.cpp 정리 후:

// 정리 후 - row 이름 분기 없이 DT의 Priority/MaxActivationRange/Cooldown만 읽음
bool UEnemyCombatComponent::CanActivatePattern(const FMonsterPatternRow* Row) const
{
    if (DistanceToTarget > Row->MaxActivationRange) return false;
    if (PatternCooldowns.Contains(Row->RowName) && PatternCooldowns[Row->RowName] > 0.f) return false;
    return true;
}

배운 점

공통 런타임 코드에 특정 몬스터 row 이름이 단 하나라도 들어가는 순간, 그 파일은 "특정 몬스터 전용 파일"과 다름없어진다. 기획이 바뀌거나 새 몬스터가 추가될 때마다 공통 코드를 고쳐야 하는 구조가 된다. 모든 몬스터별 특성은 DataTable row가 소유하고, 코드는 그 데이터를 읽기만 해야 한다.

---

2. 공통 StateTree Task에서 EpicMonsterCharacter 직접 의존 제거

배경

StateTreeTask_EnemyAttack.cpp, StateTreeTask_EnemyPatternAttack.cpp, StateTreeTask_ShiftOrbitSlot.cpp 안에 다음과 같은 코드가 있었다:

#include "Character/RetrieveEpicMonsterCharacter.h"

// ...

ARetrieveEpicMonsterCharacter* EpicChar = Cast<ARetrieveEpicMonsterCharacter>(EnemyChar);
if (EpicChar && EpicChar->UsesForwardLocomotion())
{
    EpicChar->UpdateGroundTurnAnimation(TurnRate);
}

공통 StateTree task가 파생 클래스인 ARetrieveEpicMonsterCharacter를 직접 include한다는 것은 의존 방향이 역전된 상태다. base → derived 참조는 곧 "base가 derived 없이는 빌드가 안 된다"는 뜻이 된다.

또한 일반/보스 몬스터에서 이 task가 실행될 때도 Cast 시도가 일어나고 실패하는 불필요한 연산이 생긴다.

해결 — Base에 no-op virtual 훅 추가

// RetrieveEnemyCharacter.h
UCLASS()
class RETRIEVE_API ARetrieveEnemyCharacter : public ACharacter
{
    // ... 기존 멤버 ...

    // 에픽 몬스터만 override, 일반/보스는 기본 no-op
    virtual bool UsesForwardLocomotion() const { return false; }
    virtual void UpdateGroundTurnAnimation(float TurnRate) {}
    virtual void StopGroundTurnAnimation() {}
    virtual bool HasAerialPhase() const { return false; }
};

// RetrieveEpicMonsterCharacter.h — override
virtual bool UsesForwardLocomotion() const override { return true; }
virtual void UpdateGroundTurnAnimation(float TurnRate) override;
virtual void StopGroundTurnAnimation() override;
virtual bool HasAerialPhase() const override { return true; }

StateTree task 정리 후:

// #include "Character/RetrieveEpicMonsterCharacter.h" 제거
// ARetrieveEpicMonsterCharacter* EpicChar = Cast<...> 제거

// base 훅만 호출 — Cast 없이 동작
if (EnemyChar->UsesForwardLocomotion())
{
    EnemyChar->UpdateGroundTurnAnimation(TurnRate);
}

이 변경으로 공통 StateTree task에서 에픽 헤더 include가 완전히 사라지고, 일반/보스 몬스터는 no-op 기본값을 타서 동작 변화가 없다.

배운 점

파생 클래스만의 동작이 공통 코드에 필요할 때는 반드시 base에 virtual 훅을 두고 파생 클래스에서 override하는 패턴으로 가야 한다. 공통 코드에서 파생 클래스로 Cast하는 순간 의존 방향이 역전되어 유지보수가 불가능해진다. no-op 기본 구현이 있는 virtual 함수는 기존 서브클래스의 동작을 전혀 건드리지 않으므로 항상 안전하다.

---

3. Build.cs 에디터 모듈 의존성 누락 수정

배경 및 증상

빌드를 실행하자 다음 에러가 순서대로 발생했다:

error C2027: use of undefined type 'FStateTreeCompilerLog'
error LNK2019: unresolved external symbol UAnimGraphNode_SequencePlayer
error LNK2019: unresolved external symbol FPropertyBindingPath

RetrieveConfigureEpicStateTreeCommandlet.cpp가 StateTree를 에디터에서 컴파일하는 API를 쓰고 있었는데, 해당 API가 선언된 헤더가 StateTreeEditorModule의 Public 경로에 있었다.

// RetrieveConfigureEpicStateTreeCommandlet.cpp
#include "StateTreeCompilerLog.h"  // StateTreeEditorModule/Public/ 아래 있음

그런데 Retrieve.Build.cs에 이 모듈이 없었다:

// 수정 전 — 에디터 모듈 의존성 누락
PrivateDependencyModuleNames.AddRange(new string[]
{
    "GameplayAbilities",
    "StateTreeModule",
    // StateTreeEditorModule 없음
});

해결

// 수정 후 — Editor 빌드에서만 추가
if (Target.Type == TargetRules.TargetType.Editor)
{
    PrivateDependencyModuleNames.AddRange(new string[]
    {
        "StateTreeEditorModule",   // FStateTreeCompilerLog, CompileStateTree API
        "AnimGraph",               // UAnimGraphNode_SequencePlayer
        "PropertyBindingUtils",    // FPropertyBindingPath
    });
}

AnimGraph와 PropertyBindingUtils는 첫 번째 빌드가 링크 단계까지 넘어간 뒤 연쇄적으로 발견되었다. 컴파일 단계 에러(헤더 미포함)와 링크 단계 에러(심볼 미정의)는 원인이 다르므로, 하나씩 순서대로 잡아야 한다.

배운 점

UE에서 에디터 전용 타입/API를 쓸 때는 두 가지를 반드시 확인해야 한다: (1) 해당 헤더가 어느 모듈의 Public 디렉토리에 있는지, (2) 그 모듈이 Build.cs의 에디터 조건 블록에 포함되어 있는지. 컴파일 에러는 헤더 경로 문제, 링크 에러는 심볼 소유 모듈 문제다. editor-only 의존성은 반드시 Target.Type == Editor 조건으로 감싸야 패키징 빌드가 깨지지 않는다.

---

4. DataTable 필드명 호환성 복구 및 develop 구조 정렬

배경

작업 도중 FMonsterPatternRow 필드명이 다음처럼 rename되어 있었다:

기존 이름 (develop 기준)	작업 중 변경된 이름
AttackSequence	SequenceAnimation
HitboxWindowStartTime	HitboxStartTime
HitboxWindowDuration	HitboxDuration

이 rename은 DataTable 바이너리(.uasset)에 저장된 기존 값과 C++ struct 필드명이 불일치해서, 에디터에서 열 때 기존 일반/보스 몬스터 row의 값이 전부 날아가는 결과를 초래한다.

origin/develop을 확인해보니 이 필드들은 이미 develop에도 기존 이름 그대로 있었고, rename이 필요한 이유가 없는 상태였다.

복구

// 기존 필드명으로 복구
UPROPERTY(EditAnywhere, BlueprintReadWrite)
UAnimSequence* AttackSequence = nullptr;       // SequenceAnimation X

UPROPERTY(EditAnywhere, BlueprintReadWrite)
float HitboxWindowStartTime = 0.f;             // HitboxStartTime X

UPROPERTY(EditAnywhere, BlueprintReadWrite)
float HitboxWindowDuration = 0.3f;             // HitboxDuration X

DropRow 구조 정렬 문제

origin/develop을 확인하는 과정에서 FMonsterDataRow::DropRow 단수가 DropRows TArray로 바뀌어 있음을 발견했다. 현재 작업 브랜치는 단수 구조를 유지하고 있어서 DropComponent와 타입 불일치가 발생했다.

그러나 이 변경은 에픽 몬스터 구현 범위와 무관하고, 함부로 develop 구조로 맞추면 DropComponent 전체가 연쇄적으로 바뀌어야 하는 문제가 있었다. 따라서 Drop 쪽은 에픽 작업 커밋에서 제외하고 기존 단수 구조를 유지하기로 결정했다.

// 에픽 커밋 범위에서는 기존 단수 구조 유지
UPROPERTY(EditAnywhere, BlueprintReadWrite)
FName DropRow;  // DropRows TArray는 별도 PR에서 처리

배운 점

DataTable row 필드명은 C++ struct와 .uasset 바이너리가 동시에 바뀌어야 한다. C++만 rename하면 에디터에서 기존 row 값 전체가 소멸된다. develop에 이미 있는 필드를 "새로 추가해야 한다"고 착각하지 않으려면 머지/커밋 전에 항상 git show origin/develop:해당파일로 원격 버전을 먼저 확인해야 한다.

---

5. develop 머지 충돌 해결 전략

충돌 파일 분류

feature/epic-monster-0616에 develop을 머지하자 충돌이 두 종류로 발생했다.

바이너리 충돌 (줄 단위 병합 불가):

• Content/Retrieve/Data/DT_MonsterData.uasset
• Content/Retrieve/Data/DT_MonsterPattern.uasset
• Content/Retrieve/AI/Test/EnemyTestMap.umap

소스 코드 충돌:

• Source/Retrieve/Data/RetrieveDataTableTypes.h
• Source/Retrieve/GameplayTags/RetrieveGameplayTags.h/.cpp
• Source/Retrieve/Character/RetrieveEnemyCharacter.h
• Source/Retrieve/AbilitySystem/Enemy/GAS/GA_ShootProjectiles.h/.cpp
• Source/Retrieve/AbilitySystem/Enemy/EnemyProjectile.h/.cpp
• Source/Retrieve/Components/Enemy/EnemyCombatComponent.cpp

바이너리 충돌 처리 원칙

바이너리 에셋은 줄 단위 병합이 불가능하다. "ours"를 선택하면 develop의 일반/보스 데이터 변경이 날아가고, "theirs"를 선택하면 에픽 row가 사라진다.

채택한 방식: develop 버전 선택 → 에픽 row는 후처리로 재적용

git checkout --theirs -- "Content/Retrieve/AI/Test/EnemyTestMap.umap"
git checkout --theirs -- "Content/Retrieve/Data/DT_MonsterData.uasset"
git checkout --theirs -- "Content/Retrieve/Data/DT_MonsterPattern.uasset"

에픽 row는 이후 Commandlet 또는 에디터에서 수동으로 재입력한다.

소스 코드 충돌 처리 원칙

각 파일별로 "develop 기존 기능 유지 + 에픽 확장만 추가"가 원칙이다.

RetrieveGameplayTags.h/.cpp:
양쪽 태그를 모두 살린다.

• develop 추가분: GameplayEvent_Enemy_SpecialAttack_Acceleration, GameplayEvent_Enemy_SpecialAttack_DashAttack
• 에픽 추가분: GameplayEvent_Enemy_SpecialAttack_ProjectileSpread

RetrieveEnemyCharacter.h:
양쪽을 합친다.

• develop 추가분: RefreshMoveSpeedFromAttribute()
• 에픽 추가분: HasAerialPhase(), UsesForwardLocomotion(), UpdateGroundTurnAnimation(), StopGroundTurnAnimation()

GA_ShootProjectiles.h/.cpp:
develop의 공격 속도 관련 로직을 유지하고 에픽 확장을 얹는다.

// develop에서 들어온 것 — 유지
float PlayRate = GetAttackMontagePlayRate(1.f);
float FireDelay = 0.f;
Combat->GetAttackDelay(PatternRow, FireDelay);

// 에픽에서 추가한 것 — 유지
TSubclassOf<AEnemyProjectile> Resolved = PatternRow->ProjectileClass
    ? PatternRow->ProjectileClass : DefaultProjectileClass;

EnemyProjectile.h/.cpp:
develop의 ShouldApplyDamageTo()(팀 판정) + 에픽의 HandleReflectedOverlap(), TryReflectOnHit() 둘 다 유지.

// 충돌 처리 순서 — 반사가 먼저, 팀 판정이 나중
void AEnemyProjectile::OnProjectileHit(...)
{
    if (HandleReflectedOverlap(OtherActor, SweepResult)) return;
    if (HasAuthority() && TryReflectOnHit(OtherActor, TargetASC)) return;
    if (HasAuthority() && DamageEffectClass && ShouldApplyDamageTo(OtherActor))
    {
        // 데미지 적용
    }
}

Unity Build 이름 충돌 문제

머지 완료 후 빌드를 돌리니 아래 에러가 발생했다:

error C2086: 'UAnimInstance *GetEnemyAnimInstance(...)': redefinition

익명 namespace 안의 헬퍼 함수 이름이 여러 파일에서 동일하게 선언되어 있었는데, Unity Build에서 같은 번역 단위로 묶이면서 이름이 충돌한 것이었다.

해결: 파일별로 고유한 이름으로 rename

// StateTreeTask_EnemyAerialPhase.cpp
namespace { UAnimInstance* GetEnemyAnimInstanceAerial(ACharacter* Char) { ... } }

// StateTreeTask_ShiftOrbitSlot.cpp
namespace { UAnimInstance* GetEnemyAnimInstanceOrbit(ACharacter* Char) { ... } }

// RetrieveConfigureEpicStateTreeCommandlet.cpp
namespace { const FString EpicCommandletStateTreePath = TEXT("..."); }

배운 점

바이너리 DataTable 머지에서는 욕심을 버려야 한다. "ours + theirs" 두 버전을 합치려 하면 반드시 에셋이 깨진다. develop 버전을 기준으로 받고 에픽 row만 재주입하는 2단계 방식이 항상 안전하다. Unity Build에서는 익명 namespace 헬퍼도 파일 간에 이름이 겹치면 충돌한다 — 파일 이름을 접미사로 붙이는 습관이 필요하다.

---

6. 에픽 기본 공격 태그 누락 버그

증상

에픽 몬스터가 기본 공격을 전혀 하지 않는 것처럼 보임.

원인 분석

일반 몬스터의 기본 공격 흐름:

StateTree → EnemyAttack task → GA_EnemyBasicAttack 발동 → UAbilitySystemComponent가 몽타주 재생
                                                          → GAS가 자동으로 State_Enemy_Attack 태그 부여

에픽 몬스터의 기본 공격 흐름 (AttackMontage 없을 때):

StateTree → EnemyAttack task → EnemyCombatComponent::RequestPatternByPriority()
                              → AttackSequence로 동적 몽타주 생성 및 재생
                              → GAS 개입 없음 → State_Enemy_Attack 태그 미부여

State_Enemy_Attack 태그가 없으면:

• ABP가 "공격 중"으로 인식하지 못해 로코모션 몽타주를 정상적으로 재생
• 로코모션 몽타주가 기본 공격 몽타주를 덮어씀
• 결과적으로 애니메이션이 취소되면서 공격이 안 되는 것처럼 보임

해결

EnemyCombatComponent.cpp에서 시퀀스 기반 기본 공격 경로에 태그 수명 관리를 직접 추가했다.

// EnemyCombatComponent.h
private:
    bool bSequenceAttackTagApplied = false;

// EnemyCombatComponent.cpp
bool UEnemyCombatComponent::PlayAttackSequence(UAnimSequence* Sequence)
{
    UAnimMontage* DynamicMontage = CreateDynamicMontageFromSequence(Sequence);
    if (!DynamicMontage) return false;

    // GA를 거치지 않으므로 수동으로 공격 태그 부여
    if (AvatarASC && !bSequenceAttackTagApplied)
    {
        AvatarASC->AddLooseGameplayTag(RetrieveGameplayTags::State_Enemy_Attack);
        bSequenceAttackTagApplied = true;
    }

    FOnMontageEnded EndDelegate;
    EndDelegate.BindUObject(this, &UEnemyCombatComponent::OnSequenceAttackMontageEnded);
    AvatarAnimInstance->Montage_Play(DynamicMontage);
    AvatarAnimInstance->Montage_SetEndDelegate(EndDelegate, DynamicMontage);

    return true;
}

void UEnemyCombatComponent::OnSequenceAttackMontageEnded(UAnimMontage* Montage, bool bInterrupted)
{
    // 내가 붙인 태그만 제거 (GA가 붙인 태그는 건드리지 않음)
    if (AvatarASC && bSequenceAttackTagApplied)
    {
        AvatarASC->RemoveLooseGameplayTag(RetrieveGameplayTags::State_Enemy_Attack);
        bSequenceAttackTagApplied = false;
    }
}

bSequenceAttackTagApplied 플래그를 사용해서, "내가 붙인 태그"와 "GA가 붙인 태그"를 구분한다. 시퀀스 공격 도중 GA 기반 공격이 발동되어 태그가 이미 있더라도 잘못 제거하지 않도록 한다.

몽타주 재생 자체가 실패할 경우에도 태그가 남지 않도록:

bool UEnemyCombatComponent::PlayAttackSequence(UAnimSequence* Sequence)
{
    // ...
    bool bPlayed = (AvatarAnimInstance->Montage_Play(DynamicMontage) > 0.f);
    if (!bPlayed)
    {
        // 재생 실패 — 붙인 태그 즉시 회수
        if (bSequenceAttackTagApplied)
        {
            AvatarASC->RemoveLooseGameplayTag(RetrieveGameplayTags::State_Enemy_Attack);
            bSequenceAttackTagApplied = false;
        }
        return false;
    }
    return true;
}

배운 점

UE GAS에서 태그 부여·해제는 GA(GameplayAbility)를 통할 때만 자동으로 보장된다. GA를 거치지 않고 직접 몽타주를 재생하거나 로직을 실행하는 경로에서는 관련 태그도 직접 관리해야 한다. "내가 붙인 태그"와 "남이 붙인 태그"는 반드시 구분 플래그로 추적해야 잘못된 해제를 막을 수 있다.

---

7. 그로기 시스템 3종 버그 수정

버그 1 — EpicMonsterGroggyComponent 미부착 문제

증상

강공격 3회를 맞혀도 그로기가 걸리지 않고, 그로기 게이지 UI도 전혀 보이지 않음.

원인

ARetrieveEpicMonsterCharacter C++ 생성자에서 EpicMonsterGroggyComponent를 CreateDefaultSubobject로 생성하지 않고 있었다. 이 컴포넌트는 블루프린트(BP_Dragon, BP_Magma, BP_Treant)에서 수동으로 붙이는 구조였는데, 머지 과정에서 BP 에셋이 develop 버전으로 선택되면서 컴포넌트 설정이 빠졌다.

해결

// RetrieveEpicMonsterCharacter.cpp 생성자
ARetrieveEpicMonsterCharacter::ARetrieveEpicMonsterCharacter()
{
    // 기존 컴포넌트들 ...

    // C++ 기본 컴포넌트로 등록 — BP에 의존하지 않음
    EpicGroggyComponent = CreateDefaultSubobject<UEpicMonsterGroggyComponent>(TEXT("EpicGroggyComponent"));
}

BP에서 붙이는 방식은 해당 BP 에셋이 없거나 덮어써지면 바로 동작이 깨진다. C++에서 CreateDefaultSubobject로 등록하면 어떤 BP라도 상속받는 순간 컴포넌트가 보장된다.

---

버그 2 — 그로기 태그 미적용 문제

증상

게이지가 꽉 차도 몬스터가 그로기 상태로 전환되지 않음.

원인

EpicMonsterGroggyComponent가 게이지가 차면 GameplayEvent_GroggyTrigger 이벤트만 보내고 있었는데, 이 이벤트를 수신해서 실제로 State_Enemy_Groggy 태그를 붙이는 GA/GE가 어디에도 없었다.

// 기존 코드 — 이벤트만 보내고 끝
void UEpicMonsterGroggyComponent::OnGaugeMaxReached()
{
    FGameplayEventData Payload;
    UAbilitySystemBlueprintLibrary::SendGameplayEventToActor(
        GetOwner(), RetrieveGameplayTags::GameplayEvent_GroggyTrigger, Payload);
    // 이 이벤트를 받는 GA가 없었음
}

해결

컴포넌트가 직접 State_Enemy_Groggy loose tag를 부여하고, duration 동안 Tick으로 남은 시간을 UI에 전달한 뒤 제거하도록 변경했다.

// EpicMonsterGroggyComponent.h
private:
    float GroggyDuration = 3.f;        // 기본 그로기 지속시간
    float ActiveGroggyDuration = 0.f;  // 현재 그로기의 실제 지속시간 (외부에서 다를 수 있음)
    float GroggyEndTime = 0.f;
    bool bGroggyActive = false;

public:
    void ApplyGroggyState(float OverrideDuration = -1.f);

// EpicMonsterGroggyComponent.cpp
void UEpicMonsterGroggyComponent::ApplyGroggyState(float OverrideDuration)
{
    if (bGroggyActive) return;

    // 외부(반사 투사체 등)에서 duration을 지정한 경우와 기본값을 구분
    ActiveGroggyDuration = (OverrideDuration > 0.f) ? OverrideDuration : GroggyDuration;
    GroggyEndTime = GetWorld()->GetTimeSeconds() + ActiveGroggyDuration;
    bGroggyActive = true;

    // GA/GE 없이 직접 태그 부여
    if (AvatarASC)
    {
        AvatarASC->AddLooseGameplayTag(RetrieveGameplayTags::State_Enemy_Groggy);
    }

    SetComponentTickEnabled(true);  // UI 갱신 Tick 활성화
    GroggyCounter = 0;              // 게이지 초기화
}

void UEpicMonsterGroggyComponent::TickComponent(float DeltaTime, ...)
{
    if (!bGroggyActive) return;

    float Remaining = GroggyEndTime - GetWorld()->GetTimeSeconds();
    if (Remaining <= 0.f)
    {
        // 그로기 종료
        if (AvatarASC)
        {
            AvatarASC->RemoveLooseGameplayTag(RetrieveGameplayTags::State_Enemy_Groggy);
        }
        bGroggyActive = false;
        SetComponentTickEnabled(false);
        OnGroggyEnded.Broadcast();
        return;
    }

    // UI에 남은 시간 비율 전달 (0.0 ~ 1.0)
    float Ratio = Remaining / ActiveGroggyDuration;
    OnGroggyGaugeUpdated.Broadcast(Ratio);
}

ActiveGroggyDuration을 별도 변수로 관리하는 이유: ApplyGroggyState(5.f)처럼 외부에서 override duration을 넣을 때 컴포넌트의 기본 GroggyDuration 설정값이 덮어써지는 것을 막기 위해서다.

---

버그 3 — 드래곤 반사 투사체 그로기 미발동

증상

드래곤의 투사체를 패링으로 반사시켜 드래곤에게 맞혀도 그로기가 걸리지 않음.

원인

EpicEnemyProjectile.cpp의 반사 적중 처리가 PatternCounterComponent의 현재 패턴 데이터에 의존하고 있었는데, 반사된 투사체가 드래곤 자신에게 맞을 때 PatternCounterComponent에 해당 패턴 정보가 없는 상태였다.

해결

PatternCounterComponent 데이터에 의존하지 않고 EpicMonsterGroggyComponent를 직접 호출하도록 변경.

// EpicEnemyProjectile.cpp
void AEpicEnemyProjectile::HandleReflectedHit(AActor* HitTarget)
{
    // 반사 투사체가 에픽 몬스터에 적중
    ARetrieveEpicMonsterCharacter* EpicMonster = Cast<ARetrieveEpicMonsterCharacter>(HitTarget);
    if (!EpicMonster) return;

    UEpicMonsterGroggyComponent* GroggyComp =
        EpicMonster->FindComponentByClass<UEpicMonsterGroggyComponent>();
    if (GroggyComp)
    {
        // 반사 적중은 즉시 그로기, 5초 지속
        GroggyComp->ApplyGroggyState(5.f);
    }
}

FindComponentByClass를 쓰는 이유: C++ 생성자에서 CreateDefaultSubobject로 등록했으므로 항상 존재가 보장되지만, 방어적 코드로 null 체크를 유지한다.

배운 점

C++ CreateDefaultSubobject는 "이 컴포넌트는 이 클래스의 불가분한 일부"라는 선언이다. BP에서만 붙이는 컴포넌트는 에셋 상태에 따라 없을 수도 있다. 시스템의 핵심 컴포넌트는 반드시 C++ 생성자에서 등록해야 한다. 그로기처럼 "조건 만족 → 즉시 발동"이 필요한 메커니즘은 GA/GE 체인 없이 컴포넌트가 직접 태그를 붙이는 것이 가장 간단하고 신뢰성이 높다.

---

8. Treant 특수 스킬 투사체/VFX 오류 수정

증상

• Treant의 특수 스킬(Treant_FloodBarrage)을 사용하면 의도와 전혀 다른 VFX가 재생됨.
• BP_TreantWaterPillarProjectile이 있음에도 공용 BP_WaterProjectile이 발사됨.

원인

두 단계의 문제가 겹쳐 있었다.

문제 1 — Commandlet이 Treant row를 공용 투사체로 설정

RetrieveConfigureEpicMonstersCommandlet.cpp에서 Magma와 Treant 모두 같은 투사체 경로를 쓰고 있었다:

// 잘못된 코드
static const FString WaterProjectileBlueprintPath =
    TEXT("/Game/Retrieve/AI/Boss/Projectiles/BP_WaterProjectile.BP_WaterProjectile_C");

// Treant 설정 시
PatternRow.ProjectileClass = LoadClass<AEnemyProjectile>(nullptr, *WaterProjectileBlueprintPath);

문제 2 — Commandlet이 투사체 VFX를 외부 에셋으로 덮어씀

Commandlet이 BP_TreantWaterPillarProjectile의 FlightVFX/ImpactVFX를 설정하는 과정에서 외부 패키지의 Waterfall Niagara 시스템으로 덮어쓰고 있었다.

해결

Commandlet에서 Treant 전용 투사체와 VFX를 명시적으로 분리했다:

// 수정 후
static const FString TreantWaterPillarProjectilePath =
    TEXT("/Game/Retrieve/AI/Boss/Projectiles/BP_TreantWaterPillarProjectile.BP_TreantWaterPillarProjectile_C");

static const FString TreantWaterPillarVFXPath =
    TEXT("/Game/Retrieve/AI/Boss/Projectiles/VFX/NS_Hanna_WaterPillar.NS_Hanna_WaterPillar");

// Treant FloodBarrage 패턴 설정 시
PatternRow.ProjectileClass = LoadClass<AEnemyProjectile>(nullptr, *TreantWaterPillarProjectilePath);
PatternRow.SpawnPattern = EProjectileSpawnPattern::GroundPillar;

// 투사체 VFX 설정 — Treant 전용 유지
ConfigureProjectileBlueprintVFX(
    TreantWaterPillarProjectilePath,
    TreantWaterPillarVFXPath,   // FlightVFX
    TreantWaterPillarVFXPath    // ImpactVFX
);

Commandlet 수정 후 실제 에셋에 반영하기 위해 실행:

attrib -R "Content\Retrieve\AI\Boss\Projectiles\BP_TreantWaterPillarProjectile.uasset"
attrib -R "Content\Retrieve\Data\DT_MonsterPattern.uasset"
& 'C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor-Cmd.exe' `
  'Retrieve.uproject' -run=RetrieveConfigureEpicMonsters -unattended -nop4

Commandlet 실행 로그에서 VFX가 의도한 경로로 저장된 것 확인:

[ConfigureEpicMonsters] BP_TreantWaterPillarProjectile: FlightVFX = NS_Hanna_WaterPillar
[ConfigureEpicMonsters] BP_TreantWaterPillarProjectile: ImpactVFX = NS_Hanna_WaterPillar

Commandlet 최종 삭제

이후에도 Commandlet을 다시 실행하면 수동으로 에디터에서 조정한 설정을 원복시키는 문제가 계속 발생했다. 에픽 몬스터 초기 설정 자동화 목적은 이미 달성된 상태였기 때문에 Commandlet 4개 파일을 삭제했다:

• Source/Retrieve/Commandlets/RetrieveConfigureEpicMonstersCommandlet.cpp
• Source/Retrieve/Commandlets/RetrieveConfigureEpicMonstersCommandlet.h
• Source/Retrieve/Commandlets/RetrieveConfigureEpicStateTreeCommandlet.cpp
• Source/Retrieve/Commandlets/RetrieveConfigureEpicStateTreeCommandlet.h

남은 Commandlets 폴더의 BonfireCommandlet, InteractionCommandlet은 기존 파트 파일이라 건드리지 않았다.

배운 점

Commandlet은 "한 번 실행하고 에셋에 구워진 뒤에는 필요 없어지는" 초기화 도구다. 하지만 코드로 남아 있으면 누구든 실수로 다시 실행할 수 있고, 그 순간 수동으로 조정한 에셋 설정이 전부 날아간다. 초기 자동화가 완료되면 반드시 삭제하거나 실행 조건에 안전 체크(예: "이미 설정된 경우 스킵")를 넣어야 한다.

---

9. HP Bar 동기화 문제 수정

증상

실제 체력과 HP Bar가 연동이 안 되는 경우가 간헐적으로 발생.

원인

NormalMonsterHealthBarComponent가 BeginPlay에서 단 한 번만 바인딩을 시도했다. 에픽 몬스터처럼 AbilitySystemComponent 초기화가 BeginPlay 이후에 완료되는 경우, 첫 번째 바인딩 시도 때 ASC가 준비되지 않아 델리게이트 연결이 실패한다. 이후에 ASC가 준비되어도 재바인딩 코드가 없어서 체력이 영영 연동되지 않는다.

// 기존 코드 — 한 번만 시도
void UNormalMonsterHealthBarComponent::BeginPlay()
{
    Super::BeginPlay();
    InitializeWithASC();  // ASC가 없으면 그냥 실패하고 끝
}

해결

바인딩 성공 여부를 추적하고, 실패한 경우 Tick에서 계속 재시도한다. 성공하면 Tick을 비활성화해 불필요한 연산을 줄인다.

// NormalMonsterHealthBarComponent.h
private:
    bool bHealthBound = false;

// NormalMonsterHealthBarComponent.cpp
void UNormalMonsterHealthBarComponent::BeginPlay()
{
    Super::BeginPlay();
    SetComponentTickEnabled(true);  // 바인딩 성공까지 Tick 유지
    TryBindToHealthComponent();
}

void UNormalMonsterHealthBarComponent::TickComponent(float DeltaTime, ...)
{
    if (bHealthBound) return;  // 이미 바인딩됐으면 즉시 리턴
    TryBindToHealthComponent();
}

void UNormalMonsterHealthBarComponent::TryBindToHealthComponent()
{
    URetrieveHealthComponent* HealthComp =
        GetOwner()->FindComponentByClass<URetrieveHealthComponent>();
    if (!HealthComp) return;

    UAbilitySystemComponent* ASC = HealthComp->GetAbilitySystemComponent();
    if (!ASC) return;

    // 델리게이트 바인딩
    ASC->GetGameplayAttributeValueChangeDelegate(
        URetrieveHealthAttributeSet::GetHealthAttribute())
        .AddUObject(this, &UNormalMonsterHealthBarComponent::OnHealthChanged);

    // 초기값 동기화
    float CurrentHP = HealthComp->GetHealth();
    float MaxHP = HealthComp->GetMaxHealth();
    RefreshHealthPercent(CurrentHP, MaxHP);

    bHealthBound = true;
    SetComponentTickEnabled(false);  // 바인딩 성공 — Tick 비활성화
}

배운 점

UE에서 컴포넌트 초기화 순서는 BeginPlay 시점에도 보장되지 않는다. 특히 GAS의 AbilitySystemComponent는 BeginPlay 이후에 설정되는 경우가 흔하다. 델리게이트 바인딩을 "BeginPlay 1회 시도"로만 구현하면 항상 타이밍 이슈가 생긴다. "성공할 때까지 매 틱 재시도 → 성공 시 Tick 비활성화" 패턴이 안정적이다. Tick 비용은 프레임당 bool 체크 하나라 무시 가능하다.

---

10. WBP_MonsterHealthBar 레이아웃 재정렬

목표

• 그로기 게이지가 화면에 잘 보이도록 위젯 가시성 설정
• 에픽 몬스터일 때 HP바/그로기 진행바가 프레임 안에 포함되는 레이아웃

접근 방식

기존 Monolith 에디터 유틸리티 패턴(RetrieveUIVFXEditorUtility)에 위젯 레이아웃 재구성 함수를 추가하고 Python 스크립트로 실행하는 방식을 사용했다.

// RetrieveUIVFXEditorUtility.h
UFUNCTION(BlueprintCallable, CallInEditor)
static bool ConfigureMonsterHealthBarLayoutAsset();

# Saved/ConfigureMonsterHealthBarLayout.py
import unreal
result = unreal.RetrieveUIVFXEditorUtility.configure_monster_health_bar_layout()
unreal.EditorAssetLibrary.save_asset('/Game/Retrieve/UI/WBP_MonsterHealthBar', False)

중간에 발생한 문제와 해결 과정

문제 1 — ResetWidgetTree 후 이름 충돌

ResetWidgetTree() 후 같은 이름으로 위젯을 재생성하면 패키지 오브젝트 이름이 UPackage에 남아 충돌이 발생했다.

Cannot replace object 'FRA_Vignette' — different class

외부 패키지에서 임포트된 FRA_Vignette(Monolith 프레임 위젯)는 커스텀 클래스라서, 같은 이름으로 Border 타입의 새 오브젝트를 만들 수 없었다.

해결 방향: 기존 트리를 통째로 비우지 않고 기존 위젯을 재사용하거나 폐기 이름으로 rename한 뒤 새 구조를 재생성하는 방식으로 전환.

문제 2 — stale GUID 참조로 인한 Blueprint Compile ensure

기존 위젯을 유지한 채 재배치하는 방식에서 외부 프레임 위젯의 stale GUID 참조가 Blueprint Compile 단계에서 ensure를 발생시켰다. 강제 Compile 호출을 제거하고 저장만 하는 방식으로 전환했더니 저장 자체는 성공했다(Configure result: True, Save result: True).

최종적으로 기존 위젯을 폐기 이름으로 rename 후 새 구조로 재생성하는 방식으로 stale GUID 문제까지 해소했다.

최종 위젯 구조

WBP_MonsterHealthBar (UUserWidget)
└── CanvasPanel (Root)
    ├── FRA_Frame  (외부 프레임 — T_FantasyWarrior_Bar_Horizontal08 텍스처 적용)
    │   └── FRA_Vignette
    ├── HPBar (UProgressBar)            ← 체력 바인딩
    ├── GroggyProgressBar (UProgressBar) ← 그로기 게이지 바인딩
    ├── Text_MonsterName (UTextBlock)
    └── Text_HPValue (UTextBlock)

프레임 텍스처 적용:
HP바와 그로기 게이지를 감싸는 프레임으로 기존 UIFantasyWarriorHUD 팩의 가로형 바 텍스처를 사용했다.

Content/External/UIFantasyWarriorHUD/Textures/FantasyWarrior/T_FantasyWarrior_Bar_Horizontal08.uasset

이 텍스처를 FRA_Frame 위젯의 브러시로 설정해서 HP바/그로기 게이지가 프레임 안에 자연스럽게 배치되도록 했다.

그로기 게이지 표시 처리:

기존에는 NormalMonsterHealthBarComponent가 평소 HiddenInGame 상태라서 그로기 이벤트가 와도 게이지가 보이지 않았다. 그로기 게이지 충전 또는 그로기 상태 활성화 시 컴포넌트를 강제로 표시하고, 그로기가 끝날 때 다시 숨기도록 수정했다.

void UNormalMonsterHealthBarComponent::HandleGroggyGaugeUpdated(float Ratio)
{
    // 그로기 게이지가 갱신될 때 바가 보이지 않으면 강제로 표시
    if (IsHiddenInGame())
    {
        SetHiddenInGame(false);
        // 그로기 중에는 숨김 타이머 취소
        GetWorld()->GetTimerManager().ClearTimer(HideTimerHandle);
    }

    if (Widget)
    {
        Widget->UpdateGroggyGauge(Ratio);
    }
}

런타임 위젯 바인딩 타입 확장:

기존 FRA_Frame, FRA_Vignette를 UUserWidget*으로 선언해서 외부 프레임 클래스는 잡히지 않던 문제를 UWidget*으로 타입을 풀어서 해결했다.

// 수정 전 — 커스텀 외부 프레임 위젯을 잡지 못함
UPROPERTY(BlueprintReadOnly, meta = (BindWidgetOptional))
UUserWidget* FRA_Frame;

// 수정 후 — 어떤 위젯 타입이든 잡힘
UPROPERTY(BlueprintReadOnly, meta = (BindWidgetOptional))
UWidget* FRA_Frame;

검증 결과

• RetrieveEditor Win64 Development 빌드 성공
• ConfigureMonsterHealthBarLayout.py 스크립트 실행: Configure result: True, Save result: True
• 로그: Success - 0 error(s), 0 warning(s)
• 그로기 게이지가 화면에 정상 표시되고 그로기 상태 동작 확인
• 에픽 몬스터 HP바/그로기 게이지가 프레임 안에 포함된 레이아웃 확인

참고: git status 기준으로 Content/Retrieve/UI/WBP_MonsterHealthBar.uasset은 ??(Untracked)로 잡힌다. PR에 포함하려면 git add 시 이 파일도 함께 stage해야 한다.

배운 점

ResetWidgetTree() 후 같은 이름으로 새 위젯을 만드는 것은 UE에서 안전하지 않다. 패키지 오브젝트 이름은 트리를 비워도 UPackage에 남아 있어 이름 충돌이 발생한다. 기존 위젯을 폐기 이름으로 rename한 뒤 새 구조를 재생성하거나, 처음부터 완전히 새 이름을 쓰는 것이 안전하다. UUserWidget* 바인딩은 외부 패키지의 커스텀 위젯 클래스를 잡지 못하므로, 외부 프레임/장식 위젯은 UWidget*으로 선언해야 한다.

---