📘TIL - 배경 NPC AI·대화 & 일시정지/조작키 UI

목차

1. 마을 배경 NPC 순찰 — StateTree 기반 신규 AI 구현
2. NPC 대화 확장 — 몽타주 재생, 아이템 보상, 대화 중 정지
3. 일시정지 메뉴 — 순수 게임플레이 ESC와 배타 패널 시스템 편입
4. 패키지에서 조용히 사라진 패널 — TSoftClassPtr와 쿠킹 경로
5. 메뉴 버튼 배선 — 기존 진입점 재사용으로 설정·조작키 안내 연결
6. 조작키 안내 위젯 — 실제 IMC 바인딩을 근거로 한 키맵 뷰
7. Live Coding의 경계 — 새 UPROPERTY·UFUNCTION은 정식 빌드가 필요

---

1. 마을 배경 NPC 순찰 — StateTree 기반 신규 AI 구현

목표

마을에 배치된 배경 NPC가 스폰 지점 주변을 자연스럽게 돌아다니게 한다. 참고 자료(D3kryption의 UE5 State Tree 순찰 가이드)의 "Move To Random Location 반복" 개념을 이 프로젝트의 StateTree 아키텍처에 맞게 적용한다.

원인 — NPC 베이스 클래스에 AI 자체가 없었음

ARetrieveNPCCharacter(상점 NPC 등 비전투 NPC 공용 베이스)는 AIControllerClass = nullptr로 설정돼 있어 컨트롤러 자체가 없는 완전 정적 상태였다. Enemy/Lumen 쪽에는 이미 StateTree AI(UStateTreeAIComponent + 커스텀 Task/Evaluator)가 있었지만 전투 판정(공격 사거리, 인카운터 슬롯, 조우 로직)에 강하게 결합돼 있어 그대로 재사용할 수 없었다. 처음엔 이 작업을 Enemy 쪽 폴더에 잘못 시작했다가("몬스터 순찰"로 오해), 사용자가 "NPC와 Enemy는 별개"라고 정정해 방향을 바로잡았다 — 역할이 다른 액터는 처음부터 다른 클래스 계층에서 시작해야 한다는 걸 다시 확인한 순간이었다.

해결 — Enemy와 완전히 분리된 최소 StateTree AI

// ARetrieveVillagerCharacter : ARetrieveNPCCharacter
ARetrieveVillagerCharacter::ARetrieveVillagerCharacter(const FObjectInitializer& ObjectInitializer)
    : Super(ObjectInitializer)
{
    AIControllerClass = ANPCPatrolAIController::StaticClass();
    if (UCharacterMovementComponent* MovementComp = GetCharacterMovement())
    {
        MovementComp->bOrientRotationToMovement = true;
        MovementComp->RotationRate = FRotator(0.f, 180.f, 0.f);
        MovementComp->MaxWalkSpeed = 250.f;          // 여유롭게 걷는 속도
        MovementComp->MaxAcceleration = 400.f;        // 완만한 가감속
        MovementComp->BrakingDecelerationWalking = 400.f;
    }
}

ANPCPatrolAIController는 Perception·Team 없이 UStateTreeAIComponent 하나만 구동하는 최소 컨트롤러다. FStateTreeTask_VillagerPatrol은 Evaluator 없이 Task 하나만으로 무한 루프를 도는 가장 단순한 구조로 짰다 — EnterState에서 스폰 위치를 한 번만 캡처해 캐싱하고, PatrolOrigin 반경 내 GetRandomReachablePointInRadius로 지점을 뽑아 이동, 도착(또는 MaxMoveTime 초과로 막힘 판정)하면 랜덤 시간만큼 대기 후 재선정한다. State가 하나뿐이라 전이(Transition) 정의도 필요 없다.

여기까지 오는 동안 실제로 겪은 버그 세 가지가 배울 점이 많았다.

1) 옆으로 미끄러지듯 걷는 버그. CharacterMovement->bOrientRotationToMovement = true(캐릭터 스스로 이동 방향으로 회전)로 설정해놓고 MoveToLocation의 bCanStrafe는 false로 넘겼다. bCanStrafe=false는 "AIController가 회전을 대신 통제하겠다"는 신호라, 두 회전 주체가 충돌해 미끄러지는 이동이 나왔다. bCanStrafe=true로 맞춰 회전 권한을 CharacterMovement 하나로 통일하니 해결됐다.

2) 그래도 남아있던 옆/뒤 걸음 버그 — 메쉬 회전 보정 누락. bCanStrafe 수정 후에도 증상이 남아 있었다. 정지 상태에선 절대 드러나지 않는 버그라, Monolith로 기존에 잘 동작하던 BP_ShopNPC_General의 Mesh 컴포넌트 RelativeRotation을 비교해보니 Yaw ≈ 90°로 보정돼 있었다. 새로 만든 Villager BP는 이 보정값이 Yaw=0으로 비어 있었던 것 — 이 캐릭터 메쉬(스켈레톤)가 원래 요구하는 보정값을 그대로 안 가져온 게 진짜 원인이었다. 같은 값으로 맞추자 바로 해결.

# Monolith Python: Rotator 생성자 인자 순서 함정
# unreal.Rotator(0, 89.999999, 0) → 실제로는 Pitch=90, Yaw=0으로 들어감!
mesh.set_editor_property('relative_rotation', unreal.Rotator(roll=0.0, pitch=0.0, yaw=89.999999))

3) 정지 상태에선 문제없다가 움직이면서만 드러나는 버그는 "정지 상태" 자체가 원인 은폐 조건이다. 상점 NPC는 절대 움직이지 않으므로 메쉬 회전 보정이 틀려도 티가 안 났다. 새로운 동작(이동)을 얹을 때는 기존에 그 동작을 한 번도 해보지 않은 애셋의 숨은 전제(스켈레톤 바인드 방향, 회전 보정값)를 의심해야 한다.

배운 점

역할이 다른 액터는 코드 시작 지점부터 분리한다. "순찰"이라는 요청만 보고 기존 Enemy StateTree 인프라에 손을 대기 시작했다가, 실제로는 완전히 새 폴더(Source/Retrieve/NPC/)에 독립된 Controller/Task를 만드는 게 맞는 방향이었다. 전투 AI와 배경 AI는 요구사항이 근본적으로 다르므로(타깃팅 여부, 인카운터 슬롯 여부) 처음부터 갈라두면 이후 로직이 훨씬 단순해진다.
"정지 상태에서만 써온 애셋"을 움직이는 용도로 재사용할 때는 그 애셋이 이동을 한 번도 검증받은 적 없다는 걸 전제해야 한다. 메쉬 회전 보정처럼 시각적으로만 드러나는 버그는 코드 리뷰로는 못 잡고, 반드시 실제로 움직여봐야 발견된다.

---

2. NPC 대화 확장 — 몽타주 재생, 아이템 보상, 대화 중 정지

목표

상점 NPC에 이미 있던 대화 시스템을 마을 NPC에도 적용하되, NPC마다 다른 대사·반응 애니메이션·보상을 가질 수 있게 하고, 일부 NPC는 여러 턴의 대화(다회차 대화)와 대화 종료 시 랜덤 아이템 지급까지 지원한다.

원인 — 이미 있는 기능과 없는 기능이 섞여 있었음

조사해보니 DT_Dialogue(SpeakerTag·TopicId·Lines·FollowUpRows 기반 트리 구조)와 URetrieveDialogueComponent(NPC별 EditAnywhere로 대사·애니메이션 지정)는 이미 완성돼 있어서 다회차 대화나 NPC별 차별화는 사실 데이터 작업만으로 충분했다. 반면 실제로 없던 것은 세 가지: (1) 마을 NPC는 InteractionResponse/InteractionTarget 컴포넌트가 없어 애초에 말을 걸 수조차 없었고, (2) 대화 종료 시 아이템을 지급하는 로직이 전혀 없었고, (3) "몽타주 재생"은 기존 코드가 PlayAnimation(싱글노드, AnimSequence용)만 지원해 진짜 몽타주(섹션·블렌드)는 못 썼다.

해결 — AnimBP Slot 기반 몽타주 + 가중치 아이템 보상

// URetrieveDialogueComponent::PlayGreetingAnimation
if (GreetingMontage)
{
    // Slot 재생은 AnimBP 상태머신(Idle/Run 블렌드)을 그대로 둔 채 위에 얹힌다.
    // 순찰 중인 Villager도 이동 애니메이션이 끊기지 않는다.
    if (UAnimInstance* AnimInstance = CachedMesh->GetAnimInstance())
    {
        AnimInstance->Montage_Play(GreetingMontage);
        return;
    }
}

기존 PlayAnimation 방식(대사 시작 시 CachedMesh->PlayAnimation(TalkingAnimation, true))은 AnimBP를 Single Node 모드로 강제 전환해버려 상태머신이 멈춘다. 정지 상태인 상점 NPC는 이래도 티가 안 나지만, 순찰 중인 Villager에게 쓰면 대화 도중 걷기 애니메이션이 얼어붙는다. Montage_Play는 AnimBP가 이미 갖고 있던 DefaultSlot 노드로 재생되므로 상태머신을 건드리지 않는다 — 기존 Animation/TalkingAnimation 필드는 그대로 두고 Montage 필드를 옵션으로 추가해, 값이 있으면 Slot 재생, 없으면 기존 방식으로 폴백하게 해서 상점 NPC 쪽은 전혀 건드리지 않았다.

bool URetrieveDialogueComponent::TryGrantItemReward(AActor* Instigator)
{
    if (ItemRewardPool.Num() == 0 || ItemRewardChance <= 0.f) return false;
    if (FMath::FRand() > ItemRewardChance) return false;
    // 가중치 누적 후 굴려서 하나 선택 → Instigator의 InventoryComponent::AddItem 호출
}

ItemRewardChance 기본값을 0으로 둬서, 기존 NPC는 이 필드를 안 건드리는 한 지급이 아예 발생하지 않는다. 호출 지점은 RetrievePlayerController::CloseConversation()(대화 종료 시점)으로, 기존에 있던 CompleteStepOnConversationEnd 퀘스트 완료 로직과 같은 자리에 얹었다.

여기서도 세 가지 버그를 실제로 겪었다.

1) 대사가 안 뜨는 버그 — DataTable 배열 필드 쓰기가 조용히 깨짐. Monolith의 add_data_table_row로 Lines(TArray\<FText>)와 FollowUpRows(TArray\<FName>)를 채웠는데, 툴은 "fields_set": 8로 성공을 보고했지만 실제로 저장된 값은 빈 문자열이었다. 편집기 로그에 "Json Value of type 'Array' used as a 'String'" 에러가 있었던 걸 뒤늦게 연결지었다. 검증은 항상 쓰기 결과를 그대로 믿지 말고 get_data_table_rows로 다시 읽어서 확인해야 한다는 걸 다시 배웠다.

# 복구: JSON 경로가 배열 필드에서 깨지므로 CSV 왕복으로 우회
csv_text = dt.export_to_csv_string()
rows = list(csv.reader(io.StringIO(csv_text)))
# Lines/FollowUpRows 컬럼만 직접 채워 넣고
dt.fill_from_csv_string(new_csv_text)  # 이 경로는 배열을 안 깨뜨림

2) 대화 중에도 순찰 이동이 안 멈추는 버그. StateTree는 대화 상태를 전혀 몰라서, 대화창이 떠 있어도 Villager가 계속 걸어 다녔다. ANPCPatrolAIController에 Deactivate()/Reactivate()를 추가해 URetrieveDialogueComponent::OpenConversationFor(대화 시작)에서 정지, ReturnToIdle()(대화 종료 콜백)에서 재개하도록 연결했다. AI 컨트롤러가 없는 상점 NPC는 Cast<ANPCPatrolAIController>가 실패하므로 자연히 아무 영향이 없다.

3) 상호작용 프롬프트 텍스트("Interact")를 못 바꾼 사례. Manager_InteractionTarget_C의 InteractionText 맵(TMap)을 새 값으로 덮어써도 여전히 "Interact"가 표시되고, 빈 상호작용 창이 겹쳐 보이는 새 증상까지 나타났다. BP 컴포넌트를 액터가 이미 레벨에 배치된 뒤에 추가하면 인스턴스가 구식 데이터를 들고 있을 수 있다는 가설로, 액터를 지우고 새로 배치해보는 절차로 넘겼다 — 이 부분은 세션이 종료되는 시점까지 결론이 나지 않아 다음 확인이 필요한 채로 남았다.

배운 점

쓰기 API가 성공을 보고해도, 배열/복합 타입 필드는 반드시 읽어서 재검증한다. DataTable의 TArray<FText>/TArray<FName> 필드처럼 JSON 직렬화가 까다로운 타입은 "성공" 응답과 실제 저장 값이 다를 수 있다. CSV 왕복처럼 더 안정적인 우회 경로를 알아두면 막혔을 때 바로 대체 수단으로 쓸 수 있다.
기존 방식을 대체하지 말고 옵션으로 얹으면 회귀 위험이 없다. PlayAnimation 위에 Montage 필드를 옵션으로 추가한 것처럼, 새 기능은 기본값에서 기존 동작을 그대로 재현하게 만들면 이미 동작하던 7종의 상점 NPC를 하나도 건드리지 않고 신규 NPC 타입에만 새 기능을 켤 수 있다.
AI 상태(대화 중)를 이동 시스템이 모르면 반드시 새서 나온다. 상호작용/대화 같은 "일시적으로 다른 시스템이 캐릭터를 점유하는" 상황은 이동 로직에 명시적으로 알려야 한다 — 이번엔 Deactivate/Reactivate 페어로 연결했지만, 이런 종류의 훅은 새 NPC 타입을 만들 때마다 빠지기 쉬운 지점이라 체크리스트화할 필요가 있다.

---

3. 일시정지 메뉴 — 순수 게임플레이 ESC와 배타 패널 시스템 편입

목표

전투 중 ESC를 누르면 일시정지 메뉴(계속하기 / 설정 / 조작키 안내 / 메인 메뉴로 / 게임 종료)가 뜨게 하고, 이미 존재하는 배타 패널 시스템(인벤토리·월드맵·상점과 같은 OpenExclusivePanel 흐름)에 자연스럽게 편입시킨다.

원인 — 게임플레이 중 ESC에 진입점이 없었고, 메뉴 위젯도 없었음

기존 ARetrievePlayerController::InputKey는 ESC를 패널이 열려 있을 때 닫는 용도로만 처리했다(if (ActivePanel && Key == Escape) CloseActivePanel()). 패널이 하나도 없는 순수 게임플레이 상태에서 ESC는 아무 동작도 하지 않았고, 일시정지 메뉴 위젯 자체도 없었다.

해결 — ESC 진입점 + C++ 베이스 위젯으로 버튼 배선을 코드에 고정

게임플레이 중(패널·퀵슬롯 휠 모두 없음) ESC를 OpenPauseMenu로 연결했다.

// 순수 게임플레이 중 ESC → 일시정지 메뉴
if (!ActivePanel && !bQuickSlotWheelOpen && Params.Key == EKeys::Escape)
{
    OpenPauseMenu();
    return true;
}

메뉴 위젯은 배타 패널의 공통 베이스(URetrieveGamePanelWidget)를 상속한 C++ 베이스로 만들어, 버튼 OnClicked 배선을 전부 코드에서 처리했다. WBP는 아래 이름의 버튼만 배치하면 그래프 배선 없이 동작한다.

UCLASS(Abstract, Blueprintable)
class URetrievePauseMenuWidget : public URetrieveGamePanelWidget
{
protected:
    virtual void NativeConstruct() override; // 각 버튼 OnClicked.AddDynamic

    UPROPERTY(meta = (BindWidgetOptional)) TObjectPtr<UButton> ResumeButton;   // RequestClose()
    UPROPERTY(meta = (BindWidgetOptional)) TObjectPtr<UButton> SettingsButton; // OpenSettingsPanel()
    UPROPERTY(meta = (BindWidgetOptional)) TObjectPtr<UButton> CommandsButton; // OpenControlsGuide()
    UPROPERTY(meta = (BindWidgetOptional)) TObjectPtr<UButton> MainMenuButton; // Server_RequestQuitToMenu()
    UPROPERTY(meta = (BindWidgetOptional)) TObjectPtr<UButton> QuitButton;     // QuitGame()
};

메뉴는 URetrieveGamePanelWidget 상속이라 ESC를 다시 누르면 베이스의 NativeOnKeyDown이 닫아준다. 처음엔 UGameplayStatics::SetGamePaused(true)로 실제 정지를 넣었다가, 멀티플레이에서는 한 클라이언트가 전체를 멈출 수 없으므로 걷어내고, 패널이 열린 동안 전투 입력만 클라이언트 로컬로 차단하는 기존 방식(PlayerTick의 if (!ActivePanel))에 맡겼다.

배운 점

위젯 버튼 배선은 그래프가 아니라 C++ BindWidgetOptional 베이스에 두면 도구 한계를 우회한다. Monolith 같은 자동화로 WidgetBlueprint의 OnClicked를 배선하는 건 불안정하지만, C++ 베이스가 이름으로 버튼을 잡아 핸들러를 붙이면 WBP는 버튼 이름만 맞추면 된다.
멀티플레이를 전제하면 "일시정지"는 시간 정지가 아니라 클라 로컬 UI다. SetGamePaused는 싱글에서만 의미가 있고, 네트워크에서는 입력 차단(클라 로컬)만으로 메뉴 UX를 만드는 편이 안전하다.

---

4. 패키지에서 조용히 사라진 패널 — TSoftClassPtr와 쿠킹 경로

목표

일시정지 메뉴가 에디터 PIE뿐 아니라 Standalone·패키징 빌드에서도 ESC로 뜨게 한다.

원인 — 소프트 참조만 있는 UI 폴더를 쿠커가 따라가지 않아 위젯이 미쿡됨

PIE에서는 되는데 Standalone/패키지에서 ESC를 눌러도 메뉴가 안 떴다. 로그의 결정적 단서는 Failed to open pause menu: PauseMenuClass is empty — 즉 입력·로직은 정상이고 PauseMenuClass.LoadSynchronous()가 null이었다. 확인해 보니 쿡된 폴더에 WBP_SettingsScreen은 있는데 WBP_PauseMenu는 아예 없었다. PauseMenuClass가 TSoftClassPtr인데, 이 프로젝트의 쿠커는 소프트 참조만 걸린 UI 폴더까지 따라가지 않아 대상 위젯을 패키지에 넣지 않았던 것이다(과거 F10 설정창도 똑같은 이유로 안 떴고 /Game/Retrieve/UI/Settings를 강제 쿡 목록에 넣어 고친 이력이 있었다).

해결 — 강제 쿡 등록 + 값은 C++ 생성자에 고정 + 런타임 경로 폴백(삼중 안전장치)

; DefaultGame.ini — TSoftClassPtr로만 참조되는 UI 폴더는 쿠커가 도달 못 함
+DirectoriesToAlwaysCook=(Path="/Game/Retrieve/UI/Menu")

값 자체도 툴로 넣은 CDO 오버라이드가 디스크에 안정적으로 직렬화되지 않아, 이미 잘 되는 SettingsPanelClass와 똑같이 C++ 생성자에 고정했다.

// 값은 코드에 박아 BP 직렬화·툴에 의존하지 않는다
PauseMenuClass = TSoftClassPtr<URetrieveGamePanelWidget>(
    FSoftObjectPath(TEXT("/Game/Retrieve/UI/Menu/WBP_PauseMenu.WBP_PauseMenu_C")));

// OpenPauseMenu — 값이 비어도(예: BP에 None 오버라이드) 알려진 경로로 폴백
TSubclassOf<URetrieveGamePanelWidget> PanelClass = PauseMenuClass.LoadSynchronous();
if (!PanelClass)
{
    PanelClass = LoadClass<URetrieveGamePanelWidget>(
        nullptr, TEXT("/Game/Retrieve/UI/Menu/WBP_PauseMenu.WBP_PauseMenu_C"));
}

진단의 핵심은 로그가 아니라 쿡 산출물 비교였다. Saved/Cooked/.../UI/Menu에 특정 위젯이 있는지/없는지가 "게임이 실제로 로드할 수 있는가"의 그라운드 트루스였고, 에디터 인메모리 CDO만 확인하면 계속 헛다리를 짚게 됐다.

배운 점

TSoftClassPtr로만 참조되는 UI 폴더는 DirectoriesToAlwaysCook에 등록해야 패키지에 들어간다. 소프트 참조는 하드 참조 체인이 없으면 쿠커가 누락할 수 있고, 그러면 에디터에서는 멀쩡한데 패키지에서만 조용히 사라진다.
"에디터에서 되는데 패키지에서 안 되면" 쿡 산출물을 직접 본다. 인메모리 상태는 디스크/쿡 상태와 다를 수 있으므로, Saved/Cooked에 에셋이 실제로 존재하는지가 판정 기준이 된다.
위젯 클래스 기본 할당은 도구가 아니라 C++ 생성자(또는 사람이 Details 패널에서) 고정한다. 인메모리 CDO에는 보여도 디스크 직렬화에 실패하는 경우가 있어, 재컴파일·재패키징 후 조용히 빈 값이 된다.

---

5. 메뉴 버튼 배선 — 기존 진입점 재사용으로 설정·조작키 안내 연결

목표

메인 메뉴의 "설정" 버튼과 일시정지 메뉴의 "조작키 안내" 버튼을 이미 있는 기능에 연결한다. 새 흐름을 만드는 게 아니라 기존 진입점을 재사용해 배선만 하는 것이 목표다.

원인 — 버튼이 명시적으로 비활성화돼 있거나 핸들러가 없었음

메인 메뉴의 OptionsButton은 NativeConstruct에서 SetIsEnabled(false)로 아예 죽어 있었고 클릭 핸들러도 없었다. 일시정지 메뉴의 CommandsButton(조작키 안내) 역시 위젯에는 배치돼 있었지만 대응하는 C++ 핸들러가 없어 눌러도 무반응이었다.

해결 — 죽은 버튼을 살려 OpenSettingsPanel / OpenControlsGuide에 연결

// RetrieveMainMenuWidget.cpp — 비활성화를 제거하고 기존 진입점에 연결
if (OptionsButton)
{
    OptionsButton->OnClicked.AddDynamic(this, &URetrieveMainMenuWidget::HandleOptionsClicked);
}

void URetrieveMainMenuWidget::HandleOptionsClicked()
{
    if (ARetrievePlayerController* PC = GetRetrievePlayerController())
    {
        PC->OpenSettingsPanel(); // F10과 동일한 진입점 재사용
    }
}

조작키 안내도 같은 패턴으로, PC에 OpenControlsGuide를 추가하고 그 안에서 배타 패널 시스템(OpenExclusivePanel)을 재사용했다. 두 경우 모두 패널 닫기 시 입력 모드 복원 로직이 이미 세션 상태별로 분기돼 있었던 덕을 봤다.

// RemoveActivePanelImmediately — 메인메뉴/결과 화면에서 연 패널은 UIOnly+커서 유지
if (SessionState == ERetrieveSessionState::MainMenu ||
    SessionState == ERetrieveSessionState::Result)
{
    UpdateInputMode(SessionState);
}
else { /* 인게임에서만 GameOnly로 복귀 */ }

즉 메인 메뉴에서 설정창을 열었다 닫아도 커서·키보드 조작이 죽지 않고 정상 복귀했다 — 신규 흐름을 위한 별도 처리가 필요 없었다.

배운 점

버튼이 "무반응"일 때 먼저 의심할 것은 배선이 아니라 활성 상태다. SetIsEnabled(false)로 막혀 있거나 핸들러가 아예 없는 경우가 흔하고, 이건 배선 로직을 아무리 봐도 안 보인다.
기존 진입점(OpenSettingsPanel / OpenExclusivePanel)을 재사용하면 신규 UI는 "배선"만 남는다. 입력 모드 복원처럼 세션 상태별 분기가 이미 마련돼 있으면, 새 화면을 그 흐름에 얹는 것만으로 엣지 케이스까지 공짜로 커버된다.

---

6. 조작키 안내 위젯 — 실제 IMC 바인딩을 근거로 한 키맵 뷰

목표

조작키 안내 화면을 만들되, 표에 들어가는 키는 디자인 목업이나 추측이 아니라 게임에 실제 매핑된 키로 채운다.

원인 — 참고 이미지의 키가 실제 바인딩과 달랐음

처음엔 참고 이미지의 조작표를 그대로 옮겼는데, 실제 게임과 어긋나는 곳이 많았다(이미지에선 E가 상호작용이었지만 실제로는 E=버스트·F=상호작용, R=방어, Tab=타겟 고정 등). "실제 키"의 근거를 코드/데이터에서 직접 뽑아야 했다.

해결 — Enhanced Input IMC_Default에서 매핑을 덤프하고 하드코딩 키와 합치기

UE5.7에서는 UInputMappingContext의 구 mappings 프로퍼티가 deprecated 되어 빈 배열을 반환한다. 새 경로(default_key_mappings → mappings)로 접근해 실제 IA→키를 덤프했다.

imc = unreal.load_asset('/Game/Retrieve/Input/IMC_Default')
# UE5.7: 구 'mappings'는 deprecated(빈 배열) → default_key_mappings 경유
ms = imc.get_editor_property('default_key_mappings').get_editor_property('mappings')
for m in ms:
    a = m.get_editor_property('action')
    k = m.get_editor_property('key')
    print(a.get_name(), '=>', k.get_editor_property('key_name'))
# IA_Move=>W/S/A/D, IA_Jump=>SpaceBar, IA_Attack=>LMB, IA_HeavyAttack=>RMB,
# IA_Guard=>R, IA_LockOn=>Tab, IA_Burst=>E, IA_Absorb=>Q,
# IA_ElementMode1/2/3=>1/2/3, IA_Interaction=>F, IA_UseItem1/2=>4/5, IA_Zoom=>휠 ...

IMC에 없고 PlayerController::InputKey에서 직접 처리되는 하드코딩 키(설정=F10, 퀵슬롯 휠=T, 미니맵 회전=N, 인벤=I, 월드맵=M, 일시정지=ESC)는 따로 취합해 합쳤다. 위젯은 URetrieveGamePanelWidget 상속으로 만들어 ESC로 닫히게 하고, 카테고리(이동/전투/원소/시스템)별 색상 코딩과 키캡 배치로 구성했다.

배운 점

"실제 조작"의 근거는 디자인 목업이 아니라 IMC와 코드의 하드코딩 키다. Enhanced Input을 쓰면 물리 키는 IMC에, 나머지는 컨트롤러의 InputKey 분기에 흩어져 있으므로 둘 다 훑어야 진짜 매핑이 나온다.
엔진 버전이 올라가면 데이터 접근 경로가 바뀐다. UE5.7의 IMC는 mappings(deprecated)가 아니라 default_key_mappings.mappings로 읽어야 하고, 이런 건 스키마를 직접 파헤쳐 확인해야 한다.

---

7. Live Coding의 경계 — 새 UPROPERTY·UFUNCTION은 정식 빌드가 필요

목표

위젯 버튼 배선 같은 C++ 변경을 에디터를 켠 채 빠르게(Live Coding) 반영하되, 반영이 되는 변경과 안 되는 변경을 구분한다.

원인 — 라이브 컴파일은 성공했는데 새 버튼만 무반응

"조작키 안내" 버튼용 CommandsButton(새 UPROPERTY)과 HandleCommandsClicked/OpenControlsGuide(새 UFUNCTION)를 추가하고 Live Coding으로 컴파일했는데, patch_applied가 떴는데도 그 버튼만 눌러도 무반응이었다. 반면 이전 정식 빌드에 이미 들어 있던 ResumeButton은 잘 동작했다.

해결 — 함수 본문은 라이브, 리플렉션 멤버 추가는 정식 재빌드

// 이런 "새 리플렉션 멤버"는 Live Coding으로 등록되지 않는다
UPROPERTY(meta = (BindWidgetOptional)) TObjectPtr<UButton> CommandsButton; // 클래스 레이아웃 변경
UFUNCTION() void HandleCommandsClicked();                                   // 신규 리플렉션 함수

Live Coding은 함수 본문 변경만 핫패치하고, 새 UPROPERTY/UFUNCTION처럼 클래스 레이아웃·리플렉션이 바뀌는 변경은 등록하지 못한다. 그래서 BindWidgetOptional이 CommandsButton을 채우지 못해 핸들러가 붙지 않았다. 해결은 단순하지만 확실하다 — 에디터를 닫고 정식 재빌드 후 재실행(또는 재패키징). 증상으로 원인을 구분할 수 있었다: 기존 바이너리에 있던 버튼은 되고, 라이브로 추가한 신규 멤버만 무반응.

배운 점

Live Coding은 "함수 본문 핫패치" 전용으로 생각한다. 새 UPROPERTY/UFUNCTION/BindWidget 멤버 추가는 정식 빌드가 필요하며, 라이브 컴파일이 성공(patch_applied)해도 리플렉션에는 반영되지 않는다.
"방금 추가한 것만 안 되고 기존 것은 된다"면 리플렉션 등록을 의심한다. 동일 메커니즘인데 신규 멤버만 죽어 있으면 배선 로직이 아니라 빌드 방식(라이브 vs 정식)의 문제다.

---

오늘의 핵심 요약

작업	핵심 문제	해결 원칙
마을 NPC 순찰 AI	NPC 베이스에 AI 자체가 없었고, 전투 AI(Enemy)에 결합해 재사용 불가	Enemy와 완전히 분리된 최소 StateTree(Task 1개, Evaluator 없음) 신설
이동 시 회전 버그	bCanStrafe/bOrientRotationToMovement 충돌 + 메쉬 회전 보정 누락	회전 권한을 한 주체로 통일 + 기존 정상 동작 애셋과 컴포넌트 값 비교로 원인 특정
NPC 대화 확장	몽타주 재생·아이템 보상 없음, 대화 중 이동 안 멈춤	AnimBP Slot 기반 몽타주(옵션 폴백), 확률 기반 보상, Deactivate/Reactivate 훅
DataTable 배열 필드	JSON 쓰기 경로가 배열 필드에서 조용히 실패	CSV export/fill 왕복으로 우회 + 쓰기 후 항상 재검증
일시정지 메뉴	게임플레이 중 ESC 진입점·메뉴 위젯 부재	ESC→OpenPauseMenu + C++ 베이스 위젯으로 버튼 배선을 코드에 고정, MP는 정지 대신 클라 로컬 입력 차단
패키지 미표시 패널	소프트 참조 UI 폴더를 쿠커가 누락	DirectoriesToAlwaysCook 등록 + 값은 C++ 생성자 고정 + 경로 폴백(삼중 안전장치)
메뉴 버튼 배선	버튼이 비활성/핸들러 부재	죽은 버튼을 살려 기존 진입점(OpenSettingsPanel/OpenExclusivePanel) 재사용
조작키 안내	참고 이미지가 실제 바인딩과 불일치	IMC_Default + 하드코딩 키에서 실제 매핑을 직접 덤프
Live Coding 한계	새 UPROPERTY/UFUNCTION 미반영	함수 본문만 라이브, 리플렉션 멤버 추가는 정식 재빌드

공통 교훈: 오늘 두 갈래 작업(배경 NPC, 일시정지/조작키 UI)은 결국 같은 원칙으로 수렴했다.

1. 있는 것과 없는 것을 정확히 가른다. 대화 트리·다회차 대화·설정창·배타 패널·입력모드 복원은 이미 있었고, AI·몽타주·아이템 보상·일시정지 진입점·조작키 위젯은 없었다. 있는 걸 다시 만들지 않고 없는 것만 얹으니, 상점 NPC 7종도 기존 메뉴 흐름도 하나 안 건드리고 신규 기능을 붙일 수 있었다.
2. 역할이 다른 액터·UI는 시작 지점부터 분리하고, 새 기능은 기존 동작을 기본값으로 재현하는 옵션으로 얹는다. Enemy에서 갈라낸 NPC AI, PlayAnimation 위에 얹은 Montage 옵션이 그 예다.
3. 문제는 대부분 코드가 아니라 툴체인의 경계에서 났다. DataTable 배열 쓰기, 쿠킹 누락, Live Coding의 리플렉션 한계, IMC 접근 경로 변경 — 모두 "쓰기 성공 응답 / 에디터에서 됨"을 믿는 순간 헛다리를 짚게 했다. 그래서 판정 기준을 "쓰고 나서 읽어 재검증했는가 / 쿡 산출물에 있는가 / 정식 빌드에 들어갔는가"로 바꾸는 것이 오늘 반복된 교훈이었다.