📘TIL-상점 UI 레이아웃 재구성 & NPC 포커스 카메라

작업 배경

상점(Shop) 시스템을 다듬으며 세 가지 주제를 다뤘다.

1. NPC 포커스 카메라: 상점을 열면 카메라가 NPC 정면으로 전환되고 플레이어 캐릭터는 일시적으로 숨겨지는 연출
2. 레이아웃 재구성: 상점 화면을 "중앙에 NPC가 보이고 좌/우·하단에 패널 카드가 떠 있는" 형태로 바꾸고, 그 과정에서 레이아웃을 누가 소유하는가(C++ vs WBP) 를 정리
3. 레이아웃 변경으로 드러난 버그/증상 수정: 흰 박스·텍스트, 좁은 영역에서의 넘침·겹침, 리스트 항목 붕괴, 닫기·상호작용 프롬프트, 빈약한 상세 정보

겉보기엔 "창 위치만 잡으면 되는" UI 작업 같지만, 카메라 뷰타깃 블렌드 → 패널 입력모드/닫기 경로 → 위젯이 런타임에 조립되는지 여부 → BindWidget 바인딩 → CanvasPanel의 크기 계산 방식까지 여러 시스템이 맞물려 있었다.

---

목차

1. NPC 정면 포커스 카메라
2. 카메라가 NPC 뒤를 비추는 문제
3. 상점 진입 시 수 초 멈춤
4. 닫기 버튼: 커서·조작·카메라 복귀
5. 레이아웃 소유권: 런타임 조립 vs WBP
6. 양피지 카드에서 텍스트·이미지가 흰색으로 보임
7. 좁은 카드에서의 텍스트·버튼 넘침/겹침
8. 리스트 항목이 겹치는 문제 (CanvasPanel 크기)
9. 상세 정보 풍부화
10. 상호작용 프롬프트 숨김
11. UMG 에셋을 자동화로 편집할 때 주의
12. 검증 결과
13. 배운 점
14. 다음에 비슷한 작업이 나면 볼 체크리스트

---

1. NPC 정면 포커스 카메라

요구사항

상점을 열면 카메라가 NPC 정면으로 부드럽게 전환되고, 플레이어 캐릭터는 숨겨져 NPC만 보인다. 닫으면 원래 시점으로 복귀.

분석

• 상점은 대화 시스템을 거쳐 컨트롤러(ARetrievePlayerController)에서 열린다. 이 시점에 상점 NPC 액터를 알 수 있다.
• NPC가 풀 캐릭터(자체 3인칭 카메라 리그 보유) 라, NPC를 그대로 카메라 뷰타깃으로 삼으면 NPC의 3인칭 카메라(뒤통수 너머)가 잡힌다. → NPC 앞쪽에 별도 카메라 액터를 스폰해 그 카메라를 비춰야 한다.

구현

Source/Retrieve/Player/RetrievePlayerController.cpp에 포커스/복귀 함수를 추가했다.

void ARetrievePlayerController::FocusCameraOnActor(AActor* TargetActor)
{
    const FVector NpcLoc  = TargetActor->GetActorLocation();
    const FVector Forward = TargetActor->GetActorForwardVector();
    const FVector Dir     = Forward.RotateAngleAxis(ShopCameraOrbitYaw, FVector::UpVector);
    const FVector CamLoc  = NpcLoc + Dir * ShopCameraDistance + FVector(0,0,ShopCameraHeight);
    const FVector LookAt  = NpcLoc + FVector(0,0,ShopCameraLookAtHeight);

    ShopFocusCameraActor->SetActorLocationAndRotation(CamLoc, (LookAt - CamLoc).Rotation());
    SetViewTargetWithBlend(ShopFocusCameraActor, ShopCameraBlendTime,
        EViewTargetBlendFunction::VTBlend_Cubic, 0.f, false);

    if (bHidePlayerDuringShopCamera)
        if (APawn* P = GetPawn()) P->SetActorHiddenInGame(true);
}

• 상점 열림 시 FocusCameraOnActor(상점NPC), 닫힘 시 RestorePlayerCameraView()(폰으로 복귀 + 폰 다시 표시).
• 닫기 처리는 모든 닫기 경로가 반드시 지나는 단일 함수(RemoveActivePanelImmediately)에 넣어 누락을 막았다.
• 카메라 액터는 BeginPlay에서 미리 스폰해 전환 순간의 스폰 비용을 없앴다.
• 카메라 구도는 모두 UPROPERTY로 빼서 에디터에서 리빌드 없이 조정 가능: ShopCameraDistance, ShopCameraHeight, ShopCameraLookAtHeight, ShopCameraOrbitYaw, ShopCameraBlendTime, bHidePlayerDuringShopCamera.

---

2. 카메라가 NPC 뒤를 비추는 문제

증상

카메라를 NPC의 정면 방향(GetActorForwardVector)에 두고 NPC를 바라보게 했는데 뒤통수가 보였다.

원인

이 NPC는 메시 정면이 액터의 Forward와 반대 방향이었다(캐릭터 메시가 액터 forward 대비 180° 회전된 흔한 경우). "앞"이라고 둔 위치가 실제로는 뒤였다.

수정

카메라 배치 방향을 회전 오프셋(ShopCameraOrbitYaw)으로 조정 가능하게 만들고 기본값을 180°로 뒀다. 메시 방향이 다른 NPC가 와도 값만 바꿔 맞출 수 있다(리빌드 불필요).

---

3. 상점 진입 시 수 초 멈춤

증상

상점을 여는 순간 화면이 수 초간 멈췄다가 한 번에 나타났다. 에디터(PIE)에서 첫 진입·상점에서만 심하고, 둘째부터는 빠르며, 인벤토리 등 다른 화면에는 없었다.

원인

• 상점 오픈 자체는 동기 즉시 실행이라 코드 경로에 수 초 지연 요소가 없다.
• "멈췄다가 한 번에"는 게임 스레드 블로킹의 전형이다. 첫 진입·상점에서만 나는 이유는, 카메라가 NPC(모듈러 캐릭터)를 가까이서 처음 렌더링하면서 그 머티리얼들의 셰이더를 그 자리에서 컴파일하기 때문이다. 인벤토리는 카메라를 바꾸지 않아 발생하지 않는다.

결론

에디터 전용 현상이며 패키징(쿡) 빌드에는 없다. 기능 버그로 오인해 코드로 무리하게 잡으려 하지 말 것. (전환 시점의 카메라 액터 스폰 비용만 미리 스폰으로 제거)

---

4. 닫기 버튼: 커서·조작·카메라 복귀

증상

상점 닫기(✕)를 눌러도 마우스 커서가 남고 플레이어 조작으로 돌아가지 않았다(카메라/플레이어 표시도 복귀 안 됨).

원인

닫기 핸들러가 패널을 RemoveFromParent()로 직접 제거해, 컨트롤러가 담당하는 정식 닫기 경로를 우회했다. 그 경로 안에서 입력모드 복귀·커서 숨김·카메라 복귀·플레이어 표시가 처리되는데 전부 건너뛴 것.

수정

패널이 스스로 닫지 않고 닫기 요청만 보내 컨트롤러가 마무리하게 위임했다.

void UShopPanelWidget::HandleCloseShopClicked()
{
    // 컨트롤러의 정식 닫기 경로로 위임 → 입력모드/커서/카메라/플레이어표시가 한 곳에서 복원됨
    RequestClose();
}

교훈: 부수 효과(입력·커서·카메라 등)가 따라붙는 닫기는 단일 경로로 모아야 한다. 위젯이 자기를 직접 제거하면 그 부수 효과가 통째로 누락된다.

---

5. 레이아웃 소유권: 런타임 조립 vs WBP

증상

원하는 카드 레이아웃을 WBP(WBP_ShopPanel)에서 만들었는데 화면에 전혀 반영되지 않았다.

원인

상점 위젯의 C++ NativeConstruct가 매번 런타임에 레이아웃을 다시 조립하고 있었다. 디자인 타임에 배치한 바운드 위젯들(목록/상세/인벤토리/대사)을 떼어내 코드로 만든 카드에 다시 담고, 닫기 버튼·통화 텍스트·타이틀바까지 코드로 생성하는 구조였다. 그래서 WBP에서 무엇을 바꿔도 실행하면 덮어써졌다.

해결: 레이아웃을 WBP로 옮기고 런타임 조립 코드를 제거

레이아웃 소유자를 WBP로 일원화하기로 하고, 깨짐 없이 옮기기 위해 이렇게 진행했다.

1. 런타임 조립 코드에 가드 추가 — WBP가 카드 루트(Canvas_ShopRoot)를 가지면 조립을 건너뛰게 해, 옮기는 도중에도 화면이 깨지지 않게 함.
2. WBP에 카드 레이아웃 구축 — Canvas_ShopRoot(CanvasPanel) 아래 카드 4개(Border, 양피지 배경)를 만들고 기존 바운드 위젯을 그 안으로 재배치, 비율 앵커로 화면에 배치.
3. 런타임 조립 코드 제거 — 더 이상 쓰지 않는 조립 로직을 삭제. 이때 닫기 버튼·통화 텍스트는 WBP 위젯이 되었으므로 C++에서는 이름으로 찾아 연결.

최종 구조(레이아웃은 WBP, C++은 데이터/로직만):

WBP_ShopPanel
└ Canvas_ShopRoot (화면 채움)
   ├ 구매 목록 카드   (좌측,   스크롤)
   ├ 상세 정보 카드   (우측 위)
   ├ 인벤토리/판매 카드(우측 아래)
   ├ NPC 이름·대사 카드(좌측 아래)
   └ 닫기(✕) 버튼     (우하단)
   (가운데는 비워 NPC가 보이게)

곁들여 발견한 함정: BindWidget 이름 충돌

닫기 버튼·통화 텍스트를 C++ BindWidget 멤버로 잡으려 했더니 WBP 컴파일이 실패했다.

Tried to create a property Button_Close ... but another object ... already exists there.

WBP의 변수 위젯명과 C++ 프로퍼티명이 같은데 바인딩이 정상적으로 잡히지 않으면 중복 생성 충돌이 난다. → C++ 멤버를 두지 않고 이름으로 위젯을 찾아 쓰면 이 충돌을 피한다.

if (UButton* CloseBtn = Cast<UButton>(GetWidgetFromName(TEXT("Button_Close"))))
    CloseBtn->OnClicked.AddDynamic(this, &UShopPanelWidget::HandleCloseShopClicked);

옮긴 직후의 붕괴: 카드가 상단 얇은 띠로 뭉침

• 원인: Canvas_ShopRoot가 세로 박스 안에 들어 있는데 슬롯 크기 규칙이 Auto라, CanvasPanel은 스스로 원하는 크기가 0이어서 높이 0으로 찌부됨.
• 수정: 그 슬롯을 Fill로 바꿔 캔버스가 화면을 채우게 하니 비율 앵커 카드들이 제 위치로 갔다.

---

6. 양피지 카드에서 텍스트·이미지가 흰색으로 보임

카드 배경을 밝은 양피지로 바꾸자 "흰색 묻힘 / 흰 박스" 계열 문제가 줄줄이 드러났다.

증상	원인	수정
카드 텍스트가 흰색으로 묻힘	밝은 양피지 + 밝은/흰 텍스트	카드 양피지에 어두운 틴트(어두운 갈색)를 넣어 대비 확보
상세 카드 전체가 흰색	상세 패널(Border)의 기본 흰 브러시가 카드 양피지를 덮음	그 Border 배경을 그리지 않게(NoDrawType) 설정
상세 내 작은 흰 박스(스탯 비교)	스탯 비교용 Border의 흰 배경 + 빈 아이콘 이미지의 흰색	Border는 그리지 않게, 아이콘은 투명(알파 0)
상품 목록 중간 흰 블록	목록 항목의 코인 아이콘 이미지에 텍스처가 없어 흰색	코인 아이콘 투명(알파 0)

핵심: 텍스처가 없는 Image/Border는 흰색으로 찍힌다. 안 쓰면 그리지 않게 하거나 투명으로 끈다. 그리고 배경 밝기와 텍스트 색은 항상 함께 봐야 한다(밝은 배경으로 바꾸면 기존 밝은 텍스트가 묻힘).

---

7. 좁은 카드에서의 텍스트·버튼 넘침/겹침

증상	원인	수정
인벤토리 툴바 버튼이 선택 시 밀려 영역 밖으로	선택 개수 텍스트가 길어지며 가로 박스에서 버튼을 밀어냄	버튼은 내용 크기(Auto), 선택 개수 텍스트는 남는 공간 채움(Fill) 으로 역할 분리
툴바 라벨이 서로 겹침	좁은 카드 대비 글꼴이 큼	툴바 글꼴 축소
우측 상세/인벤 내용 넘침	우측 카드가 너무 좁음	우측 카드 폭을 넓힘
판매 슬롯 수량 텍스트가 크고 테두리에 가림	수량 텍스트가 슬롯을 가득 채우고, 그 위에 프레임이 덧그려져 가림	수량 텍스트를 맨 위 레이어로 올리고 글꼴 축소 + 우하단 작은 배지로 정렬

핵심 두 가지:

• 가로 박스에서 한 요소가 다른 요소를 밀어내면, 밀리면 안 되는 쪽(버튼)은 Auto, 늘어나도 되는 쪽(텍스트)은 Fill로 둔다.
• 겹쳐 그리는 컨테이너(Overlay)에서 나중에 추가된 것이 위다. 무언가가 텍스트를 덮으면 그리기 순서를 조정한다.

---

8. 리스트 항목이 겹치는 문제 (CanvasPanel 크기)

증상

재구매 목록 항목들이 세로로 쌓이지 않고 한곳에 겹쳐 보였다(이름·가격이 붙어 값이 이상하게 보이기도 함).

원인

리스트 항목 위젯의 루트가 CanvasPanel이었다. CanvasPanel은 스스로 "원하는 크기(Desired Size)"가 0이라, 스크롤 박스가 각 항목에 높이를 주지 못해 0px로 겹친다. (게다가 내부 내용이 고정된 작은 박스에 갇혀 있어 더 뭉쳤다)

수정

항목 내부 콘텐츠를 위쪽에 가로로 늘리되 높이를 고정해, 항목이 스스로 높이를 보고하도록 했다. 그 위에서 글꼴 축소 + 이름은 남는 공간 채움, 가격·버튼은 내용 크기로 정렬.

교훈: CanvasPanel은 자식으로부터 크기를 만들어내지 않는다. 스크롤/세로 박스의 항목 루트로 쓰면 높이 0으로 무너진다. CanvasPanel을 쓸 땐 "누가 이 크기를 정하는가"를 항상 의식한다(고정 높이를 주거나, 부모 슬롯에서 Fill로 채우거나).

---

9. 상세 정보 풍부화

증상

상점 상세가 이름/가격/짧은 설명/스탯 1개만 보여 빈약했다.

수정

상세 갱신 로직에서 카테고리별로 여러 줄 정보를 만들어 설명 텍스트에 넣었다(설명 텍스트는 자동 줄바꿈).

// 무기: 공격력 / 종류 / 속성 + 설명
// 방어구: 방어력 / 부위 + 설명
// 소모품: 회복량 / 속성 충전 버프 + 설명
Detail += FString::Printf(TEXT("공격력  %.0f\n"), W->AttackPower);
if (W->WeaponTypeTag.IsValid())     Detail += FString::Printf(TEXT("종류  %s\n"), *TagLeaf(W->WeaponTypeTag));
if (W->WeaponAffinityTag.IsValid()) Detail += FString::Printf(TEXT("속성  %s\n"), *TagLeaf(W->WeaponAffinityTag));

---

10. 상호작용 프롬프트 숨김

증상

상점 패널이 열린 상태에서도 NPC 위에 "Interact" 프롬프트가 떠 있었다.

원인

상호작용 프롬프트는 플레이어 컨트롤러의 인터랙터 컴포넌트가 표시하는데, 패널이 열려도 계속 동작했다.

수정

패널 열림/닫힘 단일 지점에서 인터랙터를 비활성/활성한다.

// 패널 열림
if (UActorComponent* Interactor = GetInteractorComponent()) Interactor->SetActive(false);
// 패널 닫힘
if (UActorComponent* Interactor = GetInteractorComponent()) Interactor->SetActive(true);

---

11. UMG 에셋을 자동화로 편집할 때 주의

에디터 자동화 도구로 WBP를 편집하면서 반복적으로 부딪힌 규칙들. (이 프로젝트는 UMG 편집을 스크립트/자동화로도 한다)

• 편집 후 반드시 컴파일 + 저장한다. 컴파일하지 않은 변경은 에셋이 다시 로드되면 사라진다. 한 묶음 작업이 끝날 때마다 컴파일 → 저장까지 마쳐야 안전하다.
• 플레이(PIE) 중에는 에셋 저장이 막힌다. 저장은 플레이를 멈춘 뒤에 한다.
• WBP 위젯명과 C++ 프로퍼티명이 같으면 바인딩 충돌이 날 수 있다. 충돌하면 C++ 멤버를 두지 말고 이름으로 위젯을 찾아 쓴다(5장 참고).
• 빈 Image/Border는 흰색으로 보인다. 안 쓰면 그리지 않게 하거나 투명으로 끈다.
• CanvasPanel은 자식으로부터 크기를 만들지 않는다(8장). 항목/자식으로 쓸 땐 고정 높이나 Fill로 크기를 정해준다.

---

12. 검증 결과

항목	상태
NPC 정면 카메라 전환/복귀	✅
상점 닫기 → 커서/조작/카메라/플레이어 복귀	✅
레이아웃 WBP로 이전 (카드 4개 + 닫기/통화)	✅
런타임 조립 코드 제거	✅
BindWidget 이름 충돌	✅ 해소(이름으로 찾기)
흰 박스/아이콘	✅ 그리지 않게/투명
툴바/판매 슬롯/재구매 항목 깨짐	✅
상세 정보 여러 줄 표시	✅
상호작용 프롬프트 숨김	✅

수정/생성한 주요 파일

파일	작업
Player/RetrievePlayerController.h/.cpp	포커스 카메라(스폰/복귀/숨김/미리스폰), 인터랙터 토글
UI/Shop/ShopPanelWidget.cpp	닫기 위임, 런타임 조립 제거, 상세 풍부화, 닫기/통화 위젯 이름으로 연결
UI/Shop/ShopPanelWidget.h	닫기/통화 C++ 멤버 제거
WBP_ShopPanel	카드 레이아웃·양피지·앵커·닫기/통화 위젯
WBP_ShopItemEntry	코인 아이콘 투명
WBP_ShopSellSlot	수량 텍스트 위치/글꼴
WBP_ShopRepurchaseEntry	항목 높이/글꼴/정렬

C++ 변경(카메라·런타임 조립 제거·상세·인터랙터)은 빌드 후 적용된다. WBP 변경은 편집 후 컴파일·저장이 필요하다(11장).

---

13. 배운 점

UI가 런타임에 재조립되고 있는지부터 의심한다

WBP를 고쳐도 화면이 안 바뀌면, 그 위젯의 C++ NativeConstruct가 레이아웃을 다시 만들고 있는지 먼저 확인해야 한다. 레이아웃 소유자가 WBP인지 C++인지를 정하지 않으면 엉뚱한 곳을 계속 고치게 된다.

CanvasPanel은 스스로 크기를 만들지 않는다

리스트 항목 루트로 쓰면 스크롤 박스가 높이를 못 줘 겹치고, 세로 박스 자식이면 슬롯이 Auto일 때 높이 0으로 무너진다. CanvasPanel을 쓸 땐 크기를 누가 정하는지(고정 높이 / Fill)를 반드시 챙긴다.

흰 박스·흰 텍스트는 "빈 기본값 + 대비"의 문제다

텍스처 없는 Image/Border는 흰색으로 찍힌다. 그리고 밝은 배경으로 바꾸면 기존 밝은 텍스트가 묻힌다. 배경 밝기와 위젯 색을 함께 봐야 한다.

닫기·입력 복귀는 단일 경로로 위임한다

위젯이 자기를 직접 제거하면 컨트롤러가 하던 입력·커서·카메라·표시 복원이 통째로 누락된다. 닫기 요청을 한 경로로 모으면 부수 효과가 한곳에서 정리된다.

BindWidget 이름 충돌은 "이름으로 찾기"로 피한다

WBP 위젯명과 C++ 프로퍼티명이 같은데 바인딩이 안 잡히면 컴파일 에러가 난다. C++ 멤버를 없애고 이름으로 위젯을 찾아 쓰면 바인딩 타이밍에 의존하지 않는다.

풀 캐릭터 NPC를 카메라 타깃으로 쓰면 뒤통수가 보인다

캐릭터형 NPC는 자기 3인칭 카메라를 갖고 있고, 메시 정면이 액터 forward와 반대일 수 있다. 별도 카메라를 앞에 두고, 방향을 회전 오프셋으로 조정 가능하게 빼두면 NPC마다 값으로 맞출 수 있다.

에디터에서의 "멈춤"은 셰이더 컴파일일 수 있다

첫 진입·특정 화면에서만 나는 수 초 멈춤은 기능 버그가 아니라 셰이더 컴파일/스트리밍인 경우가 많다. 패키징 빌드에선 사라지므로, 코드로 잡으려 들기 전에 "에디터 전용인가"를 먼저 확인한다.

UMG 자동 편집은 "컴파일 + 저장"이 전부다

컴파일·저장하지 않은 변경은 에셋 재로드 한 번에 날아간다. 한 묶음마다 컴파일·저장, 그리고 플레이 중에는 저장이 안 된다는 점까지 묶어서 기억한다.