• 참고하던 UI

• 확정된 UI (2.png)

배경

파츠 NPC 상호작용 UI(NSPartEquipWidget)가 원래 "항목마다 개별 버튼(장착/구매) + hover 툴팁" 방식으로 짜여 있었는데, 기획이 Docs/2.png로 확정되면서 상호작용 모델 자체가 바뀌었다. 항목 클릭 → 중앙에 설명 표시 → 하단 장착 버튼 하나로 확정하는 선택 모델로 전환 필요

확정한 설계 결정과 이유

구현 내용 (파일별 역할)

신규 — NSPartDetailWidget.h/.cpp 카탈로그 선택 파츠와 장착중 파츠 양쪽에서 쓰는 상시 설명 패널.

• SetupFromDefinition(Row, Def) — 카탈로그 후보 표시 (비용/슬롯/리롤가능)
• SetupFromEquipped(SaveData, Def) — 장착중인 파츠 표시 (현재 등급/현재 수치)
• ClearDetail() — 선택/장착 없음 상태

수정 — NSPartCatalogEntryWidget.h/.cpp 개별 ActionButton(장착/구매)과 hover 툴팁(SetToolTip) 제거. 항목 전체를 감싸는 SelectButton 하나로 바뀌고, 클릭 시 Owner->SelectCatalogPart(Row) 호출. Icon/Name만 남음.

수정 — NSPartEquipWidget.h/.cpp

• 카탈로그를 BodyListContainer/ArmListContainer/LegListContainer 3분할로 라우팅 (GetCatalogContainerForSlot)
• 선택 상태(SelectedRow/bHasSelection) 보관, 카탈로그 클릭 시 중앙 설명·장착버튼 갱신 (SelectCatalogPart, RefreshEquipButton)
• 장착 버튼 클릭 시 소유 여부에 따라 RequestEquipPart/RequestUnlockPart 분기 (OnEquipButtonClicked)
• 왼쪽 장착중 3박스 클릭 시 해당 슬롯의 장착품 정보로 왼쪽 설명 갱신 (SelectEquippedSlot) — 클릭한 박스의 슬롯 태그와 실제 장착품의 슬롯이 일치할 때만 표시, 아니면 빈 상태

수정 — NSPartUtils.h/.cpp TSoftObjectPtr<UNSPartDefinition>를 직접 받는 ResolvePartDefinition 오버로드 추가. 기존 FNSPartData 버전은 이 오버로드에 위임하도록 리팩터링.

• 왜 추가했나: 카탈로그 선택(FNSPartDefinitionRow::Definition)과 장착중 조회(FNSPartSaveData::Definition) 둘 다 "소프트포인터에서 Definition을 캐시 경유로 안전하게 꺼내는" 동일한 로직이 필요했는데, 기존 함수는 FNSPartData 구조체 전용이라 재사용이 안 됐음. 중복 구현 대신 공용화.

삭제 — NSPartTooltipWidget.h/.cpp hover 툴팁 방식 자체가 폐기되면서 참조가 완전히 사라짐. 다른 참조 없음을 확인 후 삭제.

에디터에서 남은 작업

• WBP_PartTooltip.uasset 삭제 (C++ 부모 클래스 없어짐)
• WBP_PartEquip.uasset 레이아웃 재구성 (3열 구조, 바인딩 이름 일치)
• WBP_PartCatalogEntry.uasset을 SelectButton 구조로 재구성
• 신규 WBP_PartDetail.uasset 생성 (부모: NSPartDetailWidget)

2. UMG 레이아웃 트러블슈팅 — Anchor와 Box Slot Fill 혼동

에디터 작업 중 위젯이 전부 왼쪽 위에 몰리는 문제 발생. 계층 구조(Hierarchy)는 올바르게 잡혀 있었는데도 발생한 원인:

• UMG는 사이즈 규칙이 두 층으로 분리됨
  1. Canvas Panel Slot (Anchors + Offset) — Canvas Panel의 직계 자식에만 적용
  2. Box Slot (Size Rule: Auto/Fill) — Horizontal/Vertical Box의 자식에만 적용
• 최상위 Horizontal Box(3열 컨테이너)가 Canvas Panel의 자식인데 1번 레이어의 Anchor를 "전체 스트레치"로 안 잡아서, 그 안에서 2번 레이어(Vertical Box Fill)를 아무리 조정해도 애초에 나눠 가질 공간 자체가 없었음.
• 해결: 최상위 Horizontal Box의 Anchor를 전체 스트레치(4방향 Offset 0)로 지정 → 그 안의 Vertical Box 3개에 Box Slot Fill 비율 지정.

3. 파츠 데이터 로드 구조를 UDeveloperSettings에서 NSCommonDataConfig로 이관

문제 발견 경위

사용자가 프로젝트의 데이터 로드 아키텍처를 다시 확인하자고 제안: NSDataSubsystem은 공용(Common) / 아웃런(OutGame) / 인런(Run) 페이즈별로 데이터를 로드하고, 페이즈마다 전용 UPrimaryDataAsset(예: UNSCommonDataConfig)에 DT/에셋 참조를 몰아두는 구조로 이미 정리되어 있는데, 파츠 DT(DT_PartDefinition/DT_PartSlot)만 예외적으로 UNSDataSettings(UDeveloperSettings, 프로젝트 세팅 전역 싱글톤)에 붙어 있었음.

조사로 확인한 사실

• Common 페이즈는 이미 UNSCommonDataConfig : UPrimaryDataAsset를 통해 AssetBundles="CommonData" 방식으로 DT를 로드하고 있었음 (예: AbilityBaseStatTable).
• OutGame 페이즈용 동급 DA(HubAssetType/"NSHubData")는 코드에 상수만 선언돼 있고 실제 클래스도, AssetManager 스캔 등록도 없는 미완성 상태였음.
• 파츠는 인런/아웃런 양쪽에서 다 필요한 데이터라, OutGame 전용 DA가 아니라 Common 설정에 들어가는 게 맞다고 결론.

변경 내용

• NSCommonDataConfig.h에 PartsBaseStatTable, PartsSlotBaseStatTable 필드 추가 (AssetBundles="CommonData")
• NSDataSubsystem.cpp:
  • OnOutGamePrimaryAssetsLoaded/OnOutGameAssetsLoaded에서 파츠 DT 로드·캐시빌드 로직 제거
  • OnCommonAssetsLoaded에 BuildPartRowCache()/BuildSlotRowCache() 호출 추가
  • 두 함수가 GetDefault<UNSDataSettings>() 대신 GetCommonDataConfig()를 조회하도록 변경
• NSDataSettings.h/.cpp 삭제, Config/DefaultGame.ini의 [/Script/NeoSanctum.NSDataSettings] 섹션 삭제

왜 이렇게 했나

• 페이즈 일관성: 다른 모든 데이터가 "페이즈 전용 PrimaryDataAsset에 소프트 참조를 몰아두고, 해당 페이즈 로드 시 AssetBundle로 같이 끌려오게" 하는 패턴을 쓰는데, 파츠만 UDeveloperSettings라는 별개 메커니즘(프로젝트 세팅, 페이즈 개념 없음)을 쓰고 있어 구조가 어긋나 있었음.
• 로드 로직 단순화 부수효과: UDeveloperSettings는 UPrimaryDataAsset이 아니라서 AssetBundle 시스템에 못 들어가고, 그래서 기존 코드는 PartDefinitionTable/PartSlotTable 경로를 수동으로 RequestAsyncLoad하는 별도 코드가 필요했음. NSCommonDataConfig로 옮기면서 AssetBundles="CommonData" 메타데이터 하나로 LoadPrimaryAssets(..., CommonBundles, ...) 호출에 자동으로 딸려 들어오게 되어, 수동 로드 분기 코드 자체가 통째로 삭제됨.
• 미완성 OutGame DA(NSHubData)를 새로 만들지 않은 이유: 파츠가 인런에서도 필요한 이상 OutGame 전용 DA에 넣는 건 애초에 범위가 안 맞았음. 없는 클래스를 새로 만드는 것보다, 이미 있고 정상 작동 중인 Common 패턴에 얹는 게 더 적은 변경으로 올바른 구조에 도달하는 길이었음.

로드 → 캐시 흐름 (변경 후)

LoadCommonData()
  → StartLoadCommon(): CommonDataConfigAssetType를 CommonBundles로 LoadPrimaryAssets
      (PartsBaseStatTable/PartsSlotBaseStatTable가 AssetBundles="CommonData"라 자동으로 같이 로드됨)
  → OnCommonAssetsLoaded(): CacheLoaded() → BuildPartRowCache() → BuildSlotRowCache()
      → GetCommonDataConfig()로 DA를 찾고 DT를 꺼내 CachedPartRowsByDefId / CachedSlotRowsBySlot에 채움

에디터에서 남은 작업

Content/NeoSanctum/Data/Config/DA_CommonDataConfig.uasset을 열어 PartsBaseStatTable → DT_PartDefinition, PartsSlotBaseStatTable → DT_PartSlot 지정

1. WBP_PartPanel 컴파일 에러 — SlotButtonContainer not found

증상
WBP_PartPanel을 열면 "SlotButtonContainer를 찾을 수 없습니다" 컴파일 에러.

원인
NSPartPanelWidget.h에 BindWidget으로 선언된 SlotButtonContainer(UPanelWidget)가 WBP 디자이너에 존재하지 않았음.

수정
WBP_PartPanel 디자이너에 WrapBox를 추가하고 이름을 SlotButtonContainer로 지정.

선택 이유
BindWidget은 WBP에 정확히 같은 이름의 위젯이 있어야 컴파일을 통과한다. 이름 불일치가 유일한 원인이므로 코드 수정 없이 WBP에서 해결.

2. SlotButtonTemplate이 Details 패널에서 안 보임

증상
WBP_PartPanel을 선택하고 Details 패널에서 SlotButtonTemplate을 검색해도 나오지 않음.

원인
SlotButtonTemplate은 UPROPERTY(EditDefaultsOnly)로 선언되어 있어 Designer 탭 Details가 아니라 Graph 탭 Class Defaults에만 노출됨.

수정
Graph 탭 → Class Defaults에서 SlotButtonTemplate에 WBP_PartsButton 지정.

선택 이유
EditDefaultsOnly는 인스턴스별 수정이 필요 없는 클래스 수준 설정에 쓰는 지정자. 슬롯 버튼 템플릿은 모든 인스턴스가 같은 WBP를 공유하므로 설계가 맞고, 코드 변경 없이 에디터 탐색 경로를 바꿔 해결.

3. Tab 키를 눌러도 파츠 패널이 반응하지 않음

증상
인런에서 Tab을 눌러도 파츠 슬롯이 표시되지 않고 아무 반응 없음.

원인
Tab → Input.Augment.TogglePanel 태그 → ToggleAugmentationPanel() 함수가 내부에서 IsRunReady() 상태를 확인하는 구조. OutGame(HideOut 맵)에서 테스트했기 때문에 조건이 false여서 아무것도 실행되지 않았음.

수정
인런 맵에서 테스트.

선택 이유
조건 자체가 올바른 설계(인런에서만 파츠 패널 토글 허용). 구현 버그가 아니라 테스트 환경 오류였으므로 코드 수정 없음.

4. 인런에서 Tab을 눌러도 슬롯 버튼이 나타나지 않음 (타이밍 문제)

증상
인런에서 Tab을 누르면 패널 자체는 뜨지만 Arm / Leg / Body 슬롯 버튼이 비어 있음.

원인 (1단계)
UNSPartPanelWidget::NativeConstruct()에서 BuildSlotButtons()를 호출하는데, 이 시점에 CachedSlotRowsBySlot이 비어 있어 버튼이 생성되지 않았음.

원인 (2단계)
CachedSlotRowsBySlot이 비어 있는 이유는 BuildSlotRowCache()가 OnOutGameAssetsLoaded() 안에서만 호출되는데, PartSlotTable이 OnOutGamePrimaryAssetsLoaded()의 비동기 로드 목록에 포함되지 않아 DT 자체가 메모리에 없었음.

원인 (3단계, 근본 원인)
LoadOutGameData()가 HideOut 맵 진입 핸들러에서 호출되지 않고 있었음. OutGame 데이터 로딩 자체가 시작되지 않아 이후 모든 단계가 동작하지 않았음.

수정

// NSPlayerController.cpp — HideOut 맵 핸들러
if (UNSDataSubsystem* DataSubsystem = UNSDataSubsystem::Get(this))
{
    DataSubsystem->LoadOutGameData();  // ← 추가
    ...
}

// NSDataSubsystem.cpp — OnOutGamePrimaryAssetsLoaded
// PartSlotTable을 비동기 로드 목록에 추가
if (!Settings->PartSlotTable.IsNull() && Settings->PartSlotTable.Get() == nullptr)
    PendingLoads.Add(Settings->PartSlotTable.ToSoftObjectPath());

// NSDataSubsystem.cpp — OnOutGameAssetsLoaded
void UNSDataSubsystem::OnOutGameAssetsLoaded()
{
    BuildPartRowCache();
    BuildSlotRowCache();  // ← 추가
    SetPhase(ENSDataLoadPhase::OutGameReady);
    OnOutGameDataReady.Broadcast();
}

// NSPartPanelWidget.cpp — NativeConstruct (타이밍 대응)
if (!DataSS->GetAllSlotRows().IsEmpty())
{
    BuildSlotButtons();
    ...
}
else
{
    // 아직 로드 전이면 완료 델리게이트 구독
    DataSS->OnOutGameDataReady.AddDynamic(this, &UNSPartPanelWidget::OnOutGameDataReady);
}

선택 이유

• LoadOutGameData() 미호출은 단순 누락이므로 있어야 할 자리(HideOut 핸들러의 DataSubsystem 블록)에 추가.
• PartSlotTable 누락도 동일한 이유로 PartDefinitionTable과 같은 방식으로 추가.
• NativeConstruct 타이밍 문제는 "데이터가 준비됐으면 즉시, 아니면 델리게이트 구독 후 콜백"으로 처리. 위젯 생성 시점과 데이터 준비 시점이 보장되지 않는 구조에서 표준적인 패턴.
• NativeDestruct에서 RemoveDynamic으로 구독 해제하여 위젯 파괴 후 콜백 호출 방지.

요약 — 디버깅 순서와 실제 원인 계층

Tab 눌러도 슬롯 안 나옴
  └─ BuildSlotButtons()에서 슬롯 데이터가 비어 있음
       └─ BuildSlotRowCache()가 실행되지 않았음
            └─ PartSlotTable이 로드되지 않았음
                 └─ LoadOutGameData()가 호출되지 않았음  ← 근본 원인

증상은 UI에서 보였지만 원인은 PlayerController의 맵 전환 핸들러에 있었음.
데이터 로드 → 캐시 빌드 → 위젯 구독 → UI 반영으로 이어지는 의존 체인 전체를 역추적해야 찾을 수 있는 유형의 버그.

1. 처음 구조 — enum 기반 슬롯

어떤 구조였나

UENUM(BlueprintType)
enum class ENSPartSlot : uint8
{
    Body,
    Arm,
    Leg
};

슬롯은 C++ enum으로 고정. 파츠 관련 모든 구조체/컴포넌트/UI가 이 enum에 의존하고 있었다.

// 세이브 데이터
TSet<ENSPartSlot> UnlockedSlots;   // 캐릭터별
TArray<FNSPartSaveData> OwnedParts; // 캐릭터별

// UI
UPROPERTY(meta=(BindWidget)) UNSPartSlotButton* BodySlotButton;
UPROPERTY(meta=(BindWidget)) UNSPartSlotButton* ArmSlotButton;
UPROPERTY(meta=(BindWidget)) UNSPartSlotButton* LegSlotButton;

// VisualComponent
for (const ENSPartSlot Slot : { ENSPartSlot::Body, ENSPartSlot::Arm, ENSPartSlot::Leg })

무엇이 문제였나

"슬롯을 하나 추가하면 어떻게 되는가?"를 생각했을 때 문제가 명확해졌다:

1. C++ enum에 값 추가 → 리컴파일 필요
2. switch/if 분기 전부 수정 → 빠뜨리면 런타임 버그
3. UI 위젯에 버튼 UPROPERTY 추가 → UMG 에디터 열어서 바인딩
4. VisualComponent 하드코딩 순회 수정 → 까먹으면 새 슬롯 메시 안 붙음

슬롯 3개인 지금도 관리하기 불편한데, 슬롯이 늘어날수록 이 비용이 선형으로 증가한다.

2. 첫 번째 전환 결정 — FGameplayTag + DataTable

왜 FGameplayTag인가

증강 시스템이 이미 FGameplayTag로 모든 카테고리를 구분하고 있었다. 슬롯도 같은 체계를 쓰면:

• 에디터 드롭다운 필터: meta=(Categories="Part.Slot") 한 줄로 Part.Slot.* 네임스페이스만 표시
• 신규 슬롯 추가 워크플로: 태그 1줄 등록 + DT 행 1개 추가. C++ 수정 없음
• 빌드 없이 슬롯 확장 가능

DataTable은 왜 필요한가

태그만으로는 "이 슬롯의 해금 비용이 얼마인가", "기본 해금 상태인가"를 알 수 없다.
DT_PartSlot이 이 수치를 보관하고, 코드는 DataSubsystem을 통해 캐시된 맵으로 조회한다.

// DT 행 구조체
USTRUCT(BlueprintType)
struct FNSPartSlotRow : public FTableRowBase
{
    FGameplayTag SlotTag;       // 슬롯 정체성
    int64 UnlockCost;           // 해금 비용
    bool bUnlockedByDefault;    // 기본 해금 여부
    bool bEnabled;              // 활성화 여부
};

// DataSubsystem 캐시
TMap<FGameplayTag, FNSPartSlotRow> CachedSlotRowsBySlot;

무엇이 바뀌었나

UI 동적화가 어떤 의미인가

// 변경 전 — UMG에 버튼 3개 고정 배치, C++에서 이름으로 참조
UPROPERTY(meta=(BindWidget)) UNSPartSlotButton* BodySlotButton;
UPROPERTY(meta=(BindWidget)) UNSPartSlotButton* ArmSlotButton;
UPROPERTY(meta=(BindWidget)) UNSPartSlotButton* LegSlotButton;

void HandlePartChanged(ENSPartSlot Slot, ...)
{
    switch(Slot)
    {
        case Body: BodySlotButton->...; break;
        case Arm:  ArmSlotButton->...;  break;
        case Leg:  LegSlotButton->...;  break;
        // 슬롯 추가 시 여기도 수정 필요
    }
}

// 변경 후 — 컨테이너만 UMG에 배치, 버튼은 DT 읽고 런타임 스폰
void BuildSlotButtons()
{
    for (const auto& Pair : DataSS->GetAllSlotRows())
    {
        UNSPartSlotButton* Btn = CreateWidget<UNSPartSlotButton>(this, SlotButtonTemplate);
        SlotButtonContainer->AddChild(Btn);
        SlotButtonMap.Add(Pair.Key, Btn);  // 태그 → 버튼 맵
    }
}

void HandlePartChanged(FGameplayTag Slot, ...)
{
    if (auto* Btn = SlotButtonMap.Find(Slot))
        ApplySlot(Slot, *Btn);   // switch 없음, 슬롯 추가해도 수정 불필요
}

"동적화"란: DT에서 슬롯 행이 늘어나면 버튼도 자동으로 늘어나는 구조.
슬롯 추가 = DT에 행 1개 추가가 전부. UI/C++ 수정 없음.

3. 중간에 발견된 설계 오류 — OwnedParts 범위 문제

무엇이 잘못됐나

구현 중 OwnedParts(파츠 인벤토리)가 FNSCharacterSaveData(캐릭터별) 안에 있다는 것을 확인했다.

struct FNSCharacterSaveData
{
    TArray<FNSPartSaveData> OwnedParts;  // ← 캐릭터별로 파츠를 따로 가지고 있었음
    TSet<FGameplayTag> UnlockedSlots;
};

이 구조의 문제: 캐릭터 A로 파츠를 구매하면 캐릭터 B에서는 그 파츠가 없다.
원래 의도는 "파츠 인벤토리는 계정 공유"였다.

실제로 OwnedParts는 처음 설계 때 UNSPermanentSaveGame(계정 레벨)에 있었다가,
어느 시점에 캐릭터별로 이사 온 것으로 파악됐다. enum→태그 전환 작업 도중 이 사실이 드러났다.

왜 이게 문제인가

게임 설계 의도:

• 파츠 인벤토리: 계정 공유. 어떤 캐릭터로 구매해도 전체 캐릭터가 사용 가능.
• 슬롯 언락: 캐릭터별. 캐릭터마다 독립적으로 슬롯을 해금.
• 장착 참조: 캐릭터별. 어떤 파츠를 끼고 있는지는 캐릭터마다 다름.

OwnedParts가 캐릭터별이면 "파츠 공유" 자체가 불가능해진다.

무엇을 어떻게 변경했나

세이브 구조:

// 변경 전
struct FNSCharacterSaveData
{
    TArray<FNSPartSaveData> OwnedParts;  // 캐릭터별 (잘못됨)
    TSet<FGameplayTag> UnlockedSlots;    // 캐릭터별 (유지)
};

// 변경 후
struct FNSCharacterSaveData
{
    // OwnedParts 제거됨
    TSet<FGameplayTag> UnlockedSlots;    // 캐릭터별 (유지)
};

class UNSPermanentSaveGame
{
    TArray<FNSPartSaveData> OwnedParts;  // 계정 공유로 복귀
};

ProgressionSubsystem 함수 시그니처:

// 변경 전 — CharacterId가 인벤토리 조회에도 쓰임
bool IsPartOwned(FName CharacterId, TSoftObjectPtr<UNSPartDefinition>, ENSPartRarity) const;
const TArray<FNSPartSaveData>& GetOwnedParts(FName CharacterId) const;

// 변경 후 — 인벤토리는 계정 풀, CharacterId 불필요
bool IsPartOwned(TSoftObjectPtr<UNSPartDefinition>, ENSPartRarity) const;
const TArray<FNSPartSaveData>& GetOwnedParts() const;

PurchasePart는 CharacterId를 유지했다. "이 캐릭터의 슬롯이 해금됐는가"를 검사하기 때문이다. 구매는 캐릭터 슬롯 게이트를 통과해야 하지만, 구매된 파츠는 계정 풀에 쌓인다.

NSPlayerController UploadLocalProgress:

// 변경 전 — 장착 파츠를 캐릭터 인벤토리에서 찾음
const FNSPartSaveData* Owned = CharacterSlot->OwnedParts.FindByPredicate(...);

// 변경 후 — 장착 파츠를 계정 인벤토리에서 찾음
const FNSPartSaveData* Owned = PermanentSave->OwnedParts.FindByPredicate(...);

4. 최종 구조

세이브 데이터 책임 분리

슬롯 추가 워크플로 (최종)

1. Config/DefaultGameplayTags.ini에 Part.Slot.Wing 태그 1줄 추가
2. DT_PartSlot에 행 1개 추가 (SlotTag=Part.Slot.Wing, UnlockCost=500, ...)
3. DT_PartDefinition에 해당 슬롯 파츠 행 추가
완료 — C++ 수정/빌드 없음

수정된 파일 목록

5. 핵심 교훈 (TIL)

enum → FGameplayTag 전환이 필요한 시점

enum은 집합이 고정될 때 좋다. "나중에 늘어날 수 있다"는 가능성이 조금이라도 있으면 태그+DT가 낫다.
전환 비용(모든 참조 수정)이 크지만, 한 번 전환하면 이후 확장 비용이 0에 가까워진다.

데이터 소유권은 설계 초반에 명확히

OwnedParts가 계정 공유인지 캐릭터별인지는 게임 설계 의도의 문제다.
이걸 코드 구현 중에 발견한 건 설계 문서에 명시되지 않았기 때문이다.
세이브 데이터 설계 시 모든 필드에 "계정 단위 / 캐릭터 단위"를 명시하는 습관이 필요하다.

PurchasePart의 CharacterId는 왜 남겼나

"파츠를 살 수 있는가"를 검사할 때 "이 캐릭터의 슬롯이 해금됐는가"가 필요하다.
구매 게이트는 캐릭터별, 구매된 파츠의 저장은 계정 공유.
책임이 두 층에 걸쳐 있어서 파라미터가 남아있는 것이 맞다.

UI "동적화"는 DT와 세트로 설계해야 한다

슬롯 버튼을 UMG에 하드코딩하면 슬롯 추가 때 UI도 수정해야 한다.
SlotButtonTemplate(버튼 1개짜리 클래스)을 에디터에서 지정하고,
런타임에 DT를 읽어서 스폰하는 패턴이 DT 기반 설계의 완결이다.

1. 목표

인 런 진입 전 거점에서 파츠를 미리 선택·장착할 수 있게 한다.

• 영구 재화(CommonCurrency)를 소모해 개별 파츠를 언락(구매)
• 언락한 파츠 중 1부위를 선택해 장착 저장 → 런 시작 시 Common 등급으로 적용
• 비용·목록 등 모든 수치는 DataTable로 관리

2. 설계 원칙

• 증강 동형 패턴: DT가 카탈로그·수치를 주도, 얇은 DA가 번들 페이로드(Icon/GE/GA/Mesh) 보유
• DA 정체성 유지: 런타임·세이브 키는 TSoftObjectPtr<UNSPartDefinition> 그대로 → 세이브 마이그레이션 없음
• 아웃런 = 저장 전용: 허브에서 GAS 즉시 장착 없음. 런 시작 시 기존 경로(ApplyEquippedPart)로 적용
• 모든 수치는 DT: 언락 비용, ValueRange, bCanReroll 전부 DT_PartDefinition에서 읽음

3. 데이터 모델

3-1. 신설: FNSPartDefinitionRow : FTableRowBase (DT_PartDefinition)

카탈로그의 유일한 수치 출처. 파츠 1개 = row 1개.

3-2. UNSPartDefinition 변경 (얇아짐)

DA에서 DT로 이사하는 필드: ValueRange, bCanReroll, PartSlot

DA에 남는 필드 (PrimaryAsset·번들 로드 앵커로 유지):

PartIconTool은 DA의 PartMesh → Icon 경로를 그대로 사용하므로 수정 없음.

4. 해석 인프라 (증강 패턴 복제)

4-1. NSDataSubsystem

UPROPERTY(EditDefaultsOnly)
TObjectPtr<UDataTable> PartDefinitionTable;  // DT_PartDefinition 참조

TMap<FPrimaryAssetId, FNSPartDefinitionRow> CachedPartRowsByDefId;  // 로드 시 빌드

• 허브 로드 시(LoadOutGameAssets) PartAssetType DA 로드 완료 콜백에서 row 캐시 빌드
• GetPartRow(FPrimaryAssetId) → const FNSPartDefinitionRow* 조회 함수 추가

4-2. NSPartUtils

기존 ResolvePartDefinition(WorldCtx, PartData) 유지.
신규 ResolvePartRow(WorldCtx, FPrimaryAssetId) → const FNSPartDefinitionRow* 추가.

5. 언락(구매) 흐름

[UI: 언락 버튼 클릭]
  → ProgressionSubsystem::PurchasePart(Def, Common, Cost)
      ← Cost는 UI가 직접 넘기지 않음
      ← NSDataSubsystem::GetPartRow(DefId).UnlockCost 에서 조회 (단일 출처)
      → CommonCurrency 차감
      → OwnedParts 에 FNSPartSaveData 추가 (Value 1회 롤 후 고정)
      → SaveNow()

PurchasePart 수정 포인트:

• LoadSynchronous 제거 — ValueRange를 DT row에서 읽으므로 DA 로드 불필요
• 비용 파라미터 제거 또는 row 조회로 대체

6. 장착 흐름 (저장 전용, 허브 GAS 없음)

[UI: 장착 버튼 클릭]
  → ProgressionSubsystem::SetEquippedPart(CharacterId, Def, Common)
      → IsPartOwned 검증
      → FNSCharacterSaveData.EquippedPartDefinition / Rarity 갱신
      → SaveNow()

• 현재 위젯의 Server_RequestEquip (인런 GAS 즉시 장착 경로) 호출 제거
• 허브에서 비주얼 프리뷰가 필요해지면 별도 추가 (현재 범위 밖)

7. 위젯 재연결 (NSPartEquipWidget)

UI 표시 항목 (row + OwnedParts 상태 결합):

• 파츠 이름 / 슬롯 / 언락 비용
• 상태: 미언락(비용 표시) / 언락됨(장착 가능) / 장착 중

8. 런 시작 적용

변경 없음. 기존 경로 그대로.

NSPlayerController::Server_UploadProgress
  → OwnedParts에서 EquippedPartDefinition + Rarity로 FNSPartSaveData 해석
  → Payload.EquippedPart 설정
  → Client_SaveProgress / ApplyEquippedPart()

증강의 선택가능 횟수가 다음 스테이지로 유지가 안되는 문제

증상

• 스테이지 1에서 증강 추첨횟수가 남아있는 상태로 다음 스테이지로 넘어가면 증강 추첨횟수가 남아있지 않음
• 고른 증강(인벤토리)은 정상적으로 이관되나, 아직 선택하지 않은 추첨대기횟수(PoolQueue)가 초기화되는 현상

관련 구조

UNSAugmentSelectionComponent (PlayerController에 붙음)
  ├── PoolQueue        : 대기 중인 추첨 풀 태그 목록 (서버 전용)
  ├── PendingCount     : PoolQueue.Num() 복제값 (클라이언트 UI 뱃지용)
  └── OnPendingCountChanged : UI 갱신 델리게이트

• PendingCount는 SetPendingCount로만 변경이되고, OnRep_PedingCount로만 클라에 복제되는 형태

트러블 슈팅 과정

초기 가설 : 타이밍 문제

• 가설 : OnRep_PendingCount가 위젯 NativeConstruct보다 먼저 발화되어 델리게이트 미바인딩 -> 소실?
• 검증 방법 : OnRep_PendingCount와 NativeConstruct에 로그 추가
• 결과 : NativeConstruct에서 이미 GetPendingCount를 델리게이트 구독하여 타이밍 문제가 아님

2단계 : PostSeamlessTravel 시점 확인

• 검증 방법 : PostSeamlessTravel함수를 오버라이드해서 PoolQueue가 살아있는지 확인
• 결과 : PostSeamlessTravel 시점에 PendingCOunt = 0 즉 데이터손실은 그 이전에 발생

3단계 : 데이터 소실 경로 탐색

Reset(), Server_Choose, SetPendingCount, CopyRunStateFrom, 생성자에 순차적으로 로그 추가

• 결과 : SetPendingCount(0)이 안불리는데 PendingCount가 0 -> 컴포넌트가 새로 생성되어 기본값(0)으로 시작하는구나

4단계 : 포인터 비교로 컴포넌트 재생성 확인

• 검증 방법 : EnqueueOffer와 PostSeamlessTravel에 this포인터 로그 추가

[EnqueueOffer]       this=000002C9E94F4F80 PoolQueue=4   ← 스테이지1
[Constructor]        this=000002C9E94F3D80               ← 전환 직후 새 컴포넌트 생성
[PostSeamlessTravel] comp=000002C9E94F3D80 PendingCount=0 ← 새 컴포넌트라서 0

• 결과 : 포인터가 다르다. SeamlessTravel시 새 컴포넌트 (새 PC)가 생성되고 있음이 거의 확실

5단계 : 근본 원인 확정 : AGameModeBase vs AGameMode

엔진소스를 뜯어서 GameModeBase와 GameMode를 보았다.

AGameMode::HandleSeamlessTravelPlayer의 경우

if (PC && PC->GetClass() != PCClassToSpawn)
{
    // 클래스가 다를 때만 새 PC spawn
    PC->SeamlessTravelTo(NewPC);
}
else
{
    // 클래스가 같으면 PC 객체 그대로 유지 ← 데이터 보존
}

클래스가 다를때만 새 PC를 스폰하고 같으면 유지하는 코드가 존재한다.

AGameModeBase::HandleSeamlessTravelPlayer의 경우

// 무조건 새 PC spawn — 클래스 비교 없음
APlayerController* NewPC = SpawnPlayerControllerCommon(...);
PC->SeamlessTravelTo(NewPC);  // ← 이전 PC에서 수동 이관해야 함

PC비교가없고 NewPC로 덮어씌움 결국 수동으로 데이터를 이관해주어야 한다

NeoSanctum의 경우 게임모드가 AGameModeBase를 상속받기 때문에 두가지 해결방안을 냈다.

해결 방안

1. PlayerState로 이관

AugmentSelectionComponent는 기존에 PlayerController에 장착되어있다. 결국에는 조작과 관련된 기능들이 있어서 PC에 ActorComponent로 달게 되었었고, SeamlessTravel시 해당문제는 단지 PC는 무조건 끝까지 살아있는 구조로 알고있었어서 이렇게 짠것도 있다. 이쪽 방안이 조금 더 깔끔한 구조라고 생각이 된다.

2. SeamlessTravelTo 오버라이드 (PC유지)

기존 PC에 달아놓는 방식에서 SeamlessTravelTo함수를 오버라이드하여 PC에서 복제하는 함수를 하나 만들고 새로운 PC가 생겼을때 데이터를 복제해주는 식으로도 짤 수 있다. 이쪽의 장점은 구현이 간단하고, 현재 다른 기능들은 정상작동하는데 굳이 PC에서 PlayerState로 옮겨야 하는 생각이 있었다. 그래서 결론적으로 이쪽으로 구현하게 되었다.

선택이유

위에서 작성한것처럼 우선 잘 작동하는데 굳이 건드렸다가 다른 버그가 터질수도 있다고 생각하여 PC에 두는 구조를 계속 이어가기로 하였다.

리팩토링

위젯을 npc에서 pc로 옮기는 작업

기존구조에서는 npc에서 위젯을 띄워주는 역할을하고 있었는데 프로젝트 구조상 PC에서 UI를 모두 관리하고 있는 구조였다. 그래서 잠재적인 버그 (PC쪽 UI와 겹쳐서 버그발생)을 미연에 방지하기 위해서 PC쪽으로 옮기기로 하였다.

기존 구조

NPO의 OnInteract함수에서 CreateWidget -> Widget->OpenForInteractor()로 NPC가 위젯 타입을 직접 알고 생성

변경 구조

NPC의 GetInteractionWidgetClass -> Type별 WidgetClass 반환, PlayerController에서 OpenInteractionWidget(NPC) -> CreateWidget -> OpenForInteractor

변경 후 이점

PC는 UNSNPCInteractionWidgetBase 타입만 알고, 실제로 UNSPetUpgradeWidget인지 UNSPartEquipWidget인지는 모름 위젯 클래스는 NPC에서 받아오고 열고닫는건 베이스 타입의 가상함수로 처리

덕분에 PC는 ActiveInteractionWidget하나로 어떤 NPC위젯이든 관리할 수 있다.

개념

Seamless Travel에서 살아남는 것 vs 사라지는 것

사라지는 것(새로 생성)

• GameMode : 새 레벨에서 새로 생성
• GameState : 새로 생성
• Pawn : 새로 생성 (또는 리스폰)
• HUD / 위젯 : 새 레벨에서 새로 생성

살아남는 것

• PlayerController : 재사용
• PlayerState : 재사용
  • 같은 PlayerState를 재사용하는것이 새 인스턴스를 생성한 뒤 CopyProperties()를 호출해서 데이터를 복사하는 방식을 사용한다.
  • 커스텀 데이터를 유지하고 싶으면 CopyProperties를 사용하는것 (우리가 했던 구조)
• PC/PS에 붙어있는 ActorComponent : 재사용

으로 정리를 했는데....

변수등장

우선 언리얼 공식문서를 보면 Traveling Actor 목록에서 PC객체 자체가 들어있다고 한다. 근데 이게 AGameModeBase를 상속받냐 AGameMode를 상속받냐에 따라 다른데 왜 다른가 하면 둘의 HandleSeamlessTravelPlayer()의 구조가 조금 다르다.

HUD

NativeConstruct

위젯이 뷰포트에 추가되는 순간 호출

생성자와의 차이점은

호출 시점

• 생성자 : 에디터/쿡 타임 포함, 객체 생성 시
• NativeConstruct : AddToViewport() / AddToPlayerScreen() 호출 시

BP 변수 바인딩

• 생성자 : 아직 없음
• NativeConstruct : 완료(BindWidget 변수 사용 가능)

소유 PC

• 생성자 : 없음
• NativeConstruct : GetOwningPlayer() 작동

추후 작업

인런재화는 아웃런에 안들어감

인런 상점

인런에서 먹은 파츠 강화 증강 리롤

아웃런 상점

• 각각 npc가 있는 구조

파츠 구매 공용 스킬 드론

파츠 아이콘 간헐적 미표시 (패키징 전용)

증상

• 인런 중 몬스터 드롭 파츠를 줍고 Tab을 여러 번 열고 닫으면 장착 파츠 아이콘이 간헐적으로 사라짐
• 에디터 PIE에서는 재현 안 됨, 패키징 빌드에서만 발생
• 양쪽 클라이언트 동시에 사라지는 케이스도 목격됨

시도 1 — 서버에서 EquippedParts 배열이 초기화되는 경로 의심

단서: 양쪽 클라이언트 동시에 사라진다 → 클라이언트 개별 문제가 아니라 서버에서 발생하는 문제일 것.

의심 경로:

CommitCharacterSelection (캐릭터 선택 NPC)
→ UploadLocalProgress()
→ Server_UploadProgress_Implementation()
→ ApplyEquippedPart()
    → EquipComp->ClearAll()   ← 전체 파츠 삭제
    → SaveGame 기준 1개만 재장착

인런 중 캐릭터 선택 NPC를 건드리면 SaveGame 기준으로 파츠가 리셋되면서 배열이 일시적으로 비워질 수 있다고 판단.

추가한 로그:

• OnRep_EquippedParts에 배열 크기 로그
• NSPartUtils::ResolvePartDefinition에 DataCache 미스 로그

결과: 양쪽 클라이언트 동시 소멸 케이스는 이 경로가 원인일 수 있으나, 주요 재현 케이스(Tab 여러 번)와는 패턴이 달랐음. 보류.

시도 2 — 비동기 로드 타이밍 문제 의심 (메모리 미로드)

단서: 패키징에서만 발생 + "간헐적" 패턴 → 에디터와 패키징의 에셋 메모리 상태 차이 의심.

에디터는 프로젝트 열 때 레퍼런스된 에셋을 모두 메모리에 올려두지만, 패키징 빌드는 명시적으로 로드하기 전까지 메모리에 없음.

ApplySlot 흐름:

RefreshEquippedParts → ApplySlot
→ ResolvePartDefinition → Definition 반환 (성공)
→ SlotButton->SetPart(*PartData, Def)
    → SetBrushFromSoftTexture(Def->Icon)  ← 여기가 의심

NSPartDefinition::Icon이 TSoftObjectPtr<UTexture2D>. Definition 에셋이 메모리에 로드되어도 내부의 소프트 참조 텍스처는 별도로 로드해야 함.

"있다가 없다가"인 이유: SetBrushFromSoftTexture는 내부적으로 비동기 로드를 요청하지만 완료 콜백도 없고 핸들도 보관하지 않음. Tab을 열 때 이전 요청이 완료됐으면 텍스처가 메모리에 있어 표시되고, 아직 완료되지 않았으면 빈 이미지로 표시됨 — 순전히 타이밍에 의존.

패키징에서만 터진 이유: 에디터는 에셋이 항상 메모리에 있어 Icon.Get()이 항상 유효. 패키징은 쿠킹(파일 포함)과 런타임 로드가 분리되어 있어, 쿠킹된 에셋이라도 명시적으로 로드하지 않으면 Get() = null.

해결

NSPartSlotButton::SetPart에서 Icon을 명시적 비동기 로드 후 콜백에서 설정하도록 수정.

NSPartSlotButton.h

TSharedPtr<FStreamableHandle> IconLoadHandle;

NSPartSlotButton::SetPart (Icon 처리 부분)

if (UTexture2D* LoadedIcon = InPartDefinition->Icon.Get())
{
    // 이미 메모리에 있으면 즉시 설정
    PartIconImage->SetBrushFromTexture(LoadedIcon);
    PartIconImage->SetVisibility(ESlateVisibility::HitTestInvisible);
}
else if (!InPartDefinition->Icon.IsNull())
{
    // 로드 완료 후 설정, WeakThis로 위젯 소멸 후 크래시 방지
    TWeakObjectPtr<UNSPartSlotButton> WeakThis(this);
    TSoftObjectPtr<UTexture2D> SoftIcon = InPartDefinition->Icon;
    IconLoadHandle = UAssetManager::GetStreamableManager().RequestAsyncLoad(
        SoftIcon.ToSoftObjectPath(),
        [WeakThis, SoftIcon]()
        {
            if (!WeakThis.IsValid()) return;
            if (UTexture2D* Tex = SoftIcon.Get())
            {
                WeakThis->PartIconImage->SetBrushFromTexture(Tex);
                WeakThis->PartIconImage->SetVisibility(ESlateVisibility::HitTestInvisible);
            }
            WeakThis->IconLoadHandle.Reset();
        });
}

NSPartSlotButton::ClearPart

if (IconLoadHandle.IsValid())
{
    IconLoadHandle->CancelHandle();
    IconLoadHandle.Reset();
}

참고 — 증강 쪽과의 비교

증강 아이콘은 카드 표시 전에 모든 아이콘을 일괄 RequestAsyncLoad하고, OnIconsLoaded 콜백 이후에 카드를 채우는 구조라 같은 문제가 없었음. 파츠는 슬롯 버튼 개별로 로드하는 방식으로 수정됨.

아웃런 진입 시 증강 삭제

증상

• 인런 > 아웃런으로 진입 시 인런에서 고른 증강들을 들고오는 형태
• 실제로 인런에서도 능력이 적용되어 있음

시도 1. 게임모드에서 증강 Clear부분을 추가

• 결과 화면이 보이고 아웃런으로 진입할때 증강들을 청소해주는 함수를 하나 만들고 거기서 증강 삭제

해결

void ANSRunGameMode::ClearAllAugments()
{
    if (!HasAuthority())
    {
        return;
    }

    ANSRunGameState* NSGameState = GetGameState<ANSRunGameState>();
    if (!NSGameState)
    {
        return;
    }
    for (APlayerState* PlayerState : NSGameState->PlayerArray)
    {
        ANSPlayerState* PS = Cast<ANSPlayerState>(PlayerState);
        if (!PS)
        {
            continue;
        }
        if (UNSAugmentInventoryComponent* Augment = PS->GetAugmentInventory())
        {
            Augment->ClearAll();
        }
    }
}

증강을 다 삭제하는 로직 추가

1. PartIconTool

왜 만들었나

파츠 줍기 프롬프트 위젯(드롭 파츠 Radius 진입 시 표시)에 파츠 이미지와 이름을 띄우려 했다. 파츠 이미지 소스로 콘텐츠 브라우저의 스켈레탈 메시 썸네일을 활용하고 싶었는데, 썸네일 캡처 API(ThumbnailTools, FObjectThumbnail)가 에디터 전용 모듈(UnrealEd) 에만 존재한다. 런타임 게임 모듈에서는 접근 자체가 불가하고, 패키징(쿠킹) 시 썸네일 데이터도 제거된다.

해결 방향은 두 가지였다:

• 방법 A — 런타임에 SceneCapture로 메시를 실시간 렌더해 RenderTarget을 아이콘으로 사용 → 드롭 프롬프트처럼 자주 뜨고 사라지는 UI에는 메모리/성능 부담이 큼
• 방법 B — 에디터에서 썸네일을 텍스처 애셋으로 1회 추출, UNSPartDefinition::Icon에 저장 → 런타임 비용 0, 기존 소프트 레퍼런스 비동기 로드 구조와 자연스럽게 연결됨

방법 B를 선택했고, 이 작업을 에디터 플러그인으로 구현했다.

왜 플러그인으로 만들었나

• 썸네일 캡처는 에디터 전용 기능이라 게임 빌드(Shipping)에 포함되면 안 됨
• 에디터 모듈을 게임 모듈 안에 넣으면 구조가 지저분해지고 유지보수가 어려움
• 플러그인(Type: Editor)은 에디터 빌드에만 포함되고 패키징 시 자동으로 제외됨
• 나중에 다른 프로젝트로 이식하거나 팀원과 공유하기 좋음

구성

Plugins/PartIconTool/
├── PartIconTool.uplugin                 (Editor 타입, LoadingPhase: PostEngineInit)
└── Source/PartIconTool/
    ├── PartIconTool.Build.cs
    ├── Public/
    │   ├── PartIconTool.h               (모듈 클래스 선언)
    │   └── PartIconToolSettings.h       (UDeveloperSettings — 캡처 파라미터)
    └── Private/
        └── PartIconTool.cpp             (2패스 SceneCapture + 메뉴 등록)

의존 모듈

동작 흐름

1. 콘텐츠 브라우저에서 UNSPartDefinition 에셋 1개 이상 선택 → 우클릭
2. "Generate Icon from Mesh" 클릭 (선택 항목 중 파츠 Definition이 없으면 메뉴 비노출)
3. GetDefault<UPartIconToolSettings>()으로 캡처 파라미터 읽기 (해상도/각도/밝기)
4. 각 Definition에 대해 PartMesh.LoadSynchronous()로 스켈레탈 메시 로드
5. Mesh->WaitForPendingInitOrStreaming() + FlushRenderingCommands() — 렌더 리소스 준비 대기
6. FPreviewScene 생성 — 격리된 씬에 메시 + 라이트 + USceneCaptureComponent2D 배치
7. GShaderCompilingManager->FinishAllCompilation() — 머티리얼 셰이더 컴파일 완료 대기
8. 1패스 (SCS_FinalColorLDR) — 색상 BGRA8 캡처
9. 2패스 (SCS_SceneColorHDR) — 커버리지 마스크 캡처, 1 - alpha로 누끼 알파 생성
10. 두 패스 픽셀 합성 후 UTexture2D 애셋 생성
    • 저장 경로: Definition과 같은 폴더, 이름 T_<DefName>_Icon
    • 설정: TC_EditorIcon / TEXTUREGROUP_UI / NeverStream = true / SRGB = true
    • 같은 이름 애셋이 이미 있으면 덮어쓰기(재생성)
11. 생성된 텍스처를 Def->Icon에 지정
12. 텍스처 패키지 + Definition 패키지 둘 다 디스크 저장
13. 성공/건너뜀 개수 알림 팝업 표시

PartMesh가 비어 있는 Definition은 경고 로그 출력 후 건너뜀.

캡처 파라미터 조절: Project Settings > Plugins > Part Icon Tool에서 빌드 없이 조절 가능.

코드 진화 과정

요구사항 시작점

파츠 줍기 프롬프트에 아이콘을 보여주기로 했고, 그 아이콘을 스켈레탈 메시 썸네일처럼 찍어서 쓰고 싶다는 요구였다. 처음엔 ThumbnailTools로 썸네일을 그대로 읽어 텍스처로 저장하는 구조로 시작했다.

1세대 — ThumbnailTools 기반

GenerateThumbnailForObjectToSaveToDisk(Mesh)
→ FObjectThumbnail → 픽셀 추출 → UTexture2D 저장

문제: 처음 캡처된 이미지가 완전히 검정이었다. 렌더 리소스가 GPU에 올라가기 전에 캡처되었기 때문. WaitForPendingInitOrStreaming() + FlushRenderingCommands()를 추가했지만 여전히 검정이 나왔다. ThumbnailTools 자체가 에디터 뷰포트 상태에 의존적이라 격리된 환경에서 안정적으로 동작하지 않는다는 결론.

2세대 — SceneCapture + FPreviewScene 기반 (현재)

썸네일 렌더러에 의존하지 않고 USceneCaptureComponent2D로 직접 메시를 찍는 구조로 전환했다. FPreviewScene으로 격리된 씬을 만들고 메시 컴포넌트와 라이트, 카메라를 직접 배치한다.

FPreviewScene
  └── USkeletalMeshComponent (파츠 메시)
  └── USceneCaptureComponent2D
        → UTextureRenderTarget2D → 픽셀 읽기 → UTexture2D 저장

이 구조로 전환하자 검정 문제가 사라졌다.

누끼(배경 투명화) 요구

아이콘을 위젯 배경에 자연스럽게 녹이고 싶다는 요구가 추가됐다. SCS_FinalColorLDR은 렌더 안 된 영역도 alpha=1(불투명)로 채워서 검정 배경이 생긴다. 해결을 위해 2패스 캡처로 전환:

• 1패스 (SCS_FinalColorLDR) — 색상 정확도 높은 BGRA8 캡처
• 2패스 (SCS_SceneColorHDR) — alpha 채널에 커버리지 마스크 포함 (1 - alpha = 메시가 있는 곳)

두 패스 결과를 합쳐서 1패스 색상 + 2패스 커버리지를 alpha로 적용, 배경이 투명한 PNG형 텍스처 생성.

// 1패스: 색상 픽셀 읽기
Capture->CaptureSource = SCS_FinalColorLDR;
Capture->CaptureScene();
RTResource->ReadPixels(Pixels, ...);

// 2패스: 알파(커버리지) 픽셀 읽기
Capture->CaptureSource = SCS_SceneColorHDR;
Capture->CaptureScene();
MaskResource->ReadLinearColorPixels(MaskPixels);

// 합성
for (int32 i = 0; i < Pixels.Num(); ++i)
{
    const float Coverage = FMath::Clamp(1.f - MaskPixels[i].A, 0.f, 1.f);
    Pixels[i].A = static_cast<uint8>(FMath::RoundToInt(Coverage * 255.f));
}

머티리얼 미로드 문제

2세대로 전환 후 메시가 렌더되긴 하는데 머티리얼이 모두 흰색(기본 머티리얼)으로 나오는 문제가 생겼다. 원인은 머티리얼 셰이더가 아직 컴파일 중인 상태에서 캡처했기 때문. GShaderCompilingManager->FinishAllCompilation() 호출로 해결.

과노출 문제

라이트 밝기(LightBrightness=4.0) + 자동 노출(AutoExposure=1.0)이 겹쳐서 메시 전체가 흰색으로 날아가는 문제가 발생했다. LightBrightness를 1.0으로 낮추고 ShowFlags.SetBloom(false)로 블룸 번짐을 차단했다.

캡처 설정 조정 요구 → UDeveloperSettings 도입

각도나 밝기를 코드 수정 없이 바꿀 수 있게 해달라는 요구. UDeveloperSettings(config=Editor)를 상속한 UPartIconToolSettings 클래스를 추가해 Project Settings > Plugins > Part Icon Tool 에서 직접 조절할 수 있게 했다. 빌드 없이 설정 변경 후 바로 Generate하면 즉시 반영된다.

최종 구조

Plugins/PartIconTool/
├── PartIconTool.uplugin
└── Source/PartIconTool/
    ├── PartIconTool.Build.cs
    ├── Public/
    │   ├── PartIconTool.h
    │   └── PartIconToolSettings.h       (UDeveloperSettings — 캡처 파라미터)
    └── Private/
        └── PartIconTool.cpp             (2패스 SceneCapture + 메뉴 등록)

캡처 파이프라인 요약

[콘텐츠 브라우저 우클릭 → Generate Icon from Mesh]
  ↓
PartMesh.LoadSynchronous() + WaitForPendingInitOrStreaming()
  ↓
FPreviewScene 생성 (메시 + 라이트 + SceneCaptureComponent2D)
  ↓
GShaderCompilingManager->FinishAllCompilation()   ← 셰이더 준비 대기
  ↓
1패스: SCS_FinalColorLDR → Pixels (색상)
2패스: SCS_SceneColorHDR → MaskPixels (커버리지)
  ↓
Pixels[i].A = 1 - MaskPixels[i].A              ← 누끼 합성
  ↓
UTexture2D 생성/갱신 (T_<DefName>_Icon, TC_EditorIcon)
  ↓
Def->Icon = 생성된 텍스처, 패키지 저장

의존 모듈

있었던 문제들 (요약)

사용 방법

1. 파츠 Definition 에셋(UNSPartDefinition)을 콘텐츠 브라우저에서 선택
2. 우클릭 → Generate Icon from Mesh
3. 같은 폴더에 T_<DefName>_Icon 텍스처가 생성되고 Icon 필드에 자동 지정됨
4. 이후 드롭 파츠 Radius 진입 시 프롬프트에 파츠 이름 + 아이콘 표시

각도나 밝기를 조정하려면 Project Settings > Plugins > Part Icon Tool 에서 수치를 바꾼 뒤 다시 Generate하면 된다. 빌드 불필요.

파츠를 추가할 때마다 이 작업을 1회 실행해야 아이콘이 갱신된다.

1. 상호작용 프롬프트가 특정 파츠에서만 안 뜸

증상
일부 드롭 파츠에 다가가도 프롬프트 위젯이 표시되지 않음. 다른 파츠는 정상.

원인
NSInteractionComponent::OnSphereBeginOverlap에서 겹침 시점에 CanInteract()를 검사해 후보 목록에서 제외했음.
드롭 파츠는 비동기로 데이터(StoredInstance)를 채우기 때문에, 겹침 이벤트가 먼저 도착하면 CanInteract = false → 후보에서 영구 제외.

해결
OnSphereBeginOverlap에서 CanInteract 검사 제거. 모든 INSInteractable 구현체를 즉시 후보에 추가.
UpdateActiveTarget(Tick)에서 CanInteract를 매 프레임 재검사해 활성 대상을 결정.

// NSInteractionComponent.cpp — BeginOverlap
// 이전: CanInteract 통과한 것만 추가
// 수정: 구현체면 무조건 추가, 유효성은 Tick에서 판단
if (OtherActor->Implements<UNSInteractable>())
{
    Candidates.AddUnique(OtherActor);
}

2. 프롬프트 위치가 완전히 엉뚱한 곳에 표시됨

증상
프롬프트 위젯이 파츠/NPC 위에 뜨지 않고 화면 한쪽 구석이나 허공에 표시됨.

원인 1 — 바운드 계산이 DetectionSphere 포함
ShowPromptFor에서 액터 바운드(GetActorBounds)를 기준으로 상단 Z를 계산했는데, USphereComponent 반경이 합산되어 높이가 수백 유닛 이상 튀었음.

원인 2 — 상의(Body) 파츠 메시 피벗 어긋남
SetupVisual에서 MeshComp를 Z 방향으로 보정해 이동했지만, DetectionCollision과 PromptAnchor는 루트에 고정된 채 그대로여서 보이는 메시와 위치가 달랐음.

해결
각 액터에 USceneComponent PromptAnchor를 추가하고, INSInteractable 인터페이스에 GetPromptWorldLocation() 메서드를 추가.
ShowPromptFor는 바운드 계산 대신 이 메서드 결과를 사용.
SetupVisual에서 메시 Z 보정 후 DetectionCollision과 PromptAnchor도 함께 재배치.

// NSDroppedPart.cpp — SetupVisual
const FVector MeshCenter(MeshBounds.Origin.X, MeshBounds.Origin.Y, MeshBounds.BoxExtent.Z);
if (DetectionCollision) { DetectionCollision->SetRelativeLocation(MeshCenter); }
if (PromptAnchor)       { PromptAnchor->SetRelativeLocation(MeshCenter + FVector(0, 0, MeshBounds.BoxExtent.Z + 30.f)); }

3. F 키를 눌러도 파츠 줍기/교체가 안 됨

증상
프롬프트는 뜨는데 F를 눌러도 파츠가 장착되지 않음. 아무리 가까이 붙어도 동일.

원인
TryPickup에서 GetActorLocation()(루트 위치)과 플레이어 위치 사이의 거리를 비교했는데,
SetupVisual이 MeshComp를 Z 보정해도 루트는 그대로라 실제 메시 위치와 루트 위치가 달랐음. 루트 기준 거리가 항상 임계값 초과.

해결
거리 계산 대신 DetectionCollision->IsOverlappingActor(InstigatorPawn) 사용.
프롬프트가 뜨는 조건(DetectionSphere 겹침)과 동일한 기준이므로 데드존 없음.

// NSDroppedPart.cpp — TryPickup
if (!DetectionCollision || !DetectionCollision->IsOverlappingActor(InstigatorPawn))
{
    return;
}

4. NSInteractionComponent가 Controller에 붙어 있어 상호작용이 항상 실패

증상
TryInteract 호출 시 항상 ActiveTarget이 없어서 아무것도 실행 안 됨.
OnSphereBeginOverlap도 한 번도 호출 안 됨.

원인
NSInteractionComponent를 NSPlayerController 생성자에서 만들었는데,
TryInteract가 Pawn에서 FindComponentByClass를 했고 Controller에 붙은 컴포넌트는 Pawn에서 검색 안 됨.
또한 DetectionSphere가 Controller에 붙어 있어 월드에 존재하지 않으므로 겹침 이벤트 자체가 발생하지 않았음.

해결
NSPlayerCharacterBase 생성자로 이동. Pawn에 붙어야 물리 위치를 가져 DetectionSphere가 정상 작동.

// NSPlayerCharacterBase.cpp — 생성자
InteractionComp = CreateDefaultSubobject<UNSInteractionComponent>(TEXT("InteractionComp"));

5. LogStreamableManager: RequestAsyncLoad() called with empty or only null assets! 경고

증상
파츠 줍기(F)를 누를 때마다 로그 창에 경고 1줄씩 출력됨.
빈 공간에서 F를 누르면 경고 없음. 파츠 주울 때만 발생.

원인 추적 과정

1. 처음에는 GrantAbilities의 빈 배열 RequestAsyncLoad 의심 → 가드 추가했으나 경고 지속
2. [LoadHunt] 로그를 GrantAbilities와 ApplyPartEffect에 추가 → 경로는 유효하게 찍힘
3. GE/GA를 데이터 에셋에서 비워도 경고 발생 → GE/GA 아님 확인
4. 최종 원인: NSPartSlotButton::SetPart에서 PartIconImage->SetBrushFromSoftTexture(InPartDefinition->Icon) 호출 시 Icon이 None(미설정)이어서 내부적으로 빈 경로로 비동기 로드 요청 발생

해결
Icon.IsNull() 가드 추가.

// NSPartSlotButton.cpp — SetPart
if (!InPartDefinition->Icon.IsNull())
{
    PartIconImage->SetBrushFromSoftTexture(InPartDefinition->Icon);
    PartIconImage->SetVisibility(ESlateVisibility::HitTestInvisible);
}
else
{
    PartIconImage->SetBrushFromTexture(nullptr);
    PartIconImage->SetVisibility(ESlateVisibility::Hidden);
}

교훈
SetBrushFromSoftTexture는 내부에서 RequestAsyncLoad를 직접 호출함.
소프트 레퍼런스를 넘기기 전에 반드시 IsNull() 검사 필요.

6. DetectionRadius 값과 실제 스피어 반경이 에디터에서 동기화 안 됨

증상
에디터 Details 패널에서 DetectionRadius를 바꿔도 스피어 시각화 크기가 즉시 반영되지 않음.

원인
생성자에서 SetSphereRadius(InteractRadius) 한 번만 호출. 에디터 수정 시 재호출 없음.

해결
OnConstruction에서 SetSphereRadius 재호출. 에디터에서 값 변경 시마다 OnConstruction이 재실행됨.

void ANSDroppedPart::OnConstruction(const FTransform& Transform)
{
    Super::OnConstruction(Transform);
    if (DetectionCollision) { DetectionCollision->SetSphereRadius(InteractRadius); }
}

NPC 베이스(NSInteractableNPCBase)도 동일 패턴 적용.

7. Server RPC가 _Implementation 빌드 에러 또는 미호출

증상
UFUNCTION(Server, Reliable) 선언 후 빌드 에러 또는 런타임에 RPC가 실행 안 됨.

원인
UE5에서 Server RPC는 함수명이 반드시 Server_로 시작해야 UHT가 올바르게 처리함.
ServerRequestEquip처럼 접두사 없이 쓰면 _Implementation 생성이 의도대로 안 될 수 있음.

해결
Server_RequestEquip, Server_RequestPickup 등 Server_ 접두사로 통일.
Client_ RPC도 동일하게 Client_ 접두사 사용.

9. 리슨 서버에서 클라 플레이어 주변의 상호작용 위젯이 호스트 화면에도 표시됨

증상
2인 리슨 서버 환경. 클라이언트 플레이어가 상호작용 액터(NPC 또는 드롭 파츠)에 접근하면,
클라이언트 화면에는 정상적으로 프롬프트 위젯이 뜨지만 호스트 화면에도 동일 위젯이 표시됨.
클라 플레이어가 멀어지면 호스트 화면의 위젯도 사라짐.

원인
NSInteractionComponent::BeginPlay에서 모든 머신의 모든 폰에 대해 무조건 셋업을 실행했기 때문.

리슨 서버는 모든 플레이어 폰을 서버 프로세스 안에서 관리한다. 문제는 두 가지였다.

1. 오버랩 델리게이트가 비로컬 폰에도 바인딩됨
   BeginPlay에서 IsLocallyControlled() 검사 없이 DetectionSphere->OnComponentBeginOverlap.AddDynamic(...) 을 호출해, 호스트 위에서 실행되는 클라 폰의 NSInteractionComponent에도 델리게이트가 붙었다.

2. DetectionSphere 콜리전이 모든 폰에서 활성 상태
   생성자에서 SetCollisionProfileName(TEXT("OverlapAllDynamic"))만 설정하고 콜리전 자체를 끄지 않아, 비로컬 폰의 스피어도 오버랩 이벤트를 발생시켰다.

결과적으로 호스트 위에서 돌아가는 클라 폰이 오버랩을 감지 → Candidates에 추가 → Tick에서 UpdateActiveTarget 실행 → 위젯을 호스트 화면에 표시하는 흐름이 발생했다.

UpdateActiveTarget 내부의 GetOwnerController() 가드(if (!PC))는 컨트롤러 유무만 보는데,
리슨 서버에서 원격 플레이어 폰도 서버 입장에서 GetController()가 non-null PlayerController를 반환하므로 이 가드는 원격 폰을 걸러내지 못한다.

해결
컴포넌트에 EnableLocalInteraction() 함수를 추가하고, 로컬 전용 셋업을 이 함수 하나로 집중. 비로컬·중복 호출은 즉시 리턴.

변경된 파일과 내용:

NSInteractionComponent.h

• EnableLocalInteraction() public 함수 추가
• IsOwnerLocallyControlled() private 헬퍼 추가
• bLocalInteractionEnabled 중복 방지 플래그 추가

NSInteractionComponent.cpp

• 생성자: DetectionSphere->SetCollisionEnabled(ECollisionEnabled::NoCollision) 추가
  → 비로컬 폰의 스피어는 콜리전 쿼리 자체가 발생하지 않음

• BeginPlay: 오버랩 바인딩 / 위젯 클래스 세팅 제거, EnableLocalInteraction() 호출로 대체
  → attach 등 머신 공통 셋업만 남음. 스탠드얼론/리슨 호스트 본인 폰은 이미 possess 돼 있어 여기서 활성화됨

• EnableLocalInteraction() 구현:

  void UNSInteractionComponent::EnableLocalInteraction()
  {
      if (bLocalInteractionEnabled) { return; }
      if (!IsOwnerLocallyControlled()) { return; }
  
      bLocalInteractionEnabled = true;
  
      if (PromptWidgetClass) { PromptWidgetComponent->SetWidgetClass(PromptWidgetClass); }
      DetectionSphere->OnComponentBeginOverlap.AddDynamic(this, &UNSInteractionComponent::OnSphereBeginOverlap);
      DetectionSphere->OnComponentEndOverlap.AddDynamic(this, &UNSInteractionComponent::OnSphereEndOverlap);
      DetectionSphere->SetCollisionEnabled(ECollisionEnabled::QueryOnly);
  }

• IsOwnerLocallyControlled() 구현: APawn::IsLocallyControlled() 사용

NSPlayerCharacterBase.h/.cpp

• OnRep_Controller() 오버라이드 추가
• PossessedBy(서버/리슨 호스트 경로)와 OnRep_Controller(클라이언트 본인 폰 — 컨트롤러가 리플리케이션으로 도착하는 시점) 양쪽에서 EnableLocalInteraction() 호출

OnRep_PlayerState가 아닌 OnRep_Controller를 진입점으로 쓴 이유: IsLocallyControlled()는 내부적으로 Controller에 의존하고, 클라이언트 본인 폰에는 Controller가 리플리케이트된다. BeginPlay 단독으로는 클라이언트에서 컨트롤러가 아직 null일 수 있어 불안정하다.

결과

비로컬 폰의 DetectionSphere는 NoCollision 상태로 남아 오버랩 이벤트 자체가 발생하지 않으며, 오버랩 델리게이트 바인딩과 위젯 인스턴스 생성도 일어나지 않는다.

기록일: 2026-06-22
브랜치: feature/NPC-Interaction
관련 파일: NSInteractionComponent, NSInteractable, NSInteractableNPCBase, NSPartsNPC, NSPetNPC, NSPartEquipWidget, NSPetUpgradeWidget, NSPlayerCharacterBase

전체 구조 한눈에 보기

[플레이어 폰]
  └── NSInteractionComponent     감지 + 입력 처리 + RPC 담당
        └── DetectionSphere      근접 오버랩 감지
        └── PromptWidgetComponent 화면에 띄우는 상호작용 프롬프트

[NPC 액터]
  └── ANSInteractableNPCBase     NPC 공통 베이스 (ACharacter + INSInteractable)
        └── ANSPartsNPC          파츠 장착 NPC
        └── ANSPetNPC            펫 강화 NPC

상호작용 흐름

① 플레이어가 NPC에 접근
   DetectionSphere 오버랩 → Candidates 목록에 추가 → Tick 활성화

② Tick마다 UpdateActiveTarget() 실행
   후보 중 가장 가까운 INSInteractable 대상 → ActiveTarget
   해당 NPC의 PromptAnchor 위치에 프롬프트 위젯 표시

③ F키 입력 → TryInteract()
   클라이언트에서 CanInteract 사전 검사 (반응성용)
   → Server_RequestInteract(Target) RPC 전송

④ 서버에서 Server_RequestInteract_Implementation 실행
   CanInteract 재검증 (서버 권위)
   → 통과 시 Client_OnInteractApproved(Target) RPC 전송

⑤ 클라이언트에서 Client_OnInteractApproved_Implementation 실행
   Execute_OnInteract(Target, PC) 호출
   → ANSPartsNPC or ANSPetNPC의 OnInteract_Implementation 실행
   → 해당 UI 위젯 생성 + AddToViewport

인터페이스: INSInteractable

모든 상호작용 가능한 액터가 구현해야 하는 인터페이스.

Execute_OnInteract(Target, PC) 형태로 호출하는 이유: UHT가 자동 생성하는 정적 디스패처로, C++ 구현체든 BP 구현체든 올바른 쪽으로 알아서 디스패치한다.

NPC 베이스: ANSInteractableNPCBase

ACharacter + INSInteractable 조합. 공통 로직 구현.

• CanInteract_Implementation: PlayerState의 NSPlayerProgressComponent에서 IsNPCUnlocked(NPCId) 확인. NPCId는 에디터 Details → NPC 카테고리에서 설정.
• PromptText: 에디터 Details → NPC 카테고리에서 직접 입력.
• PromptAnchor: 프롬프트 위젯이 뜰 위치. 에디터에서 드래그로 조정 가능.
• DetectionCollision: NSInteractionComponent의 DetectionSphere가 오버랩 감지에 사용.

NSInteractionComponent 주요 설계 포인트

비로컬 폰 격리 (EnableLocalInteraction)

리슨 서버에서 서버가 모든 플레이어 폰을 관리하기 때문에, 아무 처리 없이 두면 클라이언트 폰의 상호작용 UI가 호스트 화면에도 표시되는 문제가 생긴다.

해결: 로컬 전용 셋업(오버랩 바인딩 + 콜리전 활성화 + 위젯 클래스)을 EnableLocalInteraction() 하나로 집중하고, 비로컬 폰에서는 아무것도 하지 않는다.

생성자: DetectionSphere 콜리전 = NoCollision (기본 OFF)

EnableLocalInteraction() 호출 시점:
  - BeginPlay      → 스탠드얼론 / 리슨 호스트 폴백
  - PossessedBy    → 서버 / 리슨 호스트 경로  
  - OnRep_Controller → 클라이언트 본인 폰 경로 (컨트롤러 리플리케이션 도착 시)

IsLocallyControlled() == false → 즉시 리턴, 아무것도 안 함

Tick 최적화

오버랩 중인 후보가 없으면 Tick을 끈다. 후보가 생기면(BeginOverlap) 켜고, 전부 사라지면(EndOverlap) 다시 끈다.

서버/클라 역할 분리

UI: NSPartEquipWidget / NSPetUpgradeWidget

닫기(ESC) 처리: NativeOnKeyDown에서 Escape 키 감지 → RequestClose() 호출 → FReply::Handled() 반환으로 이벤트 소비. PIE에서는 ESC가 세션 종료로 먼저 잡히므로 테스트 시 BP 닫기 버튼 사용.

파일 목록

오늘할일 : 아웃런 NPC구현 및 상호작용시 UI띄우기(임시)

상호작용 시스템 — 설계 탐색

현재 구조는 NSInteractableActor가 있고, 어떤 위젯이 붙는지·어떤 컨트롤러가 붙는지·콜리전이나 상호작용 컴포넌트도 붙는 구조 (상속해서 사용하면 됨).

그런데 NPC는 추후 자기 방을 돌아다니거나 움직이는 로직이 필요하기 때문에 ACharacter를 상속받아야 해서 NSInteractableActor 상속 방식은 부적절하다고 판단.

대안으로 컴포넌트에 상호작용 책임을 부여하는 방향을 검토했다. 다만 상호작용 가능한 모든 액터에 컴포넌트를 붙이면 컴포넌트가 주인이 누구인지(NPC인지 파츠인지)를 알아야 하는 문제가 생긴다. 이를 해결하기 위해 인터페이스 도입을 고려 — 컴포넌트는 구체적인 타입은 모르고 인터페이스 여부만 확인하면 된다.

역할 분리 초안:

• 컴포넌트 — 감지, 프롬프트 표시, 신호 발생
• 인터페이스 — 물어보면 답할 수 있게끔 (함수 제공, PlayerController 감지 등)

상호작용 시스템 — 최종 설계 확정

위 방식에서 한 번 더 방향을 바꿨다.

상호작용 가능한 액터 각각에 컴포넌트를 붙이는 것보다, 캐릭터에 상호작용 컴포넌트를 달아서 캐릭터가 판단하는 구조가 더 낫다고 결론 냈다.

이유: 상호작용 가능한 액터가 두 개 있고 둘의 콜리전 안에 동시에 들어가 있을 때, 어떤 액터와 상호작용할지 중재하는 주체가 캐릭터 컴포넌트여야 처리가 깔끔하다.

확정 구조:

• 상호작용 액터: INSInteractable 인터페이스 상속 + Sphere 콜리전만 보유
• 상호작용 컴포넌트: 캐릭터에 부착, TickComponent로 가장 가까운 액터를 선택
  • TickInterval을 크게 설정해서 갱신 횟수 최소화
• 동시 범위 진입 시: 캐릭터 위치로부터 가장 가까운 액터와 상호작용
• 프롬프트 위젯: World 좌표에 부착 (레퍼런스 게임과 동일 방식). HUD 방식은 추후 대화창 등에서 활용 예정

구현한 것

• INSInteractable 인터페이스 추가
• NSInteractionComponent — 캐릭터에 부착, 범위 내 액터 감지 + 가까운 대상 선택
• 기존 NSInteractableActor 리팩터링 — 컴포넌트/콜리전 분리, 인터페이스 상속 구조로 정리
• NPC에 컴포넌트+인터페이스 조합 적용 가능한 구조 완성

공부한 것

• TArray를 인덱스로 순회하면서 RemoveAt이 필요한 경우 → 뒤에서부터 순회하면 RemoveAt의 메모리 이동 비용을 줄일 수 있다. 단, 권장 패턴은 아니므로 상황에 따라 판단.
• 언리얼에서는 이터레이터 호환성 때문에 --i (전위 감소 연산자)를 습관화하는 것이 좋다.

알고리즘

비트 연산자

XOR

XOR는 ^로 정의되어있다.

AND

AND는 &로 정의

OR

OR는 |로 정의

NOT

NOT은 ~로 정의되어있다. (비트반전)

<<

좌측 시프트, 비트들을 왼쪽으로 이동 (빈자리는 0으로 채움)

>>

우측 시프트, 비트들을 오른쪽으로 이동

1. 파츠 드롭 스폰 공용 진입점 추출

배경

기존에 바닥에 파츠를 떨어뜨리는 코드는 UNSPartEquipComponent::SpawnDroppedPart(private) 하나에만 있었다.
이 함수는 플레이어가 파츠를 교체할 때 기존 파츠를 발 아래에 떨어뜨리는 경로 전용으로 설계되었고, UNSPartEquipComponent 자체도 PlayerState에 부착된 컴포넌트다.

문제는 몬스터 드롭이다. 몬스터 사망 상황에서는 플레이어가 주체가 아니므로, ANSDroppedPart를 월드에 스폰하는 로직이 별도의 공용 진입점을 필요로 했다.
기존 구조를 그대로 쓰려면 아래처럼 어색한 우회가 필요했다.

몬스터 사망
  → 임의 플레이어의 PlayerState 획득
  → PlayerState → PartEquipComponent 접근
  → SpawnDroppedPart() 호출

왜 문제가 되는가

1. 불필요한 의존성
   월드에 드롭 오브젝트를 스폰하는 행위는 플레이어나 PlayerState와 직접적인 관련이 없다. 그런데 스폰 로직이 UNSPartEquipComponent 안에 묻혀 있어서, 몬스터 드롭 오케스트레이터(GameMode)가 굳이 PlayerState를 경유해야 하는 구조가 된다.

2. 스폰 규약 중복 위험
   ANSDroppedPart는 SpawnActorDeferred → Initialize → FinishSpawning 순서를 반드시 지켜야 한다.
   특히 Initialize 전에 FinishSpawning을 호출하면 StoredInstance가 비어서 비주얼과 픽업 로직이 모두 깨진다. 이 규약이 여러 군데 흩어지면 한 곳에서 빠뜨릴 가능성이 커진다.

3. 팩토리 함수 위치가 부자연스러움
   인스턴스 메서드(비-static)로 두면 이 함수를 호출하기 위해 이미 ANSDroppedPart 인스턴스가 하나 있어야 한다. 하지만 이 함수의 역할 자체가 새로운 ANSDroppedPart를 생성하는 것이므로, static 팩토리 함수나 외부 매니저에 두는 편이 더 자연스럽다.

해결 방법

ANSDroppedPart에 static 팩토리 헬퍼 SpawnInWorld를 추가했다.

// NSDroppedPart.h
static ANSDroppedPart* SpawnInWorld(
    UWorld* World,
    TSubclassOf<ANSDroppedPart> Class,
    const FNSPartData& Part,
    const FVector& Location);

동작 규칙

• Class가 nullptr이면 ANSDroppedPart::StaticClass()로 폴백한다.
• 내부에서 SpawnActorDeferred → Initialize → FinishSpawning 순서를 완전히 처리한다.
• 실패 시 nullptr를 반환한다.

기존 코드 정리

기존 UNSPartEquipComponent::SpawnDroppedPart는 이제 공용 헬퍼를 호출하는 얇은 래퍼가 되었다.

// NSPartEquipComponent.cpp
void UNSPartEquipComponent::SpawnDroppedPart(const FNSPartData& Part, const FVector& Location)
{
    ANSDroppedPart::SpawnInWorld(GetWorld(), DroppedPartClass, Part, Location);
}

변경 효과

핵심은 드롭 스폰의 책임을 PlayerState 기반 컴포넌트에서 월드 오브젝트 팩토리로 이동시킨 것이다.
이렇게 하면 장착 교체 드롭과 몬스터 드롭이 같은 규약을 공유하면서도, 호출 주체는 서로 독립적으로 유지할 수 있다.

2. GameMode 재화 Multiplier 에디터 노출

배경

런 종료 시 영구 재화(공통 재화 / 스킬 재화)를 확정할 때, 클리어 여부에 따라 획득량 배율을 적용하고 있었다.

• 클리어: 100% → ClearMultiplier = 1.0f
• 전멸(실패): 50% → FailMultiplier = 0.5f

기존에는 이 값이 코드에 하드코딩되어 있어, 밸런스 조정 때마다 재컴파일이 필요했다.

변경 내용

ANSRunGameMode에 EditDefaultsOnly 프로퍼티를 추가해 에디터에서 직접 조정할 수 있도록 했다.

// NSRunGameMode.h
UPROPERTY(EditDefaultsOnly, Category = "Currency")
float ClearMultiplier = 1.0f;

UPROPERTY(EditDefaultsOnly, Category = "Currency")
float FailMultiplier = 0.5f;

의미

• 디테일 패널의 Currency 카테고리에서 수치를 수정할 수 있다.
• 코드 수정과 재컴파일 없이 밸런스 조정이 가능하다.
• 런 보상 정책을 디자이너 친화적으로 바꾼 셈이다.

3. 다음 작업 메모

몬스터 드롭 오케스트레이터 자체는 아직 미구현이다.
다만 연결 지점은 이미 확보되었다.

현재 확보된 지점

• 진입점: ANSRunGameMode::NotifyEnemyKilled_Implementation (NSRunGameMode.cpp:127)

  • HasAuthority() 가드가 있어 서버 전용 실행이 보장된다.
  • ACharacter* DeadEnemy로 사망 위치(GetActorLocation())를 얻을 수 있다.

• 재화 스폰: UNSCurrencyDropSubsystem::RegisterDrop(...)

  • 재화 드롭 저장과 관리 로직은 이미 완성되어 있다.

• 파츠 스폰: ANSDroppedPart::SpawnInWorld(...)

  • 이번 작업으로 공용 스폰 진입점이 준비되었다.

아직 남은 것

• DroppedPartClass를 GameMode에서 어떻게 참조할지 결정 필요
  • 예정안: EditDefaultsOnly UPROPERTY로 노출
• 드롭 테이블 설계
  • 어떤 재화 / 파츠가 어떤 확률로 드롭되는지
• 위치 분산 로직
  • 예: 원형 오프셋 기반 배치
• FNSPartData 생성 규칙
  • 등급, 종류, 옵션 등 실제 드롭 인스턴스 결정 방식

4. 재화 드롭 시스템 정리

UNSCurrencyDropSubsystem::RegisterDrop

몹이 죽었을 때 실제 드롭 정보를 등록하는 함수다.
초기에 호출되는 RemoveExpiredDrops()는 만료된 드롭 데이터를 먼저 정리하는 역할을 한다.

FFastArraySerializer

일반적인 TArray + UPROPERTY(Replicated) 조합은 배열 원소 하나만 바뀌어도 전체 배열을 직렬화해서 전송할 수 있다.
반면 FFastArraySerializer는 변경분(델타)만 전송하도록 설계된 언리얼 전용 구조다.

특징

• 원소 추가 / 변경 시 해당 항목만 전송
• 원소 삭제 시 삭제 마커만 전송
• 원소 단위 콜백 제공
  • PostReplicatedAdd
  • PostReplicatedChange
  • PreReplicatedRemove

즉, 드롭처럼 자주 추가/삭제되고 개별 항목 단위 반응이 중요한 데이터에 잘 맞는다.

오버랩 감지 흐름

ANSCurrencyPickup (오버랩 감지)
  → Server_CollectCurrency RPC [NSPlayerState.cpp:115]
  → DropSubsystem::TryCollect() [NSCurrencyDropSubsystem.cpp:79]

이 흐름은 클라이언트가 오버랩을 감지해도 실제 수집 확정은 서버에서 처리한다는 점이 핵심이다.

5. 알고리즘 메모

void convert(string& m, unordered_map<string, string>& words) {
    for (auto& [key, value] : words) {
        auto it = m.find(key);
        while ((it = m.find(key, it)) != string::npos) {
            m.replace(it, key.length(), value);
            it++;
        }
    }
}

동작 방식

• find로 문자열 m 안에서 key가 등장하는 위치를 찾는다.
• 찾은 위치 it를 기준으로 replace를 호출해 value로 치환한다.
• replace는 한 번에 한 위치만 바꾸므로, while 루프를 돌며 끝까지 반복 적용한다.

메모

it++를 하는 이유는 방금 치환한 위치 바로 다음부터 다시 찾기 위해서다.
다만 치환 문자열 길이나 중첩 패턴에 따라 의도하지 않은 재탐색 이슈가 생길 수 있으므로, 실제 문제에서는 증가 폭을 어떻게 둘지 주의해서 봐야 한다.

6. 언리얼 엔진 용어 정리

오브젝트 (UObject)

오브젝트는 언리얼 엔진의 가장 기본적인 클래스 계층의 출발점이다.
거의 모든 시스템이 UObject를 직접 상속하거나, 그 기능을 기반으로 동작한다.

UObject가 제공하는 것

• 가비지 컬렉션 지원
• 에디터 변수 노출을 위한 메타데이터 시스템
• 로딩 / 저장 / 직렬화 기반 기능
• 에셋과 런타임 객체의 공통 기반 구조

즉, 언리얼에서 오브젝트는 단순한 C++ 클래스가 아니라 엔진 레벨 관리 기능이 붙은 반사 가능한 객체라고 보는 것이 맞다.

FSoftObjectPath 와 TSoftObjectPtr

FSoftObjectPath

에셋의 전체 경로를 문자열 형태로 들고 있는 가벼운 구조체다.
에디터에서는 마치 UObject*를 고르는 프로퍼티처럼 보이지만, 실제로는 경로 기반 참조다.

TSoftObjectPtr

기본적으로 FSoftObjectPath를 감싸는 형태이며, 특정 클래스 타입으로 제한할 수 있다.
참조 대상이 이미 메모리에 로드되어 있으면 Get()으로 바로 접근할 수 있고, 로드되지 않았다면 소프트 경로를 이용해 로드한 뒤 다시 접근한다.

언제 유용한가

• 아티스트 / 디자이너가 에디터에서 에셋 레퍼런스를 직접 세팅할 때
• 당장 메모리에 올리지 않고 필요 시점에 로드하고 싶을 때

반대로, 조건 기반으로 많은 에셋을 탐색해야 하는 경우에는 소프트 레퍼런스만으로 해결하기보다 에셋 레지스트리나 오브젝트 라이브러리를 고려하는 편이 좋다.

에셋 레지스트리와 오브젝트 라이브러리

에셋 레지스트리

에셋 자체를 로드하지 않고도 메타데이터를 조회할 수 있게 해 주는 시스템이다.
콘텐츠 브라우저가 에셋 정보를 보여줄 때도 사용되며, 게임플레이 코드에서도 로드되지 않은 에셋의 정보를 질의할 수 있다.

핵심은 에셋 본체를 메모리에 올리지 않고도 검색과 분류가 가능하다는 점이다.

오브젝트 라이브러리 (ObjectLibrary)

특정 폴더의 에셋들을 한꺼번에 모아 관리하기 쉽게 만들어 주는 도우미 객체다.
로드된 오브젝트 목록이나, 아직 로드되지 않은 에셋의 FAssetData 목록을 한데 모아 다룰 수 있다.

즉, 대량 에셋을 폴더 단위로 관리하거나 한 번에 수집해 다루고 싶을 때 유용하다.

FStreamableManager 와 비동기 로딩

FStreamableManager는 비동기 에셋 로딩을 담당하는 핵심 도구다.
비동기 로드를 요청하면, 로드 완료 시점에 콜백을 받아 후속 처리를 수행할 수 있다.

주의할 점

• 콜백 안에서 .Get()으로 잠깐 사용하고 끝낼 수는 있다.
• 이후에도 계속 사용할 객체라면, 실제 객체 포인터를 멤버로 저장해 강한 참조를 유지하는 쪽이 안전하다.

즉, 비동기 로딩의 핵심은 로드 시점 제어뿐 아니라 로드 후 객체 수명 관리까지 포함해서 생각하는 것이다.

목표

PIE 멀티 환경에서 재화 드랍 시스템을 빠르게 테스트할 수 있는 콘솔 치트명령 구현

문제 1. GameMode의 UFUNCTION(Exec)가 콘솔에서 실행되지 않음

현상

NSRunGameMode에 UFUNCTION(Exec) 함수를 만들고 콘솔(~)에서 호출해도 아무일도 일어나지 않음, 기존 로그만 출력되는 현상

원인

언리얼 콘솔 Exec 명령의 라우팅체인은

LocalPlayer -> PlayerController -> Pawn -> HUD -> PlayerCameraManager -> PlayerInput -> CheatManager -> GameInstance

콘솔(~) Exec 명령은 GameMode로 라우팅되지 않는다는 사실, GameMode는 이 체인에 없음 그래서 Debug_SpawnCurrency를 쳐도 함수 자체가 호출되지 않는문제였다.

해결방안

1. APlayerController로 옮기기(깔끔)
2. CheatManager 만들기 (나중에 사용할 수 있지 않을까?)

CheatManager쪽으로 가기로 했다. 추후에 다른 테스트 할때도 사용할 수 있지 않을까해서 그래서 CheatManager에서 Exec함수를 정의, NSPlayerController 생성자에서 CheatClass = UNSCheatManager::StaticClass()로 등록

문제 2. 클라에서 콘솔 입력시 "Command not recognized" 오류

현상

호스트 콘솔에서는 Debug_SpawnCurrency가 정상 실행 되지만, 클라 콘솔에서는 명령 자체를 인식 못함.

원인

UCheatManager는 엔진 기본 동작상 서버/스탠드얼론에서만 생성됨 (APlayerController::AddCheats가 NetMode != NM_Client 조건으로 가드됨), 순수 클라 PlayerController에는 CheatManager가 아예 생성되지 않아서 Exec 명령을 인식하지 못했음

해결

NSPlayerController::BeginPlay에서 로컬 컨트롤러인 경우 EnabledCheats()를 명시적으로 호출, 이 함수가 내부적으로 AddCheats(true)를 실행하여 클라에도 CheatManager를 강제 생성

void ANSPlayerController::BeginPlay()
{
    ...
    // 테스트용 임시 코드 - 드롭 테이블 연동 후 삭제
    EnableCheats();
    ...
}

문제 3. 클라에서 치트를 실행해도 호스트 발밑 재화가 생성되지 않음

현상

CheatManager가 클라에서도 인식된 뒤, 클라 콘솔에서 Debug_SpawnCurrency를 실행하면 호스트 캐릭터위치에 재화가 생성되지 않음, 클라 캐릭터 위치에만 생성됨

원인

RegisterDrop은 HasServerAuthority()가드가 있어 서버 권한에서만 실행됨. CheatManager는 클라 로컬에서 동작하므로 클라의 GetPlayerControllerIterator()는 로컬 컨트롤러만 보고, 드랍도 서버에 반영되지 않았음

해결

CheatManager에서 드랍 로직을 직접 실행하지 않고, ServerRPC를 통해 반드시 서버 권한에서 실행되도록 설계

클라 콘솔 입력
-> UNSCheatManager::Debug_SpawnCurrency() (클라 로컬)
-> ANSPlayerController::Server_DebugSpawnCurrency() (Server RPC -> 서버로 전송)
-> 서버에서 모든 PlayerController순회 -> RegisterDrop
-> 각 CurrencyReplicationProxy -> Client RPC -> 각 클라에서 LocalPickup 스폰

문제 4. 공통·스킬재화를 드랍했는데 메시가 안 보임

현상

Debug_SpawnCurrency 하나로 셋 다 드랍했더니 임시재화만 메시가 보이고, 공통/스킬은 줍기 로그는 떠도 메시가 안 보임

원인

치트가 셋 다 Grade1로 등록했는데, UNSCurrencyVisualData의 행 조회(FindVisual)는 CurrencyType + Grade 둘 다 일치해야 함. 설계상 임시재화만 등급(Grade1~)을 쓰고 공통/스킬은 Grade::None 이라, FindVisual(Common, Grade1)은 매칭 행이 없어 nullptr → 메시 미설정

해결

치트를 타입별로 분리(Debug_SpawnTemp / Debug_SpawnCommon / Debug_SpawnSkill)하고, 공통/스킬은 ENSCurrencyGrade::None으로 등록. → VisualData 조회 키와 일치

문제 5. 인런 중 획득한 영구재화도 임시재화처럼 HUD에 실시간 표시로 변경

배경

임시재화는 복제되는 Wallet에 들어가 HUD에 실시간 반영되지만, 공통/스킬재화는 서버 전용 PendingPermanent TMap에만 쌓여 클라가 볼 수 없음

검토한 두 방법

• 방법 A (Wallet 미러): AddRunPermanent에서 Pending 누적 + AddToWallet로 복제 경로에도 미러. 진실 원본은 Pending 유지. 커밋 로직 무변경
• 방법 B (Wallet 일원화): Pending TMap 제거, 전부 Wallet에 저장. 커밋이 Wallet을 읽고 비움

결정 → 방법 A

커밋 = 런 종료(게임오버) 시점이라, A의 단점이던 "커밋 후 Wallet 정리"가 무의미해짐(어차피 런 경계에서 리셋/파괴). Pending·Wallet은 같은 함수에서 같은 양을 더하므로 드리프트 불가, 진실 원본(Pending)을 안 건드리는 게 가장 좋아보였음

문제6. 아웃런 진입 시 지갑초기화

배경

Seamless Travel구조라서 PlayerState가 무조건 초기화된다는 보장이없어서 지갑을 추가적으로 초기화해주는 함수를 만들었다.

최종 구조

[호스트/클라 콘솔] Debug_SpawnCurrency
  → UNSCheatManager::Debug_SpawnCurrency()
  → ANSPlayerController::Server_DebugSpawnCurrency()  ← Server RPC
  → UNSCurrencyDropSubsystem::RegisterDrop() × N명  (서버)
  → ANSCurrencyReplicationProxy::SendSpawnEvent() × N명
  → Client_SpawnCurrency() × N명  ← Client RPC
  → ANSLocalCurrencyPickup 각자 로컬 스폰

관련 파일:

삭제 예정 (드롭 테이블 연동 후)

• Core/Cheat/NSCheatManager.h/.cpp — 전체
• NSPlayerController — Server_DebugSpawnCurrency 선언/구현, EnableCheats() 호출, 관련 인클루드
• NSPlayerController::BeginPlay — EnableCheats() 한 줄

변경 사항

• 재화(Currency) 시스템 구현 (서버 레지스트리 + 클라 로컬 비주얼)
  • UNSCurrencyDropSubsystem: 서버 전용 드랍 레지스트리
  • ANSCurrencyReplicationProxy: 플레이어당 1개, owner-only 복제로 Wallet 변경 전달
  • ANSLocalCurrencyPickup: 클라 로컬 비주얼 액터 (서버 비존재)
  • UNSCurrencyWalletComponent: FastArraySerializer 기반 지갑 (키: FGameplayTag)
  • PlayerState ServerRPC: 오버랩 시 서버 Wallet 적립
• 영구 재화 적립 구조: 런 중 PendingBucket 누적 → 런 종료 시 CommitRunPermanent(Multiplier) (클리어 1.0 / 전멸 0.5)
• ProgressComponent에 영구 재화 저장 및 HUD 연동
• GameMode에 Proxy 세팅 연결
• 디버그용 UNSCheatManager 추가 (재화 강제 지급 콘솔 커맨드)

테스트 방식

1. NSCurrencyVisualData를 상속받는 DA생성
2. DA 세팅

• Currency.Common/ Temp / Skill 존재, Grade는 Temp만 1~3등급으로 지정해주면 됨
• Scale은 크기

3. NSCurrencyReplicationProxy를 상속받는 BP생성
4. Currency > Visual Data에 만든 DA 지정
5. Debug 함수 실행

• SpawnTemp : 임시 재화 생성
• SpawnSkill : 스킬 재화 생성
• SpawnCommon : 공통 재화 생성
• Spawn함수들은 각플레이어 앞에 재화 생성
• CommitPermanent : 영구재화(스킬/공통)를 아웃런에 적립 (실제로는 런 종료시에 호출, 클리어/전멸)

참고 사항

• 투사체 시스템(ProjectileManagerComponent + ReplicationProxy + ProjectileVisual) 패턴을 그대로 미러링한 구조
• 드랍 확률/수치 밸런스(UNSCurrencyDropTable)는 별도 담당자 작업 예정
• 런 종료 commit 훅(OpenRunEndVote 경로)은 아직 미연결 — 허브 복귀 확정 시점에 연결 필요

추후 구현 사항

• 드롭 테이블 구현 후 재화 스폰 위치 구현 필요
• 파츠 쪽도 똑같이 몬스터 사망에서 구현 필요

1. 시스템 개요

몬스터가 죽으면 재화가 드랍되고, 각 플레이어가 독립적으로 줍는 구조. A가 줘도 B 화면엔 그대로 남는다. 서버 복제 액터가 0개라 스폰 비용이 낮다.

투사체 시스템(NSProjectileManagerComponent + NSProjectileReplicationProxy + NSProjectileVisual)과 동일한 패턴을 그대로 미러링했다. 차이가 있다면 WorldSubsystem을 활용했다.

2. 구성 요소

3. 동작 흐름

드랍 생성

몬스터 사망
→ NSRunGameMode::NotifyEnemyKilled (서버)
→ UNSCurrencyDropSubsystem::RegisterDrop(Type, Grade, Amount, Location, Duration)
  → DropId 발급, ActiveDrops에 FNSCurrencyDropEntry 등록
  → 등록된 모든 프록시에 SendSpawnEvent(FNSCurrencySpawnEvent)
    → 각 ANSCurrencyReplicationProxy::Client_SpawnCurrency (Client RPC)
      → 클라: ANSLocalCurrencyPickup 스폰 (Deferred + Initialize)
        → 비동기 메시 로드 (UNSCurrencyVisualData 조회)
        → 만료 타이머 시작 (Duration초 후 Destroy)

픽업

로컬 폰이 픽업 액터에 오버랩
→ SetActorHiddenInGame(true) — 즉각 UX (클라)
→ ANSPlayerState::Server_CollectCurrency(DropId) — 서버 RPC
  → UNSCurrencyDropSubsystem::TryCollect(DropId, PlayerState)
    검증 4단계:
    1. DropId 존재 여부
    2. 만료 시간 초과 여부
    3. 이미 이 플레이어가 주운 적 있는지 (CollectedPlayer)
    4. 서버 기준 거리 (300cm²)
    → 통과 시:
      - Currency.Temp → CurrencyComponent::AddTemp → Wallet 가산
      - Currency.Common/Skill → CurrencyComponent::AddRunPermanent → PendingPermanent 버킷
      - CollectedPlayer.Add
      - SendRemoveEvent(DropId) → 해당 클라 픽업 액터 Destroy
    → 실패 시:
      - SendRestoreEvent(DropId) → 픽업 액터 다시 보이게 복원

런 종료 (영구재화 확정)

NSRunGameMode::OnResultDisplayFinished
→ 각 PlayerState::CurrencyComponent::CommitRunPermanent(Multiplier)
  - 클리어: Multiplier = 1.0
  - 전멸: Multiplier = 0.5
  → PendingPermanent × Multiplier
  → Currency.Common → ProgressComponent::AddCommonCurrency
  → Currency.Skill → ProgressComponent::AddJobCurrency
  → PendingPermanent 비움
→ SaveAllPlayersProgress()
  → ProgressComponent::BuildPayload → Client_SaveProgress RPC
  → 클라 로컬 SaveGame 저장

4. 재화 종류별 저장 구조

용어 정리

• 버킷(PendingPermanent): 런 중 영구재화를 임시로 쌓아두는 서버 전용 TMap. 런 종료 시 배율 적용 후 ProgressComponent로 이동하고 비워진다.
• 지갑(Wallet): 임시재화 전용. FastArray로 복제돼 HUD에 실시간 표시. 저장 안 됨.
• 영구 지갑: ProgressComponent. 세이브 대상. Wallet이 아님.

5. 프록시 생명주기

ANSRunGameMode가 관리. 투사체 프록시와 나란히 처리됨.

프록시는 Owner = PlayerController, bOnlyRelevantToOwner = true라 해당 클라에만 복제됨. 서버가 SendSpawnEvent를 호출하면 그 PC의 클라에만 Client RPC가 날아감.

재화 시스템

ANSCurrencyReplicationProxy의 역할이 정확하게 뭐야? 존재는 서버에서 하는건가? 아니면 AActor상속을 받았으니까 복제용인건가?? 얘를 통해서 픽업액터, 재화컴포넌트 이런게 어떤식으로 소통하는거지?

ANSCurrencyReplicationProxy의 역할은 서버에 존재하지만 서버가 특정 한명의 클라이언트에게 명령을 전달하기 위한 통로역할 그래서 Proxy라는 대리자 명칭을 씀 또, Client RPC를 쏘기 위해서 AActor를 사용함, 이 액터는 복제되지만 데이터(프로퍼티)를 복제하려는게 아니고 Client RPC를 쏠 수 있는 자격을 얻기 위해 복제 액터, SceneRoot만 있고 복제 프로퍼티가 하나도 없는게 그 이유

서버에 플레이어 수만큼 생성하고 NSRunGameMode의 PostLogin/Logout에서 생성/소멸 됨 각 클라에는 자기 것 1개만 복제되어 존재, 호스트도 owner 클라 경로로 동일하게 처리

DropSubsystem: 몹 죽음 -> DropId 발급 -> 레지스트리 등록 -> 플레이어의 프록시를 찾아서 ClientRPC 발사(네트워크 경유), 프록시가 드롭 아이디별 픽업을 직접 관리한다.

FSoftObjectPath, TSoftObjectPtr, TSoftClassPtr

핵심 개념: 하드 참조 vs 소프트 참조

중요: UPROPERTY에 하드 참조를 걸면 그 클래스를 로드할 때 참조된 에셋 전체가 딸려 로드된다. DataAsset 하나가 맵 전체 에셋을 끌고 오는 참사의 원인.

FSoftObjectPath

FSoftObjectPath Path = TEXT("/Game/Assets/SK_Mesh.SK_Mesh");

• 순수 경로 문자열. 타입 정보 없음
• 직렬화, UI 표시, 에셋 레지스트리 조회 등 "경로를 다루는" 로우레벨 작업에 사용
• RequestAsyncLoad에 직접 넣을 수 있음
• Blueprint 노출보다는 C++ 내부 로직에서 경로 조작 시 사용

TSoftObjectPtr<T>

TSoftObjectPtr<UStaticMesh> Mesh;

• 타입이 있는 소프트 참조. FSoftObjectPath를 감싼 래퍼
• 에디터에서 드래그&드랍으로 에셋 지정 가능 (타입 필터링 지원)
• .Get() → 이미 로드되어 있으면 포인터 반환, 없으면 nullptr
• .IsValid() → 로드되어 있고 유효한지
• .IsNull() → 경로 자체가 비어 있는지
• UPROPERTY에 걸어도 참조한 에셋을 자동 로드하지 않음 → 메모리 안전
• 사용 전 RequestAsyncLoad 또는 LoadSynchronous 필요

// 비동기 로드 (권장)
StreamableManager.RequestAsyncLoad(Mesh.ToSoftObjectPath(), [this]()
{
    UStaticMesh* Loaded = Mesh.Get(); // 이제 유효
});

// 동기 로드 (게임스레드 블로킹 — 금지 원칙)
UStaticMesh* Loaded = Mesh.LoadSynchronous();

TSoftClassPtr<T>

TSoftClassPtr<UGameplayEffect> EffectClass;

• 클래스(UClass) 전용 소프트 참조. TSoftObjectPtr<UClass>와 개념적으로 동일하지만 타입 안전성 강화
• TSubclassOf<T> (하드)의 소프트 버전
• .Get() → TSubclassOf<T> 반환 (로드된 경우)
• GE/GA 같은 Blueprint 파생 클래스를 DataAsset에서 소프트 참조로 보관할 때 표준 패턴

// 패턴: DataAsset에 선언 → 필요할 때 비동기 로드 → SpawnActor/ApplyGE
TSoftClassPtr<UGameplayEffect> EffectClass;

// 로드 후 사용
TSubclassOf<UGameplayEffect> LoadedClass = EffectClass.Get();
if (LoadedClass)
{
    ASC->ApplyGameplayEffectToSelf(LoadedClass->GetDefaultObject<UGameplayEffect>(), 1.f, EffectContext);
}

정리: 언제 어떤 걸 쓰나

DataTable vs DataAsset

UDataTable

• 행(Row) 기반 데이터. 엑셀/CSV로 일괄 편집 가능
• 스키마: FTableRowBase를 상속한 USTRUCT
• 용도: 밸런스 수치, 텍스트 데이터, 반복 패턴 (몬스터 스탯, 드랍률, 보상 테이블)
• 편집: 에디터 내 테이블 뷰 or CSV 임포트
• 조회: FindRow<FMyRow>(FName, Context)
• 특징
  • 데이터가 많아져도 구조가 단순하게 유지됨
  • 기획자가 코드 없이 CSV로 수치 조정 가능
  • 에셋 참조(메시, 클래스 포인터)를 담는 건 가능하지만 어색함

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

    UPROPERTY(EditDefaultsOnly)
    float DropChance = 0.3f;

    UPROPERTY(EditDefaultsOnly)
    int32 MinAmount = 10;

    UPROPERTY(EditDefaultsOnly)
    int32 MaxAmount = 50;
};

// 사용
if (const FNSEnemyDropRow* Row = DropTable->FindRow<FNSEnemyDropRow>(EnemyId, TEXT("")))
{
    // Row->DropChance, Row->MinAmount ...
}

UDataAsset / UPrimaryDataAsset

• 단일 오브젝트 구조. 한 에셋 = 하나의 개념적 단위
• 용도: 구조적 참조, 설정 묶음 (캐릭터 정의, 파츠 정의, 능력치 셋)
• 특징
  • 에셋 번들(AssetBundles) 태그로 그룹 로드 제어 가능
  • UPrimaryDataAsset은 에셋 매니저로 ID 기반 조회 가능
  • 메시, 클래스 포인터, 복잡한 중첩 구조체를 담기에 적합
  • 소프트 참조(TSoftObjectPtr)와 함께 쓰면 온디맨드 로드 가능

UCLASS()
class UNSPartDefinition : public UPrimaryDataAsset
{
    UPROPERTY(EditDefaultsOnly)
    TSoftClassPtr<UGameplayEffect> EffectClass;  // 소프트 참조

    UPROPERTY(EditDefaultsOnly)
    TSoftObjectPtr<USkeletalMesh> PartMesh;       // 소프트 참조
};

역할 분리 원칙

DataTable  = "이 적이 얼마를 드랍하나?" (수치/밸런스)
DataAsset  = "이 파츠가 어떤 GE 클래스를 쓰나?" (구조/참조)

• DataAsset에 float/int 수치가 늘어나기 시작하면 → DataTable로 분리 검토
• DataTable에 메시/클래스 포인터가 많아지면 → DataAsset으로 분리 검토

소프트 참조 비동기 로드 패턴 (UE5)

FStreamableManager / UAssetManager

// 단일 에셋
FStreamableManager& Manager = UAssetManager::GetStreamableManager();
Manager.RequestAsyncLoad(
    SoftPtr.ToSoftObjectPath(),
    FStreamableDelegate::CreateUObject(this, &UMyClass::OnLoaded)
);

// 여러 에셋 묶음
TArray<FSoftObjectPath> Paths = { MeshA.ToSoftObjectPath(), MeshB.ToSoftObjectPath() };
Manager.RequestAsyncLoad(Paths, FStreamableDelegate::CreateLambda([this]()
{
    // 모두 로드 완료
}));

로드 핸들 관리

TSharedPtr<FStreamableHandle> LoadHandle;

// 저장해두면 중간에 취소 가능
LoadHandle = Manager.RequestAsyncLoad(Path, Callback);

// EndPlay 등에서 취소
if (LoadHandle.IsValid())
{
    LoadHandle->CancelHandle();
    LoadHandle.Reset();
}

.Get()의 null 체크 패턴

// 잘못된 패턴: 로드 여부 무시
UStaticMesh* Mesh = SoftMesh.Get(); // null일 수 있음
SetStaticMesh(Mesh);                // 크래시 위험

// 올바른 패턴: 로드 확인 후 사용
if (UStaticMesh* Mesh = SoftMesh.Get())
{
    SetStaticMesh(Mesh);
}
else
{
    // 비동기 로드 후 재진입
    LoadHandle = Manager.RequestAsyncLoad(SoftMesh.ToSoftObjectPath(), [this]()
    {
        SetStaticMesh(SoftMesh.Get());
    });
}

NeoSanctum 적용 사례

파츠 시스템 PIE 테스트 통합

무엇을 했나

파츠 시스템(드랍 → 줍기 → 장착)의 전체 흐름을 PIE에서 실제로 테스트하기 위한 임시 코드를 추가했다. 몬스터 드랍 연동과 상호작용 시스템이 아직 없어서, 두 군데에 우회 경로를 만들었다.

1. ANSDroppedPart — DebugDefinition 자동 Initialize

   • 레벨에 배치한 드랍 파츠 액터의 디테일 패널에서 DebugDefinition / DebugRarity / DebugValue를 지정하면 BeginPlay에서 자동으로 Initialize를 호출하도록 했다.
   • 원래 이 코드는 이전 세션에서 한 번 추가했다가 "테스트 코드 삭제" 커밋(a3054f42)으로 지웠는데, PIE 흐름을 확인하려면 다시 필요해서 재복원했다.

2. UNSPartEquipComponent — ServerRequestPickup RPC 추가

   • H키로 픽업 테스트를 하려는데 TryPickup이 서버 전용 함수라 클라이언트 BP에서 직접 호출이 안 됐다.
   • 클라 → 서버로 넘겨주는 Server RPC ServerRequestPickup(ANSDroppedPart*)를 임시로 추가하고, BP_NS_PlayerCharacter에서 H키 이벤트에 바인딩했다.

3. NSPlayerCharacterBase — if문 {} 누락 핫픽스

   • PossessedBy에서 HasAuthority() 블록에 중괄호가 없어 다음 줄 코드가 항상 실행되는 버그를 발견하고 수정했다. (커밋 4d370a6d)

어떤 어려움이 있었나

1. TryPickup은 서버 전용인데 BP는 클라에서 실행된다

제일 막혔던 부분. ANSDroppedPart::TryPickup은 HasAuthority() 가드가 있어서 클라이언트 컨텍스트에서 호출해도 조용히 무시된다. 처음엔 BP에서 직접 호출하면 되겠지 싶었는데 ListenServer 환경에서 호스트는 되고 클라는 안 돼서 원인 파악에 시간이 걸렸다.

2. DebugDefinition을 지웠는데 테스트가 안 된다

이미 "테스트 코드 삭제"를 커밋해서 없앤 코드인데, 막상 픽업 흐름을 테스트하려니 드랍 파츠에 데이터가 없어서 EquipPart가 early return으로 빠져나갔다. 삭제와 재추가를 두 번 반복한 셈이라 커밋 히스토리가 지저분해졌다.

3. H키 바인딩 위치 오파악

처음에 H키 바인딩이 레벨 BP에 있다고 잘못 안내했다. 실제로는 BP_NS_PlayerCharacter에 있었고, 이 차이로 에디터 작업 안내를 두 번 수정해야 했다.

무엇을 배웠나

서버 전용 함수는 클라이언트 테스트 경로를 따로 뚫어야 한다

HasAuthority() 가드가 붙은 함수는 멀티플레이어 환경에서 클라이언트가 절대 실행할 수 없다. PIE 테스트에서도 마찬가지다. 이 경우 선택지는 두 가지다:

• Server RPC를 임시로 추가한다 (이번에 한 방식)
• 테스트를 에디터 전용 호스트(플레이어 0번)로만 한다

임시 RPC 방식은 나중에 상호작용 시스템으로 교체할 예정이므로, 반드시 // 테스트용 임시 코드 블록으로 표시해두고 삭제 시점을 메모해둬야 나중에 놓치지 않는다.

테스트 코드는 삭제 시점을 미리 정하고 추가해야 한다

"일단 넣고 나중에 지우자"는 항상 두 번 일하게 만든다. 이번에도 한 번 지웠다가 다시 추가했고, 커밋 히스토리에 흔적이 남았다. 앞으로는:

1. 추가할 때 삭제 조건을 주석에 명시 (// 몬스터 드랍 연동 후 삭제)
2. 메모리/작업 큐에 "임시 코드 삭제" 항목을 바로 등록
3. 정식 흐름이 생기는 시점에 묶어서 한 번에 제거

if (HasAuthority()) 단문은 반드시 {}로 감싸야 한다

Unreal 코드베이스에서 HasAuthority() 블록은 한 줄처럼 보여도 나중에 줄이 추가될 가능성이 높다. 단문이어도 {} 없이 쓰면 이번처럼 다음 줄이 무조건 실행되는 버그가 생긴다. 제어문은 항상 {}를 쓰는 스타일을 지킬 것.

NSPartUtils: 중복 ResolveDefinition 공통 유틸 추출

무엇을 했나

NSPartEquipComponent와 NSPartVisualComponent 두 곳에 완전히 동일한 구현으로 존재하던 ResolveDefinition을 NSPartUtils 네임스페이스 자유 함수로 추출했다. (커밋 7afabc66)

• 추출 전: UNSPartEquipComponent::ResolveDefinition(const FNSPartData&) const (멤버 함수) / NSPartVisualComponent에도 동일 구현
• 추출 후: NSPartUtils::ResolvePartDefinition(const UObject* WorldContextObject, const FNSPartData&) — NSPartUtils.h/.cpp 신규 파일

멤버 함수가 아니라 자유 함수로 만든 이유는 UNSDataSubsystem::Get()에 WorldContext가 필요한데, UObject*를 파라미터로 받으면 어느 컴포넌트에서든 호출할 수 있기 때문이다. BlueprintFunctionLibrary는 BP 노출이 필요 없어서 사용하지 않았다.

이 커밋에서 DOREPLIFETIME_CONDITION(..., COND_OwnerOnly) → DOREPLIFETIME으로도 변경됐는데, 파츠 슬롯이 오너 전용으로 복제되면 다른 플레이어 캐릭터에 파츠 비주얼이 표시되지 않는 문제를 해결하기 위해서였다.

어떤 어려움이 있었나

자유 함수 vs 멤버 함수 vs BlueprintFunctionLibrary 선택

처음엔 UNSPartDefinition을 반환하는 함수니까 멤버 함수 형태가 자연스럽게 느껴졌다. 하지만 멤버 함수로 두면 두 컴포넌트 중 어느 쪽에 소속시킬지 결정해야 하고, 한쪽에 의존성이 생기거나 또 중복이 발생한다. BlueprintFunctionLibrary는 BP 노출이 목적인데 이 함수는 서버 로직에서만 쓰이므로 과한 선택이었다.

결론적으로 namespace 자유 함수가 가장 작은 형태였지만, Unreal에서 namespace 함수를 NEOSANCTUM_API로 모듈 외부에 노출하는 패턴이 익숙하지 않아서 헤더 선언 형태를 한 번 고쳐야 했다.

유니티 빌드 이름 충돌 가능성

Unreal은 기본적으로 Unity Build(여러 .cpp를 하나로 묶어 컴파일)를 사용한다. 이 경우 서로 다른 파일에 같은 이름의 namespace나 로컬 심볼이 있으면 충돌이 날 수 있다. NSPartUtils라는 이름 앞에 프로젝트 접두사를 붙인 것도 이 때문이다.

무엇을 배웠나

중복 코드는 "어디에 두느냐"가 핵심이다

중복을 없애는 건 쉬운데, 합친 코드를 어디에 두느냐는 별개의 결정이다. Unreal에서 선택지는 보통 세 가지다:

이번 ResolvePartDefinition은 WorldContext만 있으면 되고 BP 노출도 불필요해서 namespace 자유 함수가 맞았다.

COND_OwnerOnly는 비주얼 데이터에 쓰면 안 된다

DOREPLIFETIME_CONDITION(..., COND_OwnerOnly)은 오너 클라이언트에게만 복제한다. 파츠 장착 정보(EquippedParts)에 이걸 붙이면 내 화면에서는 장착 비주얼이 보이지만, 다른 플레이어 시점에서는 내 캐릭터가 빈 손으로 보인다. 비주얼에 영향을 주는 복제 프로퍼티는 DOREPLIFETIME(모든 클라이언트)을 써야 한다. 보안/트래픽 이유로 오너만 받아야 하는 건 인벤토리 수량, 자원 같은 private 데이터다.

복제문제

• 서버에서 장착한 파츠가 클라에서 안보임 !youtube[5620Nv7IBfc]

• 반대는 가능 !youtube[c6yGiKojjrU]

첫번째 예상

비주얼 컴포넌트로 따로 분리를해서 비주얼 컴포넌트쪽을 의심했지만 OnPartChanged 콜백을 받아서 메시를 불러와서 띄워주는 역할을 하기때문에 파츠 컴포넌트쪽 레플리케이션 조건을 바꿔보았다. 기존에는 COND_OwnerOnly로 소유한 클라에게만 복제되게끔 되어있는데 이를 모든 접속자에게 복제하도록 변경해보았다.

void UNSPartEquipComponent::GetLifetimeReplicatedProps(TArray<class FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
    // 이전 코드
    // DOREPLIFETIME_CONDITION(UNSPartEquipComponent, EquippedParts, COND_OwnerOnly); 
    // 새 코드
    DOREPLIFETIME(UNSPartEquipComponent, EquippedParts);
}

• 결과 !youtube[fo1Bv1otQOM]

바로 정상적으로 복제되었다.

• 이유

1. 호스트가 장착 -> 호스트 PlayerState의 EquipParts가 원격 클라에 복제 안됨(onwer가 아니므로) -> 클라에서 OnRep 안일어남 -> 클라에서 안보임
   2. 클라가 장착 -> 서버는 항상 authority라 데이터를 가지고 있음, EquipPart()가 직접 OnPartChanged.Broadcast 호출 -> 호스트에서 보임

파츠는 모든 플레이어에게 보여야 하므로 증강처럼 owner 전용 복제가 잘못된 조건

증강

복제문제

서버에서는 정상적으로 증강이 출력되는데 클라이언트에서 O키(디버그용키)를 눌렀을때 증강이 제대로 출력되지 않던 문제 데이터 서브시스템에서 데이터가 모두 존재하면 EnterRun()함수를 호출해서 데이터가 로드되었다는 것을 Enum으로 설정하고 이를 IsRunReady라는 함수로 확인할 수가 있다. 증강쪽 코드에는 IsRunReady()를 확인해서 데이터가 있는지 확인하고 증강을 띄워준다. 허나 아직 데이터 서브시스템을 달아놓지 않았기 때문에 둘다 동작을 안하거나 둘다 동작해야 맞는데 계속 서버만 동작하게끔 되어있었다. 그래서 디버깅을 계속하다가 문제를 찾게 되었다. 문제는 플레이어 컨트롤러에서 인런으로 넘겨주는 Server_RequestStartRun함수였다.

if (!HasAuthority())
{
    return;
}

AGameModeBase* CurrentGameMode = GetWorld()->GetAuthGameMode();
if (CurrentGameMode && CurrentGameMode->Implements<UNSOutGameInterface>())
{
    INSOutGameInterface::Execute_RequestStartRun(CurrentGameMode);
}

//서버 인런 데이터 로드
if (UNSDataSubsystem* Data = UNSDataSubsystem::Get(this))
{
    Data->EnterRun();
}

Client_NotifyRunStarted();

이 함수는 서버에서만 동작하고 Client_NotifyRunStarted를 호출한다. 해당 함수에서는

if (UNSDataSubsystem* Data = UNSDataSubsystem::Get(this))
{
    Data->EnterRun();
}

이렇게 데이터서브시스템이 있으면 EnterRun을 해서 임시로 런으로 넘겨주는 부분이 있는데 이때문에 서버에서는 EnterRun으로 넘어가고 클라에서는 Server_RequestStartRun의 !HasAuthority()를 넘기지 못하고 return되고 있었던 것

• 해결

for (FConstPlayerControllerIterator It = GetWorld()->GetPlayerControllerIterator(); It; ++It)
{
    if (ANSPlayerController* PC = Cast<ANSPlayerController>(It->Get()))
    {
        PC->Client_NotifyRunStarted();
    }
}

• GetPlayerControllerIterator()를 통해서 모든 플레이어컨트롤러를 가져와서 Client_NotifyRunStarted()함수를 호출해서 해결하였다.

파츠 드롭 테스트 정리

현재 확인하려는 것

현재 테스트 목표는 다음 두 가지로 볼 수 있다.

• 바닥에 떨어진 파츠와 현재 장착 중인 파츠가 정상적으로 교환되는지.
• 교환 결과로 GE, GA 테스트용 효과가 정상 적용되는지.

즉, 이 작업은 단순히 메시를 바꾸는 테스트가 아니라 데이터 교환 + 시각 교체 + GAS 적용 이 한 흐름으로 이어지는지 검증하는 테스트다.

드롭 액터에 물리를 켤지 고민한 이유

물리를 켜면 바닥에 자연스럽게 떨어지는 연출은 쉬울 수 있지만, 현재 구조에서는 단점이 더 크다.

• 루트가 구체 콜리전이면 반지름만큼 바닥에서 뜨는 문제가 생길 수 있다.
• 멀티플레이에서 물리 시뮬레이션 액터는 단순 복제보다 관리 포인트가 늘어난다.
• 특히 서버 권위 하에서 트랜스폼 복제와 물리 결과 동기화를 신경써야 해서 복잡도가 빠르게 증가한다.

그래서 현재 상황에서는 물리 시뮬레이션을 켜지 않고, 스폰 시 1회 위치 보정으로 해결하는 방식 이 더 적절하다.

왜 메시가 공중에 뜨는가

문제의 핵심은 파츠 메시의 피벗이 지면 기준이 아니라 본 위치 기준 이라는 점이다. 예를 들어 헬멧 메시의 원점은 머리 높이 근처, 각반 메시의 원점은 다리 본 근처에 잡혀 있을 수 있으므로, 드랍 액터 원점을 바닥에 그대로 두면 메시가 그 높이만큼 공중에 떠 보인다.

이건 메시가 잘못된 것이 아니라 모듈러 장착 기준으로 제작된 메시를 드랍 기준으로 재사용 하면서 생기는 자연스러운 현상이다.

해결 방법: 메시 바운드 기반 Z 보정

해결 방법은 드랍 시 물리 대신 메시 바운드의 밑면을 바닥에 맞추는 오프셋을 한 번 적용 하는 것이다.

흐름은 다음과 같다.

1. 드랍할 메시의 로컬 바운드를 구한다.
2. 바운드의 Min.Z 를 이용해 메시 밑면 위치를 계산한다.
3. 스폰 위치의 Z 에 그 값을 반영해 한 번만 보정한다.
4. 이후에는 물리 없이 고정된 드랍 액터로 유지한다.

예시:

const FBoxSphereBounds Bounds = Mesh->CalcBounds(FTransform::Identity);
const float BottomZ = Bounds.GetBox().Min.Z;

FVector SpawnLocation = DropLocation;
SpawnLocation.Z -= BottomZ;

이 방식의 장점은 명확하다.

• 루트 콜리전 모양에 덜 의존한다.
• 멀티플레이 물리 복제 문제를 피할 수 있다.
• 스폰 시 1회 계산으로 끝나므로 유지비가 낮다.
• 드랍 메시와 장착 메시를 같은 에셋으로 재사용하기 좋다.

스폰 관련 개념

ESpawnActorCollisionHandlingMethod

ESpawnActorCollisionHandlingMethod 는 액터를 스폰할 때, 스폰 위치에서 다른 오브젝트와 겹침이 발생하면 어떻게 처리할지 결정하는 열거형이다.

자주 보는 옵션은 다음과 같다.

현재 드랍 액터처럼 “일단 생성은 되어야 하고, 위치는 후처리로 맞출 수 있다”는 상황에서는 AlwaysSpawn 가 단순하고 예측 가능하다.

SpawnActorDeferred

SpawnActorDeferred 는 액터 스폰을 객체 생성 단계 와 최종 초기화 단계 로 나누는 방식이다. 일반 SpawnActor 는 생성 후 초기화가 즉시 진행되지만, SpawnActorDeferred 는 FinishSpawning() 을 호출하기 전까지 중간 초기화 구간을 확보할 수 있다.

즉, 흐름은 아래처럼 이해하면 된다.

1. SpawnActorDeferred 로 액터 객체를 만든다.

2. BeginPlay 전에 필요한 값을 세팅한다.

3. FinishSpawning() 으로 스폰을 완료한다.

예시:

ADroppedPart* DroppedPart = GetWorld()->SpawnActorDeferred<ADroppedPart>(
    DroppedPartClass,
    SpawnTransform,
    Owner,
    Instigator,
    ESpawnActorCollisionHandlingMethod::AlwaysSpawn
);

DroppedPart->InitializeFromInstance(StoredInstance);
DroppedPart->SetDesiredDropMesh(DropMesh);

UGameplayStatics::FinishSpawningActor(DroppedPart, SpawnTransform);

현재 케이스에서 이 방식이 중요한 이유는 DroppedPart 가 시작 시점에 StoredInstance 를 이미 가지고 있어야 하기 때문이다. 일반 SpawnActor 로 만들면 BeginPlay 또는 초기화 로직이 먼저 돌고, 그 뒤에 값을 세팅하는 순서 문제가 생길 수 있다.

파츠 비주얼 구조 정리

역할 분리

장착 데이터와 시각 표시를 분리한 현재 설계는 방향이 좋다.

핵심은 EquipComponent 가 파츠 하나당 붙는 구조가 아니라, 플레이어 하나당 1개 존재하면서 전 슬롯을 관리한다 는 점이다. 따라서 VisualComponent 는 EquipComponent 의 상태를 구독해서 렌더링만 담당하면 된다.

BindToEquipComponent 흐름

BindToEquipComponent(EquipComp, GetMesh())
 ├── GetMesh() = 캐릭터 본체 스켈레탈 메시(리더)
 ├── EnsureSlotComponents() = 슬롯별 메시 컴포넌트 최초 1회 생성
 └── OnPartChanged 델리게이트 구독

이 구조의 장점은 초기화와 갱신 책임이 깔끔히 분리된다는 점이다. 슬롯용 메시 컴포넌트는 한 번 만들어 두고, 실제 파츠 변경은 이벤트 기반으로 처리하면 된다.

EnsureSlotComponents

EnsureSlotComponents 는 슬롯별 비주얼 컴포넌트가 존재하는지 보장하는 초기화 함수 로 이해하면 된다. 보통 BindToEquipComponent 안에서 한 번만 호출되며, 하는 일은 크게 두 가지다.

• BindToEquipComponent 가 중복되지 않게 준비한다.
• 슬롯별 USkeletalMeshComponent 를 생성하고 등록한다.

즉, 이 함수의 책임은 그릇 생성 이다. 아직 어떤 파츠를 보여줄지는 모르더라도, Body/Arm/Leg 슬롯이 사용할 메시 컴포넌트를 준비해 두는 단계다.

UpdateSlotVisual

UpdateSlotVisual 은 실제 파츠 변경이 발생했을 때 해당 슬롯의 메시를 바꾸는 함수 다. 즉, EnsureSlotComponents 가 그릇을 만드는 단계라면, UpdateSlotVisual 은 그 그릇에 어떤 스켈레탈 메시를 담을지 결정하는 단계다.

파츠가 바뀔 때마다 새 컴포넌트를 생성할 필요는 없다. 이미 만들어 둔 슬롯 컴포넌트에 SetSkeletalMesh() 로 에셋만 교체하면 된다.

SetLeaderPoseComponent 와 부착 원리

파츠가 제자리에 붙는 이유

SetLeaderPoseComponent() 가 파츠 메시의 위치를 직접 계산해 주는 것은 아니다. 위치가 맞는 이유는 파츠 메시 자체가 캐릭터 전신 스켈레톤 기준 위치에 맞춰 모델링되어 있기 때문 이고, SetLeaderPoseComponent() 는 그 본 변형을 따라가게 해 주는 역할을 한다.

역할을 나누면 아래처럼 정리할 수 있다.

즉, 올바르게 모델링된 모듈러 메시 + 같은 스켈레톤 + Leader Pose 조합이 자연스러운 장착 비주얼을 만든다.

EnsureSlotComponents 코드 의미

MeshComp->SetupAttachment(LeaderMeshComp);

리더 메시를 부모로 붙여서 위치/회전/스케일을 함께 따라가게 만든다.

MeshComp->SetCollisionEnabled(ECollisionEnabled::NoCollision);

파츠 시각 메시 자체는 충돌이 필요 없으므로 꺼 두는 편이 합리적이다. 실제 캐릭터 충돌은 보통 캡슐 컴포넌트가 담당한다.

MeshComp->RegisterComponent();

NewObject 로 만든 컴포넌트는 등록 전까지 월드에서 정상적으로 렌더링·틱되지 않으므로, 수동 등록이 필요하다.

MeshComp->SetLeaderPoseComponent(LeaderMeshComp);

리더 메시의 본 포즈를 따라가게 하여, 별도 애니메이션 인스턴스 없이도 파츠가 동일한 애니메이션을 공유하게 만든다.

파츠 시각 장착 설계

설계 방향

현재 설계는 데이터 관리와 시각 표현을 분리하면서, 드랍용 메시를 장착용 메시로도 재사용하는 구조 다. 이 방향은 구현량과 유지보수 비용 사이 균형이 좋다.

구조

ANSPlayerCharacterBase
 └── UNSPartVisualComponent
     ├── BodyPartMeshComp : USkeletalMeshComponent
     ├── ArmPartMeshComp  : USkeletalMeshComponent
     └── LegPartMeshComp  : USkeletalMeshComponent

각 슬롯 메시 컴포넌트는 메인 캐릭터 메시를 리더로 사용한다.

신호 흐름

UNSPartEquipComponent::OnPartChanged(Slot, PartData)
 → UNSPartVisualComponent 가 구독
 → DefinitionPtr 로 Def 조회
   → 이미 로드됨: 즉시 SetSkeletalMesh()
   → 미로드: RequestAsyncLoad 후 콜백에서 적용
 → 비어 있는 슬롯: SetSkeletalMesh(nullptr)

이 흐름의 핵심은 EquipComponent 는 상태를 발행하고, VisualComponent 는 그 상태를 구독해서 렌더링만 한다 는 점이다.

구독 시점

VisualComponent 는 캐릭터에 붙어 있지만 EquipComponent 는 PlayerState 에 있으므로, BeginPlay 에서 무조건 바로 접근한다고 가정하면 위험할 수 있다. 따라서 PossessedBy() 와 OnRep_PlayerState() 시점 모두에서 바인딩을 보장하는 방식 이 타당하다.

이 판단은 특히 멀티플레이에서 중요하다. 서버와 클라이언트는 PlayerState 획득 타이밍이 다를 수 있기 때문이다.

구현 계획

1단계 - UNSPartVisualComponent 신설

파일 위치:

• Source/NeoSanctum/Character/Component/NSPartVisualComponent.h
• Source/NeoSanctum/Character/Component/NSPartVisualComponent.cpp

구성:

• 슬롯별 USkeletalMeshComponent 3개 보유
• BindToEquipComponent(UNSPartEquipComponent*, USkeletalMeshComponent* LeaderMesh)
• EnsureSlotComponents()
• UpdateSlotVisual(ENSPartSlot, const FNSPartData&)
• ClearVisual(ENSPartSlot)

2단계 - ANSPlayerCharacterBase 연결

• UPROPERTY(VisibleAnywhere) 로 PartVisualComp 추가
• PossessedBy() 에서 서버 측 바인딩
• OnRep_PlayerState() 에서 클라이언트 측 바인딩

검증 목표

1. 키 입력 → EquipPart → 캐릭터에 파츠 메시 부착
2. 같은 슬롯 드랍 픽업 → 기존 메시 제거 + 새 메시 부착
3. ClearAll 호출 → 모든 슬롯 메시 제거
4. GE 적용 여부 → showdebug abilitysystem 으로 확인

비동기 로드 메모

DropMesh 가 번들 태그 없이 관리된다면, 파츠 비주얼 적용 시점에 온디맨드 비동기 로드를 거는 것이 안전하다. 현재 구조에서는 슬롯별 로드 핸들을 관리하고, ClearVisual() 시 취소하거나 무효화하는 흐름이 적합하다.

특히 장착 시스템에서는 동기 로드(LoadSynchronous) 를 피하는 것 이 중요하다. 전투 중 장착 변경이나 드랍 픽업 시 프레임 스톨을 만들 수 있기 때문이다.

서버 구조 정리

데디서버와 리슨서버 차이

언리얼의 Dedicated Server 는 클라이언트와 분리된 별도 서버 프로세스로 동작하며, 시각 표시나 UI 없이 게임 상태 동기화와 규칙 처리만 담당한다. 반면 Listen Server 는 한 플레이어의 게임 클라이언트가 서버 역할까지 함께 수행하는 구조라서, 호스트는 직접 플레이하면서 동시에 서버 권한도 가진다.

NetMode 와 NetRole

NetMode

NetMode 는 현재 월드 인스턴스가 어떤 네트워크 실행 모드인지 나타내는 값이다. 즉, “이 프로그램 인스턴스가 서버인지, 클라이언트인지, 혼자인지”를 구분하는 월드 단위 개념이다.

정리하면 NetMode 는 월드 전체의 입장 이다. 같은 코드라도 어느 머신에서 실행하느냐에 따라 NM_Client, NM_ListenServer, NM_DedicatedServer 로 달라진다.

NetRole

NetRole 은 개별 Actor 가 현재 머신에서 어떤 네트워크 역할을 갖는지 나타낸다. UE5 에서는 예전 Role 직접 접근보다 GetLocalRole() / GetRemoteRole() 형태로 확인하는 방식이 권장된다.

핵심은 NetMode 는 월드 기준, NetRole 은 Actor 기준 이라는 점이다. 예를 들어 클라이언트 머신의 NetMode 는 항상 NM_Client 여도, 그 안의 Actor 들은 AutonomousProxy 나 SimulatedProxy 처럼 서로 다른 Role 을 가질 수 있다.

실무에서 어떻게 구분할까

• “이 코드가 서버에서만 돌아야 하나?” → HasAuthority() 또는 NetMode 를 본다.
• “이 Actor 가 내가 조작하는 대상인가?” → GetLocalRole() 과 소유 관계를 본다.
• 초기화 시점이 아주 이른 경우에는 NetRole 보다 NetMode 확인이 더 안전한 경우가 있다.

오늘의 핵심 정리

• Dedicated Server 는 서버 전용 프로세스, Listen Server 는 플레이어가 서버까지 겸하는 구조다.
• NetMode 는 월드 단위 실행 모드, NetRole 은 Actor 단위 네트워크 역할이다.
• 현재 드랍 파츠 문제는 물리보다 메시 바운드 기반 Z 보정 이 더 단순하고 멀티플레이 친화적이다.
• SpawnActorDeferred 는 StoredInstance 같은 필수 데이터를 BeginPlay 전 주입해야 할 때 적합하다.
• 파츠 시각 장착은 EquipComponent(PlayerState) 와 VisualComponent(Character) 분리 구조가 맞고, 슬롯 메시 컴포넌트는 최초 1회 생성 후 에셋만 교체하면 된다.

Date: 2026-06-09 Tags: UnrealEngine5 GAS Replication PartEquip TIL

배운 것 요약

드랍된 파츠를 줍고, 슬롯에 장착하고, 기존 파츠를 바닥에 다시 스폰하는 흐름을 테스트하면서 마주친 이슈와 해결 방법을 정리한다.

테스트 구성 개요

임시 테스트 코드 사용 (삭제 예정)

몬스터 드랍 연동 완료 후 위 세 가지 모두 제거할 것.

테스트 절차

사전 준비

DA_TestArmPart 생성 (없는 경우)

1. Content Browser 우클릭 → Miscellaneous > Data Asset
2. 클래스: NSPartDefinition → 이름: DA_TestArmPart
3. 내부 설정:
   • Part Slot: Arm
   • Part Name: Test Arm
   • Drop Mesh: 아무 스켈레탈 메시
   • Value Range: Common → Min 10, Max 20

BP_DroppedPart 세팅

뷰포트에서 드랍 액터 선택 → Details 패널 → Debug > Debug Part Data:

• Definition Ptr: DA_TestArmPart
• Current Rarity: Common
• Current Value: 15.0

두 번째 드랍 액터는 첫 번째를 Ctrl+D로 복제 후 위치만 이동.

레벨 블루프린트 G키 구성

기존 G키 노드 전부 삭제 후 아래 순서로 재구성:

1. 빈 곳 우클릭 → G → Keyboard Events > G
2. Pressed 핀 → Get Player Controller (Index 0)
3. → Get Player State
4. → Get Component by Class (Component Class: NSPartEquipComponent)
5. → Server Request Pickup Nearest
6. G Pressed 실행 핀 → Server Request Pickup Nearest 실행 핀 연결

테스트 케이스

TC-A: 첫 장착 확인

목표: G키로 드랍 파츠를 처음 주웠을 때 슬롯에 장착되는지 확인

절차:

1. PIE 실행
2. 첫 번째 드랍 액터 반지름 300 이내로 이동
3. G키 입력

기대 로그:

[PartEquip] 장착 완료 — Slot: 1 | Rarity: 0 | Value: 15.0 | Def: DA_TestArmPart
[PartEquip] GE 없음 — Slot: 1 (EffectClass 미지정)

GE 없음은 정상이다. DA에 EffectClass를 지정하지 않았기 때문이며, GE 테스트는 EffectClass 지정 후 별도로 진행한다.

TC-B: 교체 + 기존 파츠 드랍 확인

목표: 이미 파츠가 장착된 상태에서 다른 드랍 액터를 주우면 기존 파츠가 바닥에 스폰되는지 확인

절차:

1. TC-A 완료 상태 유지
2. 두 번째 드랍 액터 근처로 이동
3. G키 입력

기대 로그:

[PartEquip] 기존 파츠 드랍 — Slot: 1 | Rarity: 0 | Value: 15.0
[PartEquip] 장착 완료 — Slot: 1 | Rarity: 0 | Value: 15.0 | Def: DA_TestArmPart

기대 시각:

• 플레이어 발 근처에 드랍 액터 새로 스폰됨
• 두 번째 드랍 액터 사라짐

로그 해석표

트러블슈팅

[이슈 1] Make NSPartData 핀이 비어 있음

증상

BP에서 Make NSPartData 노드를 꺼냈는데 설정 가능한 핀이 하나도 없음.

원인

FNSPartData의 멤버 변수들이 전부 BlueprintReadOnly로 선언되어 있어서, Make 노드가 쓰기 가능한 핀을 노출하지 않은 것.

Unreal의 Make 노드는 내부적으로 구조체의 각 멤버에 접근해 값을 채우는데, ReadOnly면 외부에서 쓰기가 불가능하므로 핀 자체가 생성되지 않는다.

해결

NSPartTypes.h의 FNSPartData 멤버를 BlueprintReadWrite로 변경 → 에디터 완전 종료 → VS에서 빌드 → 재시작 → 기존 Make NSPartData 노드 삭제 후 새로 추가

[이슈 2] G키(TryPickup) 후 F키(Initialize) 누르면 pending kill 에러

증상

Attempted to access BP_NSDroppedPart_C_1 via property ...
but BP_NSDroppedPart_C_1 is not valid (pending kill or garbage)

원인

두 가지 문제가 중첩되었다.

1. G키(TryPickup)가 액터를 Destroy하고 나면 레벨 블루프린트가 들고 있던 레퍼런스는 이미 무효(pending kill) 상태가 된다. 이 상태에서 F키(Initialize)가 그 레퍼런스에 접근하면 에러가 발생한다.

2. Initialize 없이 G를 누르면 StoredInstance.DefinitionPtr이 비어 있어 EquipPart 실패 — Definition 로드 불가 로그가 남는다.

해결

반드시 F(Initialize) → G(TryPickup) 순서로 실행해야 했으나, DebugPartData 자동 Initialize 도입으로 F키 자체가 불필요해졌다. 현재는 G키만으로 전체 흐름이 동작하므로 F키 바인딩은 삭제한다.

정리

• BlueprintReadOnly vs BlueprintReadWrite는 Make 노드 핀 노출 여부에 직접 영향을 준다.
• 레벨 블루프린트에서 액터 레퍼런스를 들고 있을 때, 해당 액터가 Destroy되면 레퍼런스는 즉시 무효가 되므로 접근 전 유효성 체크가 필요하다.
• 테스트용 임시 코드(DebugPartData, G키 바인딩)는 몬스터 드랍 연동 시 반드시 제거할 것.

에러 모음

TMap과 리플리케이션

UPROPERTY(ReplicatedUsing=OnRep_EquippedParts)
TMap<ENSPartSlot, FNSPartData> EquippedParts;

기존의 하나의 파츠만 보유하던 구조에서 여러 파츠를 소유할 수 있는 구조로 확장하는 중 TMap으로 장착된 파츠들을 저장하려고 했는데 아래 에러가 발생했다.

NSPartEquipComponent.h(74): Error : Replicated maps are not supported.

UE의 프로퍼티 리플리케이션은 TMap을 지원하지 않는다. (포인터, Map, TSet 모두 델타 직렬화 불가)

해결: TMap에서 슬롯을 구조체 필드로 옮기고, TArray로 전환해 배열이 복제되도록 변경.

USTRUCT()
struct FNSPartData {
    ENSPartSlot Slot;  // 배열 내 슬롯 식별자로 사용
    ...
};

UPROPERTY(ReplicatedUsing=OnRep_EquippedParts)
TArray<FNSPartData> EquippedParts;

IsNull / IsValid / IsPending / .Get() 구분 (TSoftObjectPtr 기준)

핵심: 경로가 있는지 체크할 때는 IsNull(), 메모리에 올라와 있는지 체크할 때는 IsValid(). IsValid()를 guard clause에 쓰면 경로는 있지만 아직 로드 안 된 경우에도 nullptr을 반환하는 버그가 생긴다.

실수 예시:

// 잘못된 코드 — Definition이 로드돼 있으면 nullptr 반환해버림
if (Part.DefinitionPtr.IsValid())
    return nullptr;

// 올바른 코드 — 경로 자체가 없을 때만 bail
if (Part.DefinitionPtr.IsNull())
    return nullptr;

.Get()은 캐시가 없으면 로드 못 한다

.Get()은 로드를 절대 유발하지 않는다. 지금 메모리에 올라와 있으면 포인터, 아니면 그냥 nullptr. 동기 로드는 .LoadSynchronous(), 비동기 로드는 RequestAsyncLoad가 별도로 존재한다.

NSDataSubsystem이 번들 단위로 PrimaryAsset을 미리 로드해두기 때문에 .Get()이 정상 반환되는 것 — 번들 로드 전이라면 .Get()은 nullptr을 반환하고 조용히 실패한다.

FGameplayAbilitySpec 인자

FGameplayAbilitySpec Spec(Loaded, 1, INDEX_NONE, this);

SourceObject에 this를 넘기면 나중에 "어느 파츠가 준 GA인지" 추적 및 조건 판정에 사용할 수 있다. ASC->GiveAbility(Spec)의 반환 핸들(FGameplayAbilitySpecHandle)을 컴포넌트가 직접 보관해 파츠 제거 시 ClearAbility(Handle)로 정확히 그 GA만 회수하는 GAS 정석 패턴.

const 오버로드 — 왜 같은 함수가 두 개인가

FNSPartData*       FindPart(ENSPartSlot Slot);        // 수정 가능 포인터
const FNSPartData* FindPart(ENSPartSlot Slot) const;  // 읽기 전용 포인터

C++은 호출하는 객체가 const인지 아닌지로 어느 쪽을 쓸지 자동 선택한다. const 멤버 함수 안에서는 non-const 버전을 호출할 수 없으므로 (const 위반) 외부에서 const UNSPartEquipComponent&로 참조할 경우를 위해 두 버전 모두 필요하다.

설계 개념

PlayerState vs Pawn — 데이터 생존 전략

UE 멀티플레이에서 Pawn은 사망 시 파괴되지만 PlayerState는 인런 내내 살아있다. 파츠/증강처럼 사망 후에도 유지되어야 하는 데이터는 PlayerState(또는 PlayerState에 붙은 컴포넌트)에 두는 것이 정석.

ASC도 PlayerState에 두면 GE/GA가 사망 후에도 유지되고, 부활 시 InitAbilityActorInfo(PS, newPawn)으로 Avatar만 교체하면 기존 효과가 새 Pawn에 자동 적용된다.

서버 권한 액터에 Client RPC를 직접 못 다는 이유

World에 스폰된 액터(예: 드랍 파츠)는 owning connection이 없다. 클라이언트가 이 액터에 직접 Server RPC를 보내려 해도 라우팅이 안 된다. 해결: 플레이어 측(Pawn/PlayerController)에서 Server RPC를 받아, 서버에서 trace 등으로 대상 액터를 찾아 해당 로직을 직접 호출하는 패턴을 사용.

// 드랍 액터에 ServerRPC X
// 플레이어 컨트롤러에서:
void AMyPlayerController::ServerPickup_Implementation(ANSDroppedPart* Target) {
    Target->TryPickup(GetPawn());
}

알고리즘

오픈채팅방

• 문제: https://school.programmers.co.kr/learn/courses/30/lessons/42888?language=cpp
• 내 풀이: https://github.com/JongKyuHong/NBC_TIL/blob/main/%EC%BD%94%EB%93%9C%EC%B9%B4%ED%83%80/28%EC%A3%BC%EC%B0%A8/%EB%AA%A9/%EC%98%A4%ED%94%88%EC%B1%84%ED%8C%85%EB%B0%A9.cpp

id별 최종 닉네임 매핑을 만들어두고, 메시지 순서를 따로 저장한 뒤 마지막에 합치는 방식.

unordered_map<string, string> matchMap;
vector<pair<string, string>> message;

for (const string& rec : record) {
    string command, uid, nickname;
    // flag로 직접 파싱하는 방식 → 어색하고 비효율적
}

개선: stringstream으로 공백 기준 자동 분리.

for (const string& rec : record) {
    stringstream ss(rec);
    string command, uid, nickname;
    ss >> command >> uid >> nickname;

    if (command == "Enter" || command == "Leave")
        message.push_back({uid, command});
    if (command != "Leave")
        matchMap[uid] = nickname;
}

stringstream은 공백/개행 기준으로 토큰을 자동 분리해준다. 직접 flag를 관리하는 파싱보다 짧고 의도가 명확하다.

오늘은 인런 중에 증강 카드를 제시하고, 플레이어가 하나를 골라 캐릭터에 실제 효과를 적용하는 흐름을 전체적으로 붙였다. 처음에는 단순히 "카드 3장 띄우고 하나 선택" 정도로 생각했는데, 막상 구현하다 보니 데이터 정의, 추첨 로직, 적용 방식, 입력 처리, UI 반영까지 전부 이어져 있어야 자연스럽게 동작했다. 그래서 이번 작업은 기능 하나를 추가했다기보다는, 증강 시스템의 기본 뼈대를 세운 작업에 가까웠다.

이번에 구현한 흐름

전체 흐름은 다음처럼 이어진다.

1. 서버나 디버그 입력을 통해 증강 오퍼를 큐에 넣는다.
2. 증강 선택 컴포넌트가 풀과 희귀도 가중치를 바탕으로 오퍼를 구성한다.
3. UI에서 카드 3장을 보여주고, 플레이어는 입력으로 선택하거나 리롤할 수 있다.
4. 선택된 증강은 인벤토리 컴포넌트로 넘어가고, 종류에 따라 GE 또는 GA 형태로 적용된다.
5. HUD와 증강 패널은 현재 보유 중인 증강 상태를 계속 보여준다.

예전에는 증강 관련 입력을 별도 IMC로 스위칭하는 방식이었는데, 이번에는 그 구조를 걷어내고 gameplay 입력 위에 자연스럽게 얹히는 비차단 오버레이 방식으로 바꿨다. 덕분에 "증강 UI를 열었기 때문에 입력 체계를 갈아끼운다"는 느낌보다, 게임 진행 중 필요한 순간에 UI가 올라오는 구조에 더 가까워졌다.

데이터 쪽에서 정리한 내용

이번 작업에서 먼저 잡은 것은 증강을 어떤 형태로 정의하고 뽑을지에 대한 데이터 구조였다. 단순히 카드 이름만 두는 수준이 아니라, 증강의 실제 적용 방식과 추첨 풀의 역할을 분리해서 설계했다.

• NSAugmentTypes: 증강 시스템 전반에서 공통으로 사용하는 타입/분류 성격의 기반
• NSAugmentDefinition: 개별 증강 하나를 설명하는 정의 데이터, 실제 카드 단위
• NSAugmentPoolDefinition: 어떤 증강들이 어떤 규칙으로 추첨될지 관리하는 풀 데이터

NSAugmentPoolDefinition에서는 풀 태그로 이 풀이 일반 풀인지, 고등급 풀인지 구분할 수 있도록 했다. 또 Rarity Weights로 희귀도별 등장 확률을 조정할 수 있게 해서, 같은 시스템 안에서도 상황에 따라 다른 체감이 나오도록 만들었다. Entries에는 실제 증강 Definition들을 넣고, Legendary Stat Entries에는 레전더리 기믹 변경 제한 이후에 등장할 수 있는 스택형 레전더리 수치 증강을 따로 넣는 구조로 정리했다.

이렇게 분리해 두니까 나중에 "어떤 상황에서 어떤 증강을 보여줄지"를 코드에서 하드코딩하지 않고 데이터로 제어하기 쉬워졌다. 특히 라이브 밸런싱이나 기획 변경이 들어왔을 때 대응하기 훨씬 편해질 것 같다.

적용 방식

증강을 실제로 보유하고 효과를 적용하는 책임은 PlayerState에 붙인 증강 인벤토리 컴포넌트가 맡도록 했다. 이 컴포넌트는 "플레이어가 지금 어떤 증강을 가지고 있는지"를 관리하면서, 선택된 증강을 실제 Ability System 쪽 효과로 변환해 붙여주는 역할을 한다.

적용 방식은 증강 종류에 따라 나뉜다.

• 수치 강화형 증강은 StackEffectClass를 사용해서 GE를 적용한다.
• 이때 스택 값은 SetByCaller로 넘겨서 같은 계열의 누적 강화가 가능하게 했다.
• 레전더리 기믹형 증강은 GrantedAbilityClass를 사용해서 GA를 부여한다.
• 인런이 끝나면 ClearAll로 한 번에 정리되도록 했다.

즉, "능력 자체가 추가되는 증강"과 "기존 능력치를 누적해서 강화하는 증강"을 적용 레벨에서 분리한 셈이다. 이 구분을 해두니 레전더리처럼 구조가 큰 증강과 일반 수치형 증강을 같은 시스템 안에서 무리 없이 다룰 수 있었다.

오퍼 생성과 리롤

증강 선택 컴포넌트는 플레이어에게 지금 어떤 카드 3장을 보여줄지 결정하는 쪽에 집중했다. 단순 랜덤이 아니라 희귀도 가중치, 풀 구성, 현재 쌓여 있는 대기 오퍼 수까지 고려해서 오퍼를 적재하는 구조다.

핵심은 PoolQueue와 PendingCount를 기반으로 오퍼를 관리하는 점이다. 그래서 한 번에 다 띄우는 방식이 아니라, 이벤트가 여러 번 발생하면 오퍼가 순서대로 쌓였다가 플레이어가 하나씩 처리할 수 있다. 리롤도 같은 흐름 안에 넣어서, 현재 제시된 카드 구성을 다시 뽑도록 연결했다.

이번 구현으로 플레이어 입장에서는 "증강 기회가 들어오면 대기열에 쌓이고, 필요할 때 확인하고, 마음에 안 들면 다시 뽑을 수 있는" 흐름이 만들어졌다. 단순한 팝업보다 실제 게임 시스템처럼 느껴지게 된 부분이다.

입력 처리 방식 변경

입력 쪽도 이번에 꽤 크게 바뀌었다. 기존에는 증강 UI 전용 IMC로 전환하는 식이었는데, 이 방식은 순간적으로 맥락이 끊기거나 입력 체계가 갈라지는 느낌이 있었다. 그래서 이번에는 기존 증강 IMC 스위칭을 없애고, Gameplay IMC에 증강 관련 입력을 직접 연결했다.

연결한 입력은 다음과 같다.

• 증강 카드 선택: 1 / 2 / 3
• 리롤: T
• 패널 토글: Tab
• 디버그 오퍼 생성: O

이 구조의 장점은 입력 흐름이 더 단순해졌다는 점이다. UI가 떠 있어도 "지금 입력 컨텍스트가 바뀌었는지"를 따로 추적할 필요가 줄었고, 필요한 경우 UI 열림 여부만 보고 게이팅하면 된다. 특히 IsAugmentationPanelOpen() 같은 함수가 추가되면서 InputBinder 쪽 제어도 더 명확해졌다.

UI에서 바뀐 점

이번 작업은 로직만 붙인 것이 아니라, 플레이어가 증강 시스템을 실제로 체감할 수 있도록 UI도 함께 정리했다. 증강 카드 위젯, Augmentation 패널, HUD의 보유 증강 아이콘 표시까지 전체적으로 이어 붙였다.

눈에 띄는 변화는 두 가지였다.

• 오퍼가 들어오면 카드 영역만 따로 보여줄 수 있게 했다.
• 패널 전체와 카드 섹션을 분리해서, 항상 같은 방식으로 화면을 덮지 않도록 했다.

이 덕분에 "증강 선택 UI"와 "보유 증강을 확인하는 패널"의 역할이 조금 더 명확해졌다. 카드는 이벤트성 UI에 가깝고, 패널은 현재 상태를 확인하는 UI에 가깝게 분리된 셈이다.

보유 증강 아이콘도 표시 방식이 조금 달라졌다. NSAugmentationWidget.cpp의 OnOwnedIconsLoaded()에서는 아이콘을 WrapBox에 바로 넣지 않고 USizeBox로 한 번 감싸서 추가하도록 했다. 그래서 원본 텍스처 해상도와 관계없이 항상 일정한 크기로 보이도록 강제할 수 있고, 기본값은 OwnedIconSize 48x48이며 BP별로 EditDefaultsOnly에서 조정 가능하다.

개인적으로는 이 부분이 꽤 중요했다. 아이콘 에셋마다 원본 크기가 다르면 HUD가 쉽게 지저분해지는데, 표시 크기를 강제로 고정해 두면 데이터가 조금 들쭉날쭉해도 화면 품질은 안정적으로 유지되기 때문이다.

아직 연결하지 않은 부분

현재 증강 시스템의 내부 뼈대와 UI 흐름은 붙어 있지만, 실제 게임 이벤트와의 연결은 아직 후속 작업으로 남아 있다. 즉, "증강 시스템 자체는 동작하지만, 언제 이 오퍼를 띄울지"에 대한 실전 트리거는 아직 다 연결된 상태는 아니다.

아직 미연결인 부분은 다음과 같다.

• 레벨업, 엘리트 처치, 보스 처치 시 서버에서 EnqueueOffer 호출
• 보물상자 상호작용 시 Server_EnqueueOffer 호출

지금은 인런 환경에서만 O 키 디버그 함수 Debug_EnqueueAugmentOffer로 오퍼를 띄워 테스트하고 있다. 대신 이 디버그 루트 덕분에 GE 적용, GA 부여, 큐 적재, 리롤, UI 반영까지 핵심 흐름 자체는 먼저 검증할 수 있었다.

에셋 연결 시 주의한 점

이번 시스템은 코드만 넣는다고 완전히 동작하는 구조는 아니다. 증강 Definition 데이터 에셋에서 실제로 어떤 GE와 GA를 연결할지 에디터에서 지정해 줘야 최종 동작이 완성된다.

정리하면 다음 기준으로 연결하면 된다.

• 기믹형 증강: GrantedAbilityClass만 사용
• 수치 강화형 증강(C/R/E 및 Legendary 수치형): StackEffectClass만 사용

즉, 데이터 에셋 설계와 에디터 세팅이 런타임 로직만큼 중요하다. 이 부분이 빠지면 코드상으로는 선택이 끝나도 실제 효과가 안 붙기 때문에, 테스트할 때 가장 먼저 확인해야 할 포인트 중 하나다.

UI 함수 변경 사항을 조금 더 자연스럽게 정리하면

이번에는 UI 함수 이름도 전반적으로 손봤다. 기존 이름은 단순히 Show/Hide 중심이라 "정말 패널을 여는 것인지", "카드 섹션만 다루는 것인지", "리롤 요청을 어디로 전달하는 것인지"가 덜 드러나는 편이었다. 그래서 함수 이름을 역할 중심으로 정리했다.

NSUIManagerSubsystem

NSHUDWidget

NSAugmentationWidget

NSAugmentCardWidget

이렇게 이름을 바꿔 두니 함수만 봐도 역할이 더 잘 읽힌다. 특히 UI 코드는 나중에 다시 봤을 때 "이 함수가 화면 전체를 여는 건지, 일부 섹션만 다루는 건지"가 안 보이면 유지보수가 힘든데, 이번 정리는 그런 혼란을 줄이는 데 의미가 있었다.

테스트하면서 확인한 것

현재 테스트 기준으로는 다음 항목들을 확인했다.

• 인런에서 O 키를 누르면 증강 선택 UI를 띄울 수 있다.
• O를 여러 번 누르면 오퍼가 큐에 순서대로 적재된다.
• 왼쪽 위 UI에서 적재 수를 확인할 수 있다.
• Tab으로 증강 창을 토글하고, 보유 중인 증강 아이콘을 확인할 수 있다.
• 같은 종류의 증강은 중복 추가되지 않는다.
• T 키로 리롤이 가능하다.
• GE 적용과 GA 부여가 정상 동작하는 것까지 확인했다.

아직 실전 트리거는 덜 붙었지만, "오퍼 생성 → 선택 → 적용 → UI 반영"이라는 핵심 루프는 이제 테스트 가능한 상태까지 올라왔다. 그래서 다음 작업은 시스템을 새로 만드는 단계보다는, 실제 게임 이벤트와 자연스럽게 연결하는 단계가 될 것 같다.

작업하면서 느낀 점

이번 작업은 카드 UI 하나 만든 느낌보다, 인런 보상 시스템의 기반을 깔아 둔 작업에 더 가까웠다. 데이터 정의, 추첨 로직, 적용 책임, 입력, UI가 다 따로 놀지 않고 한 흐름으로 이어지게 만드는 게 핵심이었다.

특히 좋았던 점은 적용 방식을 GE와 GA로 분리한 부분, 그리고 입력을 별도 IMC 전환이 아니라 오버레이 방식으로 정리한 부분이다. 이 두 군데를 먼저 정리해 둔 덕분에 이후 레벨업 보상이나 보스 보상 같은 실제 게임 이벤트를 붙일 때도 구조가 크게 흔들리지 않을 것 같다.

나중에 실제로 적용할때는 실제 인런 이벤트와 EnqueueOffer 연결, 서버 권한 흐름 점검, 그리고 카드 선택/리롤의 최종 RPC 연결까지 마무리하면 증강 시스템이 훨씬 완성도 있게 자리잡을 것 같다.

퀴즈

• Overlap과 Block충돌 이벤트의 차이점 : Overlap은 두 오브젝트가 서로 겹쳐도 물리적으로 통과하며, Block은 두 오브젝트가 막혀서 서로 통과할 수 없다.
• 다형성은 런타임에 동적으로 메서드 호출이 결정되는 특징이 있다.

알고리즘

[3차] 파일명정렬

• 문제 https://school.programmers.co.kr/learn/courses/30/lessons/17686?language=cpp
• 내 풀이 https://github.com/JongKyuHong/NBC_TIL/blob/main/%EC%BD%94%EB%93%9C%EC%B9%B4%ED%83%80/28%EC%A3%BC%EC%B0%A8/%ED%99%94/%5B3%EC%B0%A8%5D%ED%8C%8C%EC%9D%BC%EB%AA%85%EC%A0%95%EB%A0%AC.cpp

stable_sort라는 안정 정렬이 필요했다. 그냥 sort는 불완전 정렬이라서 순서 보장이 안될수가 있다. 그래서 순서가 보장되어야 하는 지금같은 문제에서는 stable_sort를 쓰자, 그리고 sort함수안에서 모든 조건을 다 if문으로 분기할 수 있는게 아니면 끝에 return false를 반드시 붙여주자