완성도와 결과만 놓고 보면 아쉬운 점도 분명 존재하지만, 그럼에도 불구하고 개인적으로는 최선을 다해 임했다고 말할 수 있는 프로젝트였습니다.

내가 맡았던 역할과 초기 방향성

프로젝트 초반, Project Arc는 PvPvE 기반의 게임을 목표로 기획되었고, 저는 다음과 같은 역할을 중심으로 참여할 예정이었습니다.

• 절차적 맵 생성 시스템
• 반복 플레이를 고려한 시스템 단위 설계
• 전투 외 콘텐츠 확장을 위한 기반 기능 구현

특히 절차적 맵 생성은 프로젝트의 핵심 차별점 중 하나로 논의되었고, 저 역시 해당 기능을 중심으로 기술적 기여를 준비하고 있었습니다.

기획 변경과 역할 축소

그러나 프로젝트 중반, 게임의 방향성이 PvPvE → 내러티브 중심 PvE로 크게 변경되면서 상황이 달라졌습니다.

이 변화로 인해:

• 절차적 맵 생성은 더 이상 프로젝트 방향성과 맞지 않게 되었고
• 시스템 중심의 확장 기능보다는 고정된 레벨과 연출, 스토리 전달이 우선시되었습니다

그 결과, 제가 초기에 준비하고 있던 역할과 기여 범위가 축소되어 많은 아쉬움이 남았습니다.

구현했지만 사용되지 못한 기능들

프로젝트 기간의 압박 또한 아쉬움으로 남았습니다.

• NPC 기반 상호작용 시스템
• 상점(Shop) 기능

위 기능들은 실제로 구현까지 완료했지만, 전체 일정과 콘텐츠 우선순위 문제로 인해 최종 빌드에는 포함되지 못했습니다.

기능 자체보다는,

“만들었지만 쓰이지 못했다” 는 점이 개인적으로 가장 아쉬웠던 부분이었습니다.

그럼에도 불구하고 얻은 것들

다만, 이 프로젝트가 실패나 손해만 남긴 경험이었다고 생각하지는 않습니다.

오히려 다음과 같은 점에서 의미 있는 경험이었습니다.

• 한 프로젝트 안에서 NPC, 상점, 대화, 시스템 구조 설계 등 다양한 영역을 직접 구현해볼 수 있었던 점
• 기획 변경이라는 현실적인 상황 속에서 개발자가 어떻게 대응해야 하는지를 체감한 점
• “내가 구현한 기능이 왜 필요 없어졌는지”를 감정이 아닌 기획적 관점에서 이해하려 노력했던 경험

이 경험들은 단기적인 결과보다, 미래의 나에게 분명히 도움이 될 자산이라고 생각합니다.

향후 개선할 수 있었던 점

회고를 통해 정리해본, 다음 프로젝트에서 반드시 개선하고 싶은 부분은 다음과 같습니다.

1. 기획 변경 리스크를 고려한 역할 설계
   • 특정 기능 하나에 과도하게 의존하기보다는 변경에 대응 가능한 범용적인 기여 구조를 가져갈 필요성을 느꼈습니다.

2. 조기 통합 및 우선순위 협의
   • “나중에 쓰일 기능”이 아니라 “지금 당장 프로젝트에 들어갈 기능” 위주로 팀과 더 적극적으로 조율했어야 했다고 생각합니다.

3. 기술 구현의 목적 명확화
   • 단순히 구현하는 것에서 끝나는 것이 아니라 “이 기능이 프로젝트에 어떤 가치를 주는가”를 더 명확히 설명하고 공유했어야 했습니다.

마치며

Project Arc는 결과만 놓고 보면 아쉬움이 남는 프로젝트였지만, 과정만큼은 분명히 성장으로 이어진 시간이었습니다.

기획은 언제든 바뀔 수 있고, 개발자의 역할 역시 그에 따라 변할 수 있다는 현실 속에서 유연하게 사고하고, 다음을 준비하는 태도의 중요성을 배웠습니다.

이 프로젝트에서의 경험과 시행착오는 다음 프로젝트에서 더 나은 선택을 하기 위한 밑거름이 될 것이라 믿습니다.

문제 상황 정리

• 증상
  • 레이트레이싱 옵션을 활성화한 상태에서 심리스 트래블(SeamlessTravel) 을 수행하면 간헐적으로 게임이 크래시.
  • 에디터 PIE나 레이트레이싱 OFF 환경에서는 잘 동작.

• 크래시 로그 핵심 부분 (요약)
  • Assertion 실패:
    • Array index out of bounds: 1 into an array of size 1
  • 콜스택 상 중요한 함수:
    • FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances()
    • RayTracing::FDynamicRayTracingInstancesContext::GatherDynamicRayTracingInstances_Internal()

• 로그 일부:

```text
Assertion failed: (Index >= 0) & (Index < ArrayNum)
[File:...Array.h] [Line: 1067]
Array index out of bounds: 1 into an array of size 1
...
FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances()
RayTracing::FDynamicRayTracingInstancesContext::GatherDynamicRayTracingInstances_Internal()
Crash in runnable thread Foreground Worker #1
```

• 로그에서 볼 수 있는 사실
  • 크래시가 레이트레이싱용 인스턴스 수집 과정(GatherDynamicRayTracingInstances)에서 발생.
  • 특히 FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances() 내부에서 ISM 관련 배열 접근 시 인덱스 범위가 꼬인 상태.
  • 즉, InstancedStaticMesh 의 내부 상태(인스턴스 배열)가 심리스 트래블 전후 과정에서 깨졌을 가능성이 매우 높음.

원인 분석

• 전제
  • InstancedStaticMeshComponent(ISM)는 각 월드(서버/클라) 에 존재.
  • 레이트레이싱은 각 클라이언트의 로컬 월드 안에 있는 ISM/StaticMesh 를 기준으로 씬을 빌드.

• 추정 원인
  • 심리스 트래블 시, 이전 월드에서 사용하던 ISM 인스턴스들이 완전히 정리되지 않은 상태에서
    • 월드가 전환되거나, 레이트레이싱 씬이 갱신되면서
    • 내부 PerInstanceRenderData / 인스턴스 배열 크기 정보가 어긋난 상태로 참조되는 상황.
  • 그 결과, FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances() 가
    • ArrayNum == 1 인 배열을 Index == 1로 접근하는 식의 out-of-bounds 접근을 시도하다가 Assert 에 걸림.

• 왜 심리스 트래블에서만 티가 났는지
  • 일반적인 레벨 로드(OpenLevel)에서는 월드와 렌더링 관련 리소스가 비교적 깨끗하게 재생성/파괴됨.
  • 심리스 트래블은 플레이어 관련 객체(Controller, PlayerState 등)를 유지한 채 월드만 교체하기 때문에
    • 일부 렌더링/ISM 관련 리소스가 월드 전환 타이밍에 완전히 정리되지 않고 남는 경우가 발생할 수 있음.
  • 특히 레이트레이싱은 별도의 동적 인스턴스 수집/관리 경로를 타기 때문에, 이런 내부 상태 꼬임이 Assert 로 바로 드러남.

해결 전략

• 목표
  • 심리스 트래블 직전/직후에 각 월드의 ISM 상태를 확실하게 정리해서,
  • 레이트레이싱용 인스턴스 수집 시 깨진 데이터를 참조하지 않도록 만들기.

• 고려한 방향들
  1. ISM 을 소유한 액터의 EndPlay / BeginDestroy 에서 개별적으로 정리
     • 가장 이상적인 구조지만, 현재 프로젝트 규모 상 모든 ISM 사용처를 일일이 추적하기에는 비용이 큼.
  2. 월드 단위로 ISM 을 한 번에 정리하는 세이프가드 추가
     • 심리스 트래블 직후, 각 클라이언트의 PlayerController가 자신이 속한 월드에서 ISM을 한 번 전체 스캔하여 인스턴스를 비우는 방식.

• 최종 선택
  • 2번 방식을 우선 적용:
    • ACMPlayerController::PostSeamlessTravel() 을 오버라이드.
    • 로컬 컨트롤러 기준으로 월드의 모든 UInstancedStaticMeshComponent 를 순회하며 ClearInstances() 호출.
    • 이 작업 이후, 기존에 구현해둔 캐릭터 재스폰 + 화면/사운드 페이드 인 로직을 그대로 이어서 실행.

구현 상세

1. PlayerController 에서 PostSeamlessTravel 오버라이드

• 파일 위치
  • Source/CrimsonMoon/Public/Controllers/CMPlayerController.h
  • Source/CrimsonMoon/Private/Controllers/CMPlayerController.cpp

• 헤더에 오버라이드 선언 (이미 추가되어 있음)

  • CMPlayerController.h (클래스 내부):

    • virtual void PostSeamlessTravel() override;

• cpp 에 구현 (주요 부분만 발췌)

역할:

• 심리스 트래블 완료 후, 로컬 월드의 모든 ISM 인스턴스를 정리
• 그 다음, 캐릭터 재스폰 및 화면/사운드 페이드 인

#include "Components/InstancedStaticMeshComponent.h"
#include "EngineUtils.h" // TActorIterator

void ACMPlayerController::PostSeamlessTravel()
{
    Super::PostSeamlessTravel();

    // 로컬 컨트롤러가 아닌 경우 아무 것도 하지 않음 (서버 전용 PC 등 제외)
    if (!IsLocalController())
    {
        return;
    }

    // 1) 로컬 월드의 모든 InstancedStaticMeshComponent 정리
    if (UWorld* World = GetWorld())
    {
        for (TActorIterator<AActor> It(World); It; ++It)
        {
            AActor* Actor = *It;
            if (!IsValid(Actor))
            {
                continue;
            }

            TArray<UInstancedStaticMeshComponent*> ISMComponents;
            Actor->GetComponents<UInstancedStaticMeshComponent>(ISMComponents);

            for (UInstancedStaticMeshComponent* ISMComp : ISMComponents)
            {
                if (!ISMComp)
                {
                    continue;
                }

                // 레이트레이싱/충돌 문제를 방지하기 위해 모든 인스턴스를 제거
                ISMComp->ClearInstances();
                ISMComp->MarkRenderStateDirty();
            }
        }
    }

    // 2) 심리스 트래블 후 캐릭터 재스폰 요청 (기존 로직)
    NotifyServerPlayerReadyWithCharacter();

    // 3) 화면/사운드 페이드 인 (검정 → 정상, 기존 연출)
    if (PlayerCameraManager)
    {
        PlayerCameraManager->StartCameraFade(
            /*FromAlpha*/ 1.0f,
            /*ToAlpha*/   0.0f,
            /*Duration*/  1.0f,
            /*Color*/     FLinearColor::Black,
            /*bShouldFadeAudio*/ true,
            /*bHoldWhenFinished*/ false
        );
    }
}

2. 기존 연출/로직과의 연계

• 이미 ACMPlayerController 에서는 심리스 트래블 이후에 다음 작업을 하고 있었음
  • NotifyServerPlayerReadyWithCharacter()
    • 서버에 선택된 캐릭터 태그를 보내고, 새 Pawn 스폰 요청.
  • StartCameraFade(1 → 0, bShouldFadeAudio=true)
    • 심리스 트래블 이전에 화면/오디오를 페이드 아웃한 것에 대응하여,
    • 새 맵에서 화면과 소리를 다시 자연스럽게 살리는 연출.

• 이번 수정에서는 이 두 기능을 유지한 채, 그 이전에 ISM 정리 로직을 끼워 넣는 형태로 구현.

적용 결과 및 배운 점

이번 수정 이후, 레이트레이싱을 활성화한 빌드에서 심리스 트래블을 반복 테스트했을 때, 기존에 발생하던 FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances 관련 Assert 크래시는 더 이상 재현되지 않았습니다.

물론 근본적으로는 ISM 을 소유하는 각 액터가 자신의 라이프사이클에 맞춰 적절히 정리되도록 설계하는 것이 가장 좋겠지만, 이번과 같이 레이트레이싱 + 심리스 트래블 조합에서 내부 상태 꼬임으로 인한 크래시가 발생할 때에는,

• 월드 단위로 ISM 을 한 번 "강제로" 정리해 주는 세이프가드를 추가하여
• RT/Physics 씬에 남아 있는 잘못된 인스턴스 데이터를 제거하는 것만으로도
• 실질적인 크래시 문제를 빠르게 완화할 수 있다는 점을 다시 확인하게 되었습니다.

앞으로는 ISM 을 대량으로 사용하는 시스템을 설계할 때,

• 멀티플레이/심리스 트래블,
• 레벨 스트리밍,
• 레이트레이싱/Physics 씬 빌드 타이밍 같은 요소까지 함께 고려해서 "누가 언제 ISM 을 생성/정리할 것인가" 를 처음부터 명확히 정리해 두는 것이 중요하다는 것을 배웠습니다.

오늘은 언리얼 멀티플레이 환경에서 플레이어 카메라 시점이 보이지 않는 문제를 Activate로 해결한 과정과, 아직 남아 있는 카메라 회전(Input_Look) 문제를 원인 중심으로 정리하고자 합니다.

문제 상황 요약

• 환경: UE5, 멀티플레이(Host + Client), C++ 기반 캐릭터/컨트롤러, BP 기반 GameplayCamera 사용
• 증상 1: Client 입장에서 플레이어 Pawn 은 스폰되고 Possess 도 되지만, 카메라 시점이 비어 있거나 이상한 위치를 비춤
• 증상 2: Host 에서는 정상 동작하는 것처럼 보이지만, Client 쪽에서만 카메라 관련 문제 발생
• 추가 증상: 시점을 보이게 만드는 문제는 해결했지만, 마우스 입력에 따른 카메라 상하좌우 회전은 아직 제대로 동작하지 않음

원인 분석: 카메라 시점(Activate) 문제

1. ViewCamera vs GameplayCamera 사용 불일치

• C++ ACMPlayerCharacterBase 안에는 ViewCamera(UCameraComponent) 와 CameraBoom(USpringArmComponent) 가 존재
  • CameraBoom->bUsePawnControlRotation = true;
  • ViewCamera->bAutoActivate = false;
• 하지만 실제 게임에서는 캐릭터 BP 에서 별도의 GameplayCamera 컴포넌트(UGameplayCameraComponent 파생 BP) 를 메인 카메라로 사용 중
• 결과적으로:
  • C++에서 ViewCamera->Activate() 를 호출해도 실제로 화면에 쓰이는 카메라는 GameplayCamera 이므로, 시점 문제는 그대로 유지

2. 네트워크에서 Possess/BeginPlay 타이밍 차이

• 서버:
  • GameMode 에서 Pawn 생성 → NewPlayer->Possess(NewPawn) 실행
  • 서버 기준에서는 Possess 타이밍이 확실
• 클라이언트:
  • Pawn 이 복제되고 BeginPlay 가 먼저 호출된 뒤에,
  • 컨트롤러 소유 정보가 들어오고 PawnClientRestart/OnRep_Controller 등이 호출됨
• BeginPlay 기준으로 카메라 Setup 을 시도하면:
  • Host(리스너 서버)는 우연히 잘 동작할 수 있지만,
  • 순수 Client 에서는 아직 로컬 컨트롤러가 붙지 않은 상태일 수 있어서 IsLocallyControlled() 가 false 인 경우가 많음
  • 이 경우, 로컬 전용 카메라 Activate 로직이 실행되지 않음

해결 전략: PawnClientRestart에서 GameplayCamera Activate

선택한 기준 시점

• 네트워크 플레이에서 로컬 클라이언트가 이 Pawn 을 실제로 조종할 준비가 된 시점은 APawn::PawnClientRestart() 에서 가장 확실
• 이유:
  • 컨트롤러/Owner 정보가 세팅된 뒤 호출됨
  • 입력 매핑(Enhanced Input)도 이 시점에 다시 셋업하는 패턴이 일반적
  • Host / Client 양쪽에서 동일한 타이밍 보장

구현 아이디어

• ACMPlayerCharacterBase 에 카메라 셋업 전용 헬퍼 함수 추가
  • UGameplayCameraComponent 를 FindComponentByClass 로 찾아온다.
  • 해당 컴포넌트에 대해 Activate() (또는 SetupCamera()) 를 호출한다.
• PawnClientRestart() 에서:
  • 기존 입력 매핑 설정 후
  • 바로 이 헬퍼 함수를 호출하여, 로컬 플레이어의 카메라를 활성화한다.

적용한 헬퍼 함수 소스코드

1. 헤더 선언 (ACMPlayerCharacterBase.h)

• 전방 선언 및 private 헬퍼 함수 선언

class UGameplayCameraComponent;

UCLASS()
class CRIMSONMOON_API ACMPlayerCharacterBase : public ACMCharacterBase
{
    GENERATED_BODY()

    // ...existing code...

private:
    // BeginPlay 이후, 로컬 플레이어 기준으로 GameplayCamera를 셋업하는 헬퍼 함수
    void SetupGameplayCamera_Helper();

    // ...existing code...
};

2. 구현부 (ACMPlayerCharacterBase.cpp)

void ACMPlayerCharacterBase::SetupGameplayCamera_Helper()
{
    UE_LOG(LogTemp, Warning,
        TEXT("SetupGameplayCamera_Helper: Called. IsLocallyControlled=%d"),
        IsLocallyControlled() ? 1 : 0);

    // 로컬 플레이어가 소유한 Pawn 에서만 카메라 셋업
    if (!IsLocallyControlled())
    {
        UE_LOG(LogTemp, Warning,
            TEXT("SetupGameplayCamera_Helper: Aborted - not locally controlled"));
        return;
    }

    // BP 에서 추가된 UGameplayCameraComponent 를 찾아 SetupCamera/Activate 호출
    if (UGameplayCameraComponent* GameplayCameraComp = FindComponentByClass<UGameplayCameraComponent>())
    {
        UE_LOG(LogTemp, Warning,
            TEXT("SetupGameplayCamera_Helper: Found GameplayCameraComponent on %s, calling SetupCamera"),
            *GetName());

        // 현재는 Activate로 시점을 살려두었음 (필요 시 SetupCamera()로 교체 가능)
        GameplayCameraComp->Activate();
        // GameplayCameraComp->SetupCamera();
    }
    else
    {
        UE_LOG(LogTemp, Warning,
            TEXT("SetupGameplayCamera_Helper: GameplayCameraComponent not found on %s"),
            *GetName());
    }
}

PawnClientRestart에서 호출

void ACMPlayerCharacterBase::PawnClientRestart()
{
    Super::PawnClientRestart();

    if (const APlayerController* OwningPlayerController = GetController<APlayerController>())
    {
        UEnhancedInputLocalPlayerSubsystem* PlayerSubsystem =
            OwningPlayerController->GetLocalPlayer()->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>();

        check(PlayerSubsystem);

        PlayerSubsystem->RemoveMappingContext(InputConfigDataAsset->DefaultMappingContext);
        PlayerSubsystem->AddMappingContext(InputConfigDataAsset->DefaultMappingContext, 0);
    }

    // 로컬 클라이언트가 이 Pawn 을 다시 사용할 준비가 된 시점에 카메라 셋업 시도
    SetupGameplayCamera_Helper();
}

현재 상태: 시점 문제는 해결, 회전 문제는 미해결

해결된 부분

• Host / Client 모두에서:
  • GameplayCameraComponent 를 로컬 클라이언트 기준으로 Activate 하도록 변경
  • PawnClientRestart 기준으로 실행되기 때문에, 네트워크 타이밍 문제(컨트롤러 미소유 상태)는 피함
• 결과적으로:
  • 카메라 시점이 비어 있거나, 이상한 곳을 비추던 문제는 해결됨
  • 캐릭터를 정상적으로 화면에 비추고, 이동/전투 플레이가 가능해짐

아직 해결되지 않은 부분: 마우스 입력에 따른 카메라 회전

• 남아 있는 문제:
  • 마우스 입력(Input_Look)에 따라 카메라가 상하좌우로 자연스럽게 회전해야 하는데,
  • 지금은 시점은 잡히지만, 회전이 작동하지 않음
• 추정 원인:
  • C++ 측에서는 Input_Look 에서 AddControllerYawInput, AddControllerPitchInput 을 호출하고 있음
  • 하지만 실제로 화면에 쓰이는 것은 BP 기반 GameplayCamera 이고,
  • 이 GameplayCamera/SpringArm 이 컨트롤러 회전을 제대로 반영하지 않거나,
    • bUsePawnControlRotation 설정이 비활성화되어 있거나,
    • 자체 로직으로만 회전을 제어하고 있을 가능성이 큼
  • 따라서 컨트롤러 회전 값은 변하지만, 카메라 컴포넌트가 그 값을 사용하지 않는 상태일 수 있음
• 요약:
  • "카메라가 안 보인다" 문제는 UGameplayCameraComponent Activate 로 해결
  • "카메라가 마우스 입력대로 돌지 않는다" 문제는 GameplayCamera의 회전 설정/로직 조정이 추가로 필요

마치며

이번 작업에서는 네트워크 환경에서 플레이어 카메라 시점이 비정상적으로 비춰지는 문제를, PawnClientRestart 시점에 UGameplayCameraComponent 를 찾아 Activate 하는 방식으로 해결하였습니다. 특히 BeginPlay, PossessedBy, PawnClientRestart 간의 호출 시점과 IsLocallyControlled() 여부가 네트워크 환경에서 어떻게 달라지는지 다시 한 번 정리할 수 있었고, 로컬 전용 카메라 로직은 PawnClientRestart 에서 처리하는 것이 안전하다는 점을 확인했습니다.

다만, 아직 마우스 입력에 따른 카메라 상하좌우 회전이 기대한 대로 동작하지 않는 문제가 남아 있습니다. 이는 C++ 단의 Input_Look 처리가 아니라, 실제 뷰를 담당하고 있는 GameplayCamera 컴포넌트의 회전 설정과 로직이 컨트롤러 회전을 어떻게 받아들이는지에 더 가깝기 때문에, 다음 단계에서는 해당 BP/컴포넌트의 bUsePawnControlRotation 설정, SpringArm 사용 여부, ViewTarget 세팅 방식을 집중적으로 점검하고 수정할 예정입니다.

목표는 다음과 같습니다.

• NPC와 상호작용(Interact)했을 때 서버 인원 전체를 특정 맵으로 이동시키기
• 이동 전 화면이 서서히 어두워지는 연출(페이드 아웃) 추가
• Interact 로직이 항상 서버(Host) 에서만 실행되도록 보장
• 특히, Remote Client가 조종하는 캐릭터가 Interact를 수행했을 때는 GameStarter 로직이 실행되지 않도록 필터링

특히, 게임 시작이 Host에서만 수행되도록 해야 하지만, Interact가 서버를 통해 수행되어 의도와 다르게 수행됐던 문제를 중점적으로 다뤄보고자 합니다.

현재 상호작용(Interact) 구조 분석

1. 입력 처리 흐름 (클라이언트)

• 컴포넌트: UCMPickUpComponent
• 역할: 입력 바인딩 및 상호작용 대상 관리
• 주요 특징
  • BeginPlay에서 입력 시스템 초기화 시도 (InitializeInputSystem)
  • 로컬 플레이어 컨트롤러가 준비되면 Enhanced Input으로 Interact 액션 바인딩
  • Tick에서 서버 기준으로 가장 가까운 상호작용 대상(CurrentInteractableActor)을 계산 및 복제

• 입력 처리 함수
  • UCMPickUpComponent::OnPickupInput(const FInputActionValue& Value)
    • Interact 키(예: 2번)를 누르면 호출
    • 직접 트레이스를 하지 않고, Ability System에 태그를 기반으로 Activiate 요청
    • 코드 요약
      • AbilitySystemComponent->TryActivateAbilitiesByTag(InteractAbilityTag, true);
    • 이 부분은 클라이언트 로컬에서만 실행됨

2. Gameplay Ability 실행 (서버)

• 클래스: UCMAbility_Interact
• 역할: Interact Ability의 실제 실행 로직
• 핵심 설정
  • NetExecutionPolicy = EGameplayAbilityNetExecutionPolicy::ServerOnly;
  • 의미: Ability의 ActivateAbility 는 항상 서버에서만 실행

• 실행 흐름 요약
  • AvatarActor (보통 플레이어 캐릭터)를 가져옴
  • AvatarActor에서 UCMPickUpComponent를 찾음
  • PickUpComp->GetCurrentInteractable()로 상호작용 대상 HitActor 획득
  • HitActor가 UCMInteractableInterface 구현 시:
    • ICMInteractableInterface::Execute_Interact(HitActor, AvatarActor);
  • 어빌리티 종료 (EndAbility)

• 시사점
  • Interact 입력은 클라이언트에서 시작하지만,
  • 실제 Interact 실행(인터페이스 호출)은 서버에서 수행됨

3. NPC 인터페이스 및 GameStarter NPC 역할

• 기본 NPC 클래스: ACMNpcBase
  • ICMInteractableInterface 를 구현
  • 기본적인 상호작용/대화/상점 등 공통 로직 보유

• GameStarter NPC: ACMNpcGameStarter : public ACMNpcBase
  • 역할
    • 특정 NPC와의 Interact 시, 서버 전체를 지정 맵으로 이동(ServerTravel)
    • 이동 직전, 모든 클라이언트 화면을 서서히 어둡게(페이드 아웃) 처리
  • 제약 조건
    • Ability 쪽 코드는 수정하지 않음
    • 필터링 로직은 GameStarter NPC 내부에서만 구현
    • Remote Client가 조종하는 캐릭터의 Interact는 무시

GameStarter NPC에서의 Remote Client 필터링 설계

1. 요구사항 정리

• Interact 구조(입력 → Ability → 서버에서 Interact 호출)는 그대로 유지
• 단, GameStarter NPC 입장에서 Interactor가 누구인지 보고 다음과 같이 처리
  • Interactor가 Remote 클라이언트가 조종하는 Pawn이면 → GameStarter 로직 실행 X
  • Interactor가 리슨 서버(Host)가 조종하는 Pawn 또는 기타 허용된 주체라면 → GameStarter 로직 실행 O

2. 서버 관점에서 Remote Client 판별 기준

• 서버 기준에서 APawn 의 Controller 를 통해 판별
• 판별 로직
  • Controller->IsPlayerController() == true 이면, 플레이어가 조종하는 Pawn
  • 이 때,
    • Controller->IsLocalController() == true → 서버 자신(리슨 서버) 혹은 서버 로컬 컨트롤러
    • Controller->IsLocalController() == false → Remote 클라이언트가 조종 중인 Pawn
• 따라서 아래 조합으로 Remote 클라이언트를 판별 가능
  • Controller->IsPlayerController() && !Controller->IsLocalController()

이를 GameStarter NPC의 Interact_Implementation 안에서 사용하여 필터링을 구현했습니다.

ACMNpcGameStarter 내부 구현 변화

1. 클래스 인터페이스 확장 (헤더)

• 파일: CMNpcGameStarter.h

• 변경 사항

  • Interact_Implementation(AActor* Interactor) 오버라이드 선언
  • PerformInteract() 를 override 로 선언해 GameStarter 전용 로직 수행
  • GameStart에 필요한 설정값을 프로퍼티로 추가

• 주요 멤버 요약

  • virtual void Interact_Implementation(AActor* Interactor) override;
  • virtual void PerformInteract() override;
  • UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "GameStart") FString TravelURL;
  • UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "GameStart") float FadeDuration = 1.0f;
  • UFUNCTION(NetMulticast, Reliable) void MulticastStartFadeOut();
  • void ServerTravelToConfiguredMap();

2. Interact_Implementation에서 Remote Client 필터링

• 파일: CMNpcGameStarter.cpp
• 핵심 로직
  • 오직 서버(또는 리슨 서버) 에서만 Interact 처리
  • Interactor 가 Remote 클라가 조종하는 Pawn이면 조용히 return;
  • 그 외 Interactor에 대해서만 PerformInteract() 호출
• 로직 개요
  • 권한 체크
    • if (!HasAuthority() && GetNetMode() != NM_ListenServer) return;
  • Interactor 타입 검사
    • APawn* Pawn = Cast<APawn>(Interactor);
    • AController* Controller = Pawn->GetController();
  • Remote Client 판별
    • Controller->IsPlayerController() && !Controller->IsLocalController() → Remote 클라
  • 필터링
    • 위 조건이면 return; → GameStart 로직 미실행
  • 허용 시
    • PerformInteract(); 호출

3. PerformInteract: 서버 전용 GameStart 로직

• 역할
  • 서버에서만 실행되는 GameStart 핵심 로직
  • 전체 클라이언트에 페이드 아웃 명령 전파
  • 페이드가 끝난 시점에 ServerTravel 수행
• 동작 순서
  1. HasAuthority() + NetMode 체크로 서버/리슨 서버에서만 진행
  2. UWorld* World = GetWorld(); 유효성 확인
  3. MulticastStartFadeOut(); 호출 → NetMulticast RPC
  4. World->GetTimerManager().SetTimer(..., FadeDuration); 로 ServerTravelToConfiguredMap 예약 호출
• 이로 인해:
  • 클라이언트가 Interact 입력을 하더라도
  • Ability → 서버에서 Interact → GameStarter → 추가 필터링 후 허용된 경우에만 서버 트래블이 실행됨

4. MulticastStartFadeOut: 모든 클라에서 로컬 화면 페이드

• 함수: MulticastStartFadeOut_Implementation()
• 특성: NetMulticast, Reliable
  • 서버에서 한 번 호출하면, 서버 + 모든 클라이언트 월드에서 각각 1번씩 실행
• 동작
  • UWorld* World = GetWorld();
  • APlayerController* PC = World->GetFirstPlayerController();
  • PC->IsLocalController() 인 경우에만 페이드 적용
  • PC->PlayerCameraManager->StartCameraFade(0.0f, 1.0f, FadeDuration, FLinearColor::Black, true, true);
• 결과
  • 각 클라이언트가 자기 화면에서만 0 → 1 알파로 서서히 어두워짐
  • Remote/로컬 구분 없이, 모든 접속자 화면에서 동일한 페이드 아웃 연출 발생

5. ServerTravelToConfiguredMap: 서버 인원 전체 맵 이동

• 역할
  • 에디터에서 설정한 TravelURL 을 기준으로 ServerTravel 실행
• 동작 요약
  • 서버/리슨 서버에서만 실행 (HasAuthority() 체크)
  • TravelURL.IsEmpty() 시 로그만 출력하고 종료
  • World->ServerTravel(TravelURL, /*bAbsolute*/ false);
• 효과
  • 서버가 새로운 맵으로 트래블하면서,
  • 현재 접속 중인 모든 클라이언트도 해당 맵으로 함께 이동

5. 상호작용 흐름 전체 시각화

6. 얻은 인사이트 및 정리

오늘 작업을 통해 다음과 같은 점을 다시 정리할 수 있었습니다.

• 입력과 실행 주체의 분리
  • 상호작용 입력은 클라이언트에서 발생하지만,
  • 실제 게임 규칙(Logics)은 ServerOnly Ability와 서버 측 NPC 로직을 통해 서버에서만 결정하도록 설계할 수 있음

• Remote Client 필터링은 Interactor 정보를 활용해 GameStart 클래스 내부에서 충분히 처리 가능
  • Ability 구조를 건드리지 않고도,
  • Interact_Implementation(AActor* Interactor) 에서 Interactor의 Controller를 검사하여
  • Remote 클라이언트가 조종하는 Pawn의 Interact만 깔끔하게 차단할 수 있었음

• NetMulticast + 로컬 컨트롤러 검사로 시각 효과를 안전하게 분배
  • NetMulticast 함수는 월드마다 한 번씩 실행되므로,
  • 함수 내부에서 GetFirstPlayerController() + IsLocalController() 조합을 사용하면
  • 각 클라이언트의 로컬 화면에만 시각 효과(페이드)를 적용할 수 있음

• 서버 트래블(ServerTravel)과 연출(페이드)을 분리하여 타이밍 제어
  • 페이드 아웃 → 타이머 → ServerTravel 순으로 분리함으로써,
  • 연출 타이밍과 실제 맵 전환 타이밍을 명확하게 제어할 수 있었음

앞으로는 이 패턴을 바탕으로, 특정 권한(예: GM 전용, 특정 팀 전용)만 사용할 수 있는 상호작용 오브젝트를 설계할 때, Interactor 기반 필터링을 적극적으로 활용할 계획입니다.

이번 작업의 핵심은 다음과 같습니다. CMShopContentElementWidget을 클릭 → CMShopWidget에서 선택 상태 갱신 → 상세 UI에 이름/설명/수량 표시 → 수량 버튼으로 Quantity 증감까지의 흐름을 자연스럽게 만드는 것이었습니다.

오늘 구현/정리한 내용

Shop UI 전체 흐름 요약

• 서버에서 상점 데이터를 가져와서 클라이언트의 UCMShopWidget에 전달하는 기존 구조를 재확인하였습니다.
• CreateShopWidget에서 이미 상점 위젯 인스턴스가 있을 경우에는 SetShopItems + BuildShopList만 다시 호출하여 재사용하도록 되어 있음을 확인했습니다.

CMShopWidget: 아이템 선택 및 수량 표시 로직

주요 멤버 정리

• FCMShopItemContent CurrentSelectedItem;
  • 현재 선택된 상점 아이템 정보 구조체
• int32 SeletedItemQuantity = 0;
  • 현재 선택된 아이템의 수량(Quantity)
• UTextBlock* SelectedItemNameText;
  • 선택 아이템 이름 표시용 텍스트
• UTextBlock* SelectedItemQuantityText;
  • 선택 아이템 수량 표시용 텍스트
• UTextBlock* ItemDescriptionText;
  • 선택 아이템 설명 표시용 텍스트
• UButton* AddItemQuantityButton;
  • 수량 증가 버튼(+)
• UButton* SubtractItemQuantityButton;
  • 수량 감소 버튼(-)

초기화 및 버튼 바인딩

• NativeOnInitialized()에서 다음과 같이 버튼과 핸들러를 바인딩
  • AddItemQuantityButton -> OnClickedAddItemQuantityButton
  • SubtractItemQuantityButton -> OnClickedSubtractItemQuantityButton
• 이 핸들러 함수들은 반드시 UFUNCTION()으로 선언해 델리게이트와 호환되도록 처리

아이템 선택 처리: HandleElementSelected

UCMShopContentElementWidget(리스트 요소)을 클릭했을 때 호출되는 콜백입니다.

• 역할
  • 리스트에서 클릭된 요소의 FCMShopItemContent를 받아와 현재 선택 아이템으로 저장
  • 선택과 동시에 수량을 1로 초기화
  • 상세 UI 텍스트를 갱신

개념적으로는 다음과 같습니다.

• CurrentSelectedItem = ElementWidget->GetItemContent();
• SeletedItemQuantity = 1;
• UpdateSelectedItemDisplay();

상세 표시 함수: UpdateSelectedItemDisplay

선택된 아이템 정보를 실제 UI 텍스트에 반영하는 책임을 가집니다.

• 이름 텍스트
  • SelectedItemNameText->SetText(...) 호출
  • FCMShopItemContent 내부의 이름 필드 타입을 고려하여 FName → FText::FromName, 또는 이미 FText라면 그대로 세팅
• 수량 텍스트
  • SelectedItemQuantityText->SetText(FText::AsNumber(SeletedItemQuantity));
• 설명 텍스트
  • ItemDescriptionText->SetText(CurrentSelectedItem.ItemDescription);

에디터에서 바인딩한 텍스트 위젯들이 nullptr일 수 있으므로, 각 항목마다 if (SelectedItemNameText) 같은 널 체크 후 세팅하는 패턴으로 작성했습니다.

수량 증감 로직: UpdateSelectedItemQuantityDelta

수량 버튼 양쪽에서 공통으로 사용하는 내부 함수입니다.

• 인자
  • int32 Delta : +1, -1 등의 증감 값
• 처리
  • SeletedItemQuantity = FMath::Clamp(SeletedItemQuantity + Delta, 1, 99);
    • 최소 1, 최대 99로 제한
  • UpdateSelectedItemDisplay(); 호출하여 UI를 동기화

이렇게 함으로써, 수량이 UI와 항상 동일한 상태를 유지하게 했습니다.

수량 버튼 클릭 핸들러

• OnClickedAddItemQuantityButton()
  • UpdateSelectedItemQuantityDelta(1);
• OnClickedSubtractItemQuantityButton()
  • UpdateSelectedItemQuantityDelta(-1);

버튼은 단순히 증감 방향만 결정하고, 실제 로직은 UpdateSelectedItemQuantityDelta에 몰아 넣어 중복을 줄였습니다.

CMShopContentElementWidget과 CMShopWidget의 연결 방식

UCMShopContentElementWidget은 상점 리스트의 개별 아이템 슬롯입니다. 오늘은 이 위젯이 어떻게 상위 ShopWidget에 "선택됨"을 알리는지 흐름을 명확히 이해하는 데 집중했습니다.

데이터 전달 구조 (정리)

• CMNpcShopComponent에서 TArray<FCMShopItemContent>를 생성 및 관리
• ACMPlayerController::Server_RequestShopData_Implementation
  • NPC를 찾고, 그 NPC의 UCMNpcShopComponent에서 GetShopItemContents로 아이템 배열 획득
  • ListenServer/클라 구분 후, 최종적으로 CreateShopWidget(ShopItems) 호출
• UCMShopWidget::BuildShopList()
  • ShopItems를 순회하면서 UCMShopContentElementWidget 인스턴스들을 생성
  • 각 슬롯에 SetItemDisplayData(Item, this)와 같은 방식으로
    • 표시용 데이터(이름, 가격, 아이콘 등)
    • 콜백 대상(ShopWidget 자기 자신)을 전달
• UCMShopContentElementWidget 내부에서 OnClicked 등 이벤트 발생 시
  • 바인딩된 UCMShopWidget::HandleElementSelected(this) 호출

이 과정을 통해 슬롯 → 상점 메인 위젯으로 자연스럽게 선택 이벤트가 올라오도록 설계되어 있습니다.

네이밍 및 바인딩 정리 (Count → Quantity)

오늘 도중에 발견한 네이밍 혼선을 정리했습니다. 기존에는 일부 버튼/텍스트가 Count라는 이름을 사용하고 있었고, 다른 부분에서는 Quantity를 사용하고 있었습니다. 이를 전부 Quantity로 통일했습니다.

• 버튼
  • AddItemCountButton → AddItemQuantityButton
  • SubtractItemCountButton → SubtractItemQuantityButton
• 텍스트
  • SelectedItemCountText → SelectedItemQuantityText
• 함수
  • OnClickedAddItemCountButton → OnClickedAddItemQuantityButton
  • OnClickedSubtractItemCountButton → OnClickedSubtractItemQuantityButton
• UI 바인딩 주의
  • C++ 이름을 변경한 후, UMG 디자이너에서 위젯 변수 이름도 동일하게 변경해야 바인딩이 끊기지 않음을 재확인했습니다.

이 정리 덕분에 코드 가독성과 의도가 보다 명확해졌습니다.

마치며

오늘은 Shop UI에서 아이템 선택 → 상세 정보 반영 → 수량 증감이라는 한 흐름에 집중해서 구현과 리팩터링을 진행하였습니다. 특히 CMShopContentElementWidget과 CMShopWidget 사이의 이벤트 전달 구조를 확실히 이해하고 정리하면서, 이후 구매/판매 요청(RequestBuyItem, RequestSellItem)을 구현할 때도 같은 패턴을 확장해서 사용할 수 있겠다는 생각이 들었습니다.

또한, 이름을 Count에서 Quantity로 통일하고 버튼/텍스트/함수를 일관되게 정리한 덕분에, 나중에 상점 관련 기능을 확장할 때 혼동이 줄어들 것으로 기대합니다. 다음 단계에서는 오늘 만든 선택/수량 정보를 바탕으로 실제 서버 RPC(Server_RequestBuyItem, Server_RequestSellItem)와 연동하여 아이템 구매/판매 로직을 완성해 볼 계획입니다.

오늘은 프로젝트에 NPC 상점 시스템을 구현하고, NpcWorldSubsystem / NpcShopComponent / PlayerController / Shop UI 위젯 사이의 흐름을 점검하는 작업을 진행하였습니다.

상점 UI 생성 전체 플로우

오늘 작업한 내용 정리

• 데이터 구조 정리
  • FCMShopItemContent
    • FName ItemID : 아이템 식별용 ID
    • int32 BuyPrice : 구매 가격
    • int32 SellPrice : 판매 가격
    • int32 Quantity : 수량 정보
    • FText ItemName : 표시용 이름
    • UTexture2D* ItemIcon : 아이콘 이미지
  • UDataTable 기반으로 상점 아이템 목록을 관리하도록 설계
  • ACMNpcBase 에 TObjectPtr<UDataTable> ShopItemDataTable, FName NpcId 를 추가하여 NPC 단위로 상점 구성을 다르게 가져갈 수 있도록 준비

• NPC 캐싱 구조 설계 (UCMNpcWorldSubsystem)

  • FCMNpcCacheEntry
    • FName NpcId
    • TWeakObjectPtr<ACMNpcBase> NpcActor
  • TMap<FName, FCMNpcCacheEntry> NpcCacheMap 에 NPC를 ID 기반으로 캐싱
  • RegisterNpc(const FName& NpcId, ACMNpcBase* NpcActor)
    • NpcCacheMap.FindOrAdd(NpcId) 를 이용해 캐시 엔트리 생성/조회 후 값 설정
  • UnregisterNpc(const FName& NpcId)
    • NPC가 사라질 때 캐시에서 정리
  • GetNpcById(const FName& NpcId) const
    • 캐시에서 ID로 액터를 조회
  • GetAllNpcEntries(TArray<FCMNpcCacheEntry>& OutEntries) const
    • 디버깅 및 툴 제작용 전체 조회 함수 제공

• NPC에서 Subsystem 등록 흐름

  • ACMNpcBase
    • FName NpcId 를 에디터에서 설정 가능하도록 노출
    • NPC가 BeginPlay 시점에 UCMNpcWorldSubsystem 을 가져와 RegisterNpc(NpcId, this) 를 호출하도록 구현
    • EndPlay 시점에는 UnregisterNpc(NpcId) 로 정리
  • 이를 통해 서버(호스트)에서 모든 NPC를 ID로 빠르게 찾을 수 있는 구조 확보

• NPC 상점 컴포넌트 (UCMNpcShopComponent)

  • UCMNpcComponentBase 를 상속
  • TArray<FCMShopItemContent> ShopItemContents 를 내부에 보관
  • 인터페이스
    • virtual void PerformAction() override;
    • void SetShopItemContents(const TArray<FCMShopItemContent>& InItems);
    • void GetShopItemContents(TArray<FCMShopItemContent>& OutItems) const;
  • PerformAction() 에서의 역할
    • NPC 오너(ACMNpcBase) 로부터 NpcId 를 가져옴
    • 로컬 플레이어 컨트롤러(ACMPlayerController)를 찾아 RequestOpenShopUI(NpcId) 호출
    • 상점 액션이 트리거되면 컨트롤러를 통해 상점 UI 요청이 이어지도록 연결

• PlayerController의 상점 UI 흐름 (ACMPlayerController)

  • 프로퍼티
    • TSubclassOf<UCMShopWidget> ShopWidgetClass; : 에디터에서 상점 메인 위젯 클래스 지정
    • UCMShopWidget* ShopWidgetInstance; : 런타임 인스턴스 보관
  • 상점 UI 요청 진입점
    • UFUNCTION(BlueprintCallable, Category = "Shop|UI") void RequestOpenShopUI(const FName& NpcId);
    • 로컬 컨트롤러인지 확인 후 Server_RequestShopData(NpcId) 호출
  • 서버 RPC
    • UFUNCTION(Server, Reliable, WithValidation) void Server_RequestShopData(const FName& NpcId);
    • 구현부에서
      • UCMNpcWorldSubsystem 에서 GetNpcById(NpcId) 로 NPC 조회
      • NPC의 UCMNpcShopComponent 를 찾아 GetShopItemContents() 로 상점 아이템 배열 획득
      • Host(리슨 서버) 인 경우: CreateShopWidget(ShopItems) 를 바로 호출하여 서버/클라 겸용 컨트롤러에서 UI 생성
      • 순수 클라이언트 인 경우: Client_ReceiveShopDataAndOpen(ShopItems) 클라 RPC 호출
  • 클라 RPC
    • UFUNCTION(Client, Reliable) void Client_ReceiveShopDataAndOpen(const TArray<FCMShopItemContent>& ShopItems);
    • 구현부에서 CreateShopWidget(ShopItems); 호출
  • 실제 UI 생성 함수
    • void CreateShopWidget(const TArray<FCMShopItemContent>& InShopItems);
    • IsLocalController() 확인 후
      • 이미 인스턴스가 있으면 SetShopItems() / BuildShopList() 만 호출하여 갱신
      • 없으면 UIManagerComponent->PushWidget(ShopWidgetClass) 로 위젯을 스택에 올린 뒤, 데이터 주입 및 리스트 빌드

• Shop 위젯 구현 (UCMShopWidget)

  • 구성 요소
    • UVerticalBox* ShopItemListBox; (BindWidget)
    • TSubclassOf<UCMShopContentElementWidget> ShopItemWidgetClass;
    • TArray<FCMShopItemContent> ShopItems;
  • 인터페이스
    • void SetShopItems(const TArray<FCMShopItemContent>& InItems);
    • void BuildShopList();
  • BuildShopList() 동작 개요
    • 기존 자식 위젯 제거
    • ShopItems를 순회하면서 ShopItemWidgetClass 로 UCMShopContentElementWidget 생성
    • 각 엘리먼트에
      • 아이템 이미지, 이름, 구매가, 판매가, 수량 등의 데이터를 바인딩
      • 구매 버튼 / 판매 버튼 클릭 델리게이트를 바인딩하여 상위 위젯 (UCMShopWidget) 의 HandleElementBuyRequested, HandleElementSellRequested 와 연결

• 개별 상점 아이템 위젯 (UCMShopContentElementWidget)

  • 역할
    • 한 개의 FCMShopItemContent 를 시각화
    • 이미지, 이름, 가격(구매/판매), 수량 등을 표시
    • "구매" 버튼 / "판매" 버튼 UI 제공
  • 이벤트
    • 구매 버튼 클릭 → 상위 위젯으로 "이 아이템을 구매하고 싶다" 이벤트 전파
    • 판매 버튼 클릭 → 상위 위젯으로 "이 아이템을 판매하고 싶다" 이벤트 전파
  • 상위 위젯에서 실제 로직(인벤토리 차감, 골드 변경, 서버 검증 등)을 처리할 수 있도록 설계

• Host(리슨 서버) / 클라이언트 동작 차이 정리

  • 공통
    • UCMNpcShopComponent::PerformAction() → ACMPlayerController::RequestOpenShopUI(NpcId) 호출
  • Host (ListenServer)
    • RequestOpenShopUI → Server_RequestShopData 가 같은 프로세스의 서버 컨텍스트에서 실행
    • 서버 내부에서 NpcWorldSubsystem 으로 상점 데이터 조회 후 CreateShopWidget 을 직접 호출
    • 별도의 클라 RPC 없이도 Host 화면에 상점 UI 표시
  • 순수 클라이언트
    • RequestOpenShopUI → Server RPC 로 서버에 상점 데이터 요청
    • 서버에서 상점 데이터 구성 후 Client_ReceiveShopDataAndOpen 으로 돌려줌
    • 클라이언트에서 CreateShopWidget 을 호출해 UIManager로 Push

• 디버깅용 로그 추가

  • CreateShopWidget
    • 인자로 전달된 ShopItems.Num() 과 첫 번째 아이템의 ItemID, ItemName, BuyPrice, SellPrice, Quantity 를 로그로 출력
    • 서버에서 받은 상점 데이터가 실제로 클라이언트까지 전달되었는지 확인하는 데 사용
  • Server_RequestShopData
    • NpcId 와 NPC/ShopComponent 유효성 체크 로그 출력
  • UCMNpcShopComponent::PerformAction
    • PerformAction 이 실제로 호출되는지, Owner NPC 및 NpcId 가 유효한지 확인하는 로그 출력

마치며

오늘은 NPC 상점 시스템의 전체 흐름을 정리하고, 특히 NpcWorldSubsystem 기반의 NPC 캐싱과 UCMNpcShopComponent → ACMPlayerController → UCMShopWidget 으로 이어지는 상점 UI 생성 파이프라인을 점검하였습니다. Host(리슨 서버) 환경과 순수 클라이언트 환경에서의 동작 차이를 고려하여 Server RPC 및 Client RPC 분기를 설계한 덕분에, 네트워크 환경에 따라 상점 UI가 일관되게 동작하도록 만들 수 있었습니다. 앞으로는 이 구조 위에 실제 구매/판매 서버 검증 로직과 인벤토리, 골드 연동 로직을 추가하여 완성도 높은 상점 시스템으로 발전시켜 나가고자 합니다.

상점 요소 위젯(UCMShopContentElementWidget) 설계

• 목적
  • 상점 리스트에서 한 개의 아이템을 표현하는 전용 위젯
  • UI 관점에서 재사용 가능한 단위 컴포넌트로 설계

• 표시 요소
  • 아이템 이미지: UImage* ItemImage
  • 아이템 이름: UTextBlock* ItemNameText
  • 구매 가격: UTextBlock* BuyPriceText
  • 판매 가격: UTextBlock* SellPriceText

• 동작 요소 (버튼)
  • 구매 버튼: UButton* BuyButton
  • 판매 버튼: UButton* SellButton

• 데이터 필드
  • 아이템 아이콘: TObjectPtr<UTexture2D> ItemIcon
  • 아이템 이름: FText ItemName
  • 구매 가격: int32 BuyPrice
  • 판매 가격: int32 SellPrice
  • 아이템 식별자: int32 ItemId 또는 FName ItemId (프로젝트 상황에 맞게 선택)

• 핵심 설정 함수
  • SetItemDisplayData(UTexture2D* InIcon, const FText& InName, int32 InBuyPrice, int32 InSellPrice, int32 InItemId)
    • 아이콘, 이름, 구매/판매 가격, 아이템 ID를 한 번에 세팅
    • 내부 Transient 필드에 값 저장 후, 바인딩된 위젯에 텍스트/이미지 반영

• 버튼 활성 제어
  • SetButtonsEnabled(bool bEnableBuy, bool bEnableSell)
    • 상황에 따라 구매만 가능 / 판매만 가능 / 둘 다 비활성 등을 제어

• 버튼 클릭 이벤트 처리 흐름
  • NativeOnInitialized()에서 버튼 클릭 바인딩
    • BuyButton->OnClicked.AddDynamic(this, &UCMShopContentElementWidget::HandleBuyClicked);
    • SellButton->OnClicked.AddDynamic(this, &UCMShopContentElementWidget::HandleSellClicked);
  • 내부 핸들러에서 델리게이트 브로드캐스트
    • OnBuyRequested.Broadcast(this);
    • OnSellRequested.Broadcast(this);
  • 외부(상점 메인 위젯)가 이 델리게이트에 바인딩해 실제 구매/판매 로직을 처리

• 외부에서 참조 가능한 Getter
  • GetBuyPrice() / GetSellPrice()
  • GetItemName() / GetItemIcon()
  • GetItemId()
  • 상위 위젯이 ElementWidget을 통해 아이템 정보를 재조회할 수 있도록 설계

상점 데이터 구조(FCMShopItem) 설계

• 목적
  • 상점에 노출할 아이템 정보를 모아 관리하기 위한 구조체
  • 상점 위젯이 TArray<FCMShopItem>를 기준으로 리스트를 생성하도록 설계

• 필드 구성
  • ItemID: 아이템 고유 식별자 (int32)
  • BuyPrice: 구매 가격
  • SellPrice: 판매 가격
  • Quantity: 수량 (스택 수, 재고 등 다양한 용도로 확장 가능)
  • ItemName: UI 표시용 이름
  • ItemIcon: UI 표시용 아이콘 텍스처

• 설계 포인트
  • Blueprint에서도 손쉽게 세팅할 수 있도록 BlueprintType, EditAnywhere, BlueprintReadWrite로 설정
  • 실제 게임 데이터(데이터 테이블, 데이터 애셋 등)와 연결하거나, 임시 테스트 데이터로도 사용 가능하게 유연하게 설계

상점 메인 위젯(UCMShopWidget) 설계

• 역할
  • 전체 상점 화면을 담당하는 메인 컨테이너 위젯
  • VerticalBox 안에 여러 UCMShopContentElementWidget을 동적으로 생성하여 리스트를 구성

• 주요 멤버
  • ShopItemListBox
    • 타입: UVerticalBox*
    • 역할: 상점 아이템들을 세로로 나열하는 컨테이너
    • UMG 디자이너에서 BindWidget 이름과 동일하게 배치
  • ShopItemWidgetClass
    • 타입: TSubclassOf<UCMShopContentElementWidget>
    • 역할: 각 아이템 엘리먼트로 생성할 위젯 클래스 (BP 기반으로 지정)
  • ShopItems
    • 타입: TArray<FCMShopItem>
    • 역할: 실제 상점에 표시할 아이템 데이터 목록

• 초기화 흐름
  • 생성자: UCMShopWidget(const FObjectInitializer& ObjectInitializer)
  • NativeOnInitialized()에서 초기 리스트 빌드 호출
    • BuildShopList();
    • 디자이너에서 ShopItems를 미리 세팅해 둔 경우 바로 UI에 리스트가 생성되도록 구성

• 리스트 빌드 로직 (BuildShopList)
  • ShopItemListBox 또는 ShopItemWidgetClass가 유효하지 않으면 조기 리턴
  • 기존 자식 위젯 제거: ShopItemListBox->ClearChildren();
  • ShopItems 배열을 순회하며 다음 작업 수행
    • CreateWidget<UCMShopContentElementWidget>(this, ShopItemWidgetClass)로 엘리먼트 위젯 생성
    • SetItemDisplayData로 이미지/이름/구매·판매 가격/ID 설정
    • OnBuyRequested, OnSellRequested 델리게이트를 메인 위젯의 핸들러에 바인딩
    • ShopItemListBox->AddChild(ElementWidget)으로 VerticalBox에 추가
    • UVerticalBoxSlot로 캐스팅해 정렬, 패딩 등 레이아웃 세부 설정

• 상점 데이터 갱신 (SetShopItems)
  • 외부에서 TArray<FCMShopItem>을 넘겨받아 ShopItems를 교체
  • 교체 직후 BuildShopList() 재호출로 UI를 바로 갱신
  • 코드/블루프린트 어디서든 상점 데이터만 갈아끼우면 UI 전체가 새로 그려지는 구조

• 버튼 클릭 이벤트 최종 처리
  • HandleElementBuyRequested(UCMShopContentElementWidget* ElementWidget)
    • ElementWidget->GetItemId()와 GetBuyPrice()로 어떤 아이템인지, 얼마인지 확인
    • 실제 구매 로직 (골드 차감, 인벤토리 추가 등)과 연결 예정
  • HandleElementSellRequested(UCMShopContentElementWidget* ElementWidget)
    • ElementWidget->GetItemId()와 GetSellPrice()를 사용
    • 실제 판매 로직 (인벤토리에서 제거, 골드 지급 등)과 연결 예정
  • 상점 위젯은 UI 이벤트를 게임 로직 레이어로 전달하는 허브 역할을 담당

UMG 에디터에서의 연결 작업 정리

• 상점 메인 위젯 BP (UCMShopWidget 기반)
  • 위젯 트리에서 VerticalBox 추가 후 이름을 ShopItemListBox로 지정
  • 클래스 디폴트에서 ShopItemWidgetClass에 UCMShopContentElementWidget 기반 BP를 할당
  • 테스트용으로 ShopItems 배열에 몇 개의 아이템 데이터 직접 입력해 즉시 미리보기 가능하게 설정

• 상점 요소 위젯 BP (UCMShopContentElementWidget 기반)
  • 이미지/텍스트/버튼 위젯 배치 후 이름 매칭
    • ItemImage
    • ItemNameText
    • BuyPriceText
    • SellPriceText
    • BuyButton
    • SellButton
  • C++의 BindWidgetOptional 속성과 이름이 일치하도록 관리해 자동 바인딩 확인

오늘은 언리얼 엔진 UMG를 사용해 상점 UI를 설계하고, 아이템 단위 위젯과 상점 메인 위젯 사이의 책임을 분리하는 구조를 구현해 보았습니다. 아이템 이미지, 이름, 구매/판매 가격, 그리고 식별용 ID까지 한 번에 관리할 수 있도록 설계함으로써 추후 실제 게임 데이터 및 인벤토리 시스템과의 연동이 훨씬 수월해질 것으로 기대하고 있습니다.

향후에는 오늘 설계한 UI 구조를 기반으로 실제 골드, 인벤토리, 툴팁, 필터링/정렬 기능 등을 추가하여 보다 완성도 높은 상점 시스템으로 확장해 나갈 계획입니다. 오늘의 정리가 이후 작업에 도움이 되기를 바랍니다.

전체 구조 개요

• 목표
  • NPC와 상호작용 시 대화 UI 표시
  • Next 버튼으로 다음 노드 진행
  • Action 노드가 있을 경우 선택지 버튼 동적 생성
  • 선택지 클릭 시 해당 액션 타입으로 NPC 컴포넌트 동작 수행
  • 대화 종료 시 델리게이트/상태 정리
• 핵심 구성 요소
  • ACMNpcBase : NPC 액터, 대화 트리 데이터/진행 로직 보유
  • UCMDialoagueNode / UCMActionNode : 대화 노드 & 액션 노드 트리 구조
  • UCMLocalEventManager : GameInstanceSubsystem, 대화용 델리게이트 허브
  • UCMGameInstance : GameInstance, 로컬 이벤트 매니저/세션 등 상위 관리
  • UCMNpcDialogueWidget : 대화 전체 UI, 텍스트/Next 버튼/선택지 컨테이너
  • UCMNpcDialogueChoiceElement : 개별 선택지 버튼 위젯
  • UUIManagerComponent : PlayerController에 부착, UI 스택 관리 및 뷰포트 표시

클래스 구조 (Mermaid 시각화)

상위 구조: GameInstance & Subsystem & NPC & UI

UI 구조: Dialogue Widget & Choice Element

대화 노드 구조: 노드 트리 & 액션 노드

이벤트 흐름 (상호작용 → 대화 → 선택지 → 종료)

다음 플로우 차트는 이벤트 흐름을 나타냅니다.

구현 상의 핵심 포인트

• GameInstanceSubsystem 활용

  • UCMLocalEventManager 를 UGameInstanceSubsystem 으로 두어, 맵 전환과 무관하게 대화 델리게이트를 공유 가능하게 설계
  • NPC, UI, 기타 시스템이 서로 직접 참조하지 않고 이벤트 허브를 통해 느슨하게 연결

• 델리게이트 기반 UI-로직 분리

  • NPC 쪽은 순수한 대화 트리/액션 처리에 집중
  • UI 쪽은 단지 델리게이트를 통해 텍스트와 선택지 정보를 받아 그리기만 함
  • 이로 인해 UI 변경(디자인 교체, 애니메이션 추가 등)이 NPC 로직에 영향을 주지 않음

• 액션 노드(선택지) 구조

  • 대화 트리는 UCMDialoagueNode 를 기본으로 하되, 선택지가 필요한 경우 파생 클래스 UCMActionNode 로 표현
  • 액션 노드는
    • DialogueText (선택지에 표시할 텍스트)
    • ActionType (ECMNpcComponentType) 을 가지며,
    • 선택 시 NPC가 어떤 컴포넌트의 어떤 액션을 수행해야 하는지 연결고리 역할을 수행

• EndDialogue 시 델리게이트 해제 철저

  • 대화 한 번 끝난 후에도 델리게이트가 남아있으면
    • 다음 대화에서 중복 호출, 크래시, 메모리 누수의 원인이 될 수 있음
  • EndDialogue() 에서 NPC ↔ LocalEventManager 간의 모든 바인딩을 명시적으로 해제

마치며

이번 NPC 대화 시스템 구현은 데이터 구조(트리 기반 대화 노드), 델리게이트 기반 이벤트 흐름, UI/로직 분리, GameInstanceSubsystem 활용이라는 네 가지 축을 중심으로 설계하고 구현하였습니다. 그 과정에서 UMG 바인딩, 델리게이트 시그니처, 포인터 관리 등 언리얼 특유의 함정들을 실제로 밟아 보며 정리할 수 있었고, 이를 통해 프로젝트 전반에서 재사용 가능한 패턴을 쌓을 수 있었다고 생각합니다.

앞으로는 이 구조 위에 퀘스트 시스템 연동, 세이브/로드 시 대화 상태 복원, 로컬라이제이션(다국어 지원) 등을 확장해 나가면서 NPC와의 상호작용 경험을 더욱 풍부하게 만들어 볼 계획입니다.

• NPC와 상호작용 시 대화 UI 위젯을 스택 기반으로 표시/제거
• 대화 노드 트리 기반의 대사 진행, 액션 노드 기반 선택지 버튼 생성
• GameInstanceSubsystem(UCMLocalEventManager) 를 통한 델리게이트 브로드캐스트 구조 정립

대화 데이터 구조 설계 (ACMNpcBase)

• UCMDialoagueNode
  • 부모 노드: ParentNode
  • 자식 노드 배열: TArray<UCMDialoagueNode*> Children
  • 대사 텍스트: FText DialogueText
• UCMActionNode : UCMDialoagueNode
  • 액션 타입: ECMNpcComponentType ActionType
• ACMNpcBase
  • 루트 노드: RootDialogueNode
  • 전체 노드 리스트: AllDialogueNodes
  • 현재 노드: CurrentNode
  • 노드 생성 함수들:
    • CreateDialogueNode(...)
    • CreateDialogueNodeWithSettings(...)
    • CreateActionNodeWithSettings(...)
  • 트리 탐색/디버그
    • LogAllDialogueNodeTexts() 로 전체 노드 로그
    • MoveToChildNodeByIndex(int32 ChildIndex) 로 자식 인덱스 기반 이동

NPC 상호작용 흐름 (ACMNpcBase)

• BeginPlay()
  • NpcComponents 기반으로 UCMNpcComponentBase 파생 컴포넌트 생성 및 등록
  • 1초 후 LogAllDialogueNodeTexts() 실행 (디버그용)
  • 5초 후 PerformInteract() 자동 호출 (테스트용)
• PerformInteract()
  • 현재 구현: StartDialogue() 호출
  • 후속 작업: 필요 시 여기서 UI 생성, 대사 초기화 등 추가
• HandleActionByType(ECMNpcComponentType)
  • 등록된 컴포넌트 맵에서 타입에 해당하는 컴포넌트 찾아 PerformAction() 호출

GameInstanceSubsystem: UCMLocalEventManager

• 역할: NPC ↔ UI 간 로컬 이벤트 허브
• 델리게이트 정의
  • FOnNextDialogueNodeRequested
    • 다음 대화 노드 요청 (예: UI Next 버튼)
  • FOnPrintDialogueNodeText(const FText& DialogueText)
    • 현재 노드 대사 텍스트 브로드캐스트
  • FOnCreateChoiceButton(const FText& DialogueText, ECMNpcComponentType ComponentType)
    • 선택지 버튼 생성 요청 (액션 노드 정보 전달)
  • FOnSelectedDialogueChoice(ECMNpcComponentType ComponentType)
    • 플레이어가 선택지 선택 시 브로드캐스트
• UPROPERTY(BlueprintAssignable) 로 모두 블루프린트에서 바인딩 가능하도록 노출

NPC와 LocalEventManager 연동 (ACMNpcBase)

• StartDialogue()
  • GameInstance에서 UCMLocalEventManager 서브시스템 획득 및 캐싱
  • LocalEventManager->OnNextDialogueNodeRequested.AddDynamic(this, &ACMNpcBase::OnNextDialogueNodeRequested);
• OnNextDialogueNodeRequested() 구현
  • 전제: CurrentNode 가 설정되어 있어야 함
  • 로직:
    1. CurrentNode 가 nullptr 이면 리턴 + 경고 로그
    2. CurrentNode->Children.Num() 이 1이 아닐 경우 이동하지 않고 로그만 출력
    3. 자식이 1개일 때만 CurrentNode 를 그 자식 노드로 변경
    4. 변경된 노드의 DialogueText 를 LocalEventManager->OnPrintDialogueNodeText.Broadcast(...) 로 브로드캐스트
    5. 새 CurrentNode 의 Children 를 순회하면서 UCMActionNode 인 자식을 탐색
       • 각 액션 노드에 대해 OnCreateChoiceButton.Broadcast(ActionNode->DialogueText, ActionNode->ActionType) 호출
• (추가 예정) HandleChoiceSelected(ECMNpcComponentType)
  • FOnSelectedDialogueChoice 를 수신하여 HandleActionByType 와 연동 예정

NPC 대화 UI 위젯 구조 (UCMNpcDialogueWidget)

• 상속: UCMWidgetBase
• 바인딩 프로퍼티
  • FText NpcNameText / NpcNameTextBlock
  • FText DialogueText / DialogueTextBlock
  • UButton* NextButton
  • UVerticalBox* ChoicesContainer
  • TArray<UCMNpcDialogueChoiceElement*> ChoiceWidgets
  • 에디터에서 설정 가능한 선택지 클래스: TSubclassOf<UCMNpcDialogueChoiceElement> ChoiceElementClass
• 주요 함수
  • NativeConstruct()
    • NextButton->OnClicked.AddDynamic(this, &UCMNpcDialogueWidget::OnNextDialogue);
    • ClearChoices() 로 기존 선택지 초기화
  • OnNextDialogue()
    • 내부에서 LocalEventManager의 OnNextDialogueNodeRequested 를 브로드캐스트 하도록 구현 예정 (현재는 TODO 상태로 비워둠)
  • ClearChoices()
    • ChoicesContainer->ClearChildren();
    • ChoiceWidgets.Empty();
  • AddChoice(const FText& InChoiceText, ECMNpcComponentType InComponentType)
    • 사용할 클래스 결정: ChoiceElementClass 가 있으면 그 BP, 없으면 UCMNpcDialogueChoiceElement::StaticClass()
    • CreateWidget 로 인스턴스 생성 후 텍스트 세팅, ChoicesContainer 에 AddChild, ChoiceWidgets 에 보관

선택지 UI 엘리먼트 (UCMNpcDialogueChoiceElement)

• 상속: UCMWidgetBase
• 프로퍼티
  • FText ChoiceText
  • UButton* ChoiceButton
  • UTextBlock* ChoiceTextBlock
• 델리게이트
  • FOnChoiceClicked (BlueprintAssignable)
• 동작
  • NativeConstruct() 에서 ChoiceButton->OnClicked 에 내부 핸들러 바인딩
  • HandleChoiceButtonClicked() → OnChoiceClicked.Broadcast() 호출
  • SetChoiceText(const FText& InText) 로 내부 텍스트와 TextBlock 동기화

델리게이트 연결 요약

• UCMLocalEventManager
  • OnNextDialogueNodeRequested
    • (UI → NPC) Next 버튼으로 다음 노드 요청
  • OnPrintDialogueNodeText
    • (NPC → UI) 현재 대사 텍스트 전달
  • OnCreateChoiceButton
    • (NPC → UI) 선택지 버튼 정보 전달
  • OnSelectedDialogueChoice
    • (UI → NPC) 플레이어가 선택한 액션 타입 전달
• 현재 상태
  • NPC 쪽: StartDialogue() 에서 OnNextDialogueNodeRequested 에 바인딩, OnNextDialogueNodeRequested() 구현 완료
  • UI 쪽: NextButton → OnNextDialogue() → LocalEventManager 브로드캐스트 부분은 TODO
  • 선택지 클릭 → OnSelectedDialogueChoice 브로드캐스트, NPC의 HandleChoiceSelected 에서 처리하는 구조는 설계만 완료

요약

• UE5에서 GameInstanceSubsystem(UCMLocalEventManager) 를 사용해 NPC와 UI 사이의 대화 이벤트를 느슨하게 연결하는 패턴을 정리했다.
• NPC 하나가 대화 트리(UCMDialoagueNode/UCMActionNode)를 소유하고, LocalEventManager 델리게이트를 통해 다음 노드 이동, 대사 텍스트 브로드캐스트, 선택지 생성까지 책임지도록 설계했다.
• UI는 PlayerController 가 가진 UUIManagerComponent 의 스택을 통해 관리하며, 대화 위젯을 푸시/팝하는 방식으로 게임 입력 모드와도 자연스럽게 연동했다.
• 아직 남은 TODO는 Next 버튼에서 OnNextDialogueNodeRequested 브로드캐스트, 선택지 클릭 → OnSelectedDialogueChoice 브로드캐스트 → NPC HandleActionByType 연동 이며, 이 부분을 다음 단계에서 마무리할 예정.

전체 구조 개요

• 핵심 타입

  • ECMNpcComponentType : NPC 컴포넌트의 종류를 표현하는 enum
  • UCMDialoagueNode : 기본 대화 노드(텍스트, 부모/자식 참조 포함)
  • UCMActionNode : 기본 노드를 상속받아, 추가로 액션 타입을 가지는 노드
  • ACMNpcBase : NPC 액터, 대화 트리 전체를 소유/관리
  • UCMNpcComponentBase : NPC용 공통 컴포넌트 베이스
  • UCMNpcShopComponent : 예시용 상점 컴포넌트(PerformAction 시 화면 메시지 출력)

• 설계 포인트

  • 대화 노드는 UObject(UCLASS) 로 구현 → GC 및 블루프린트 호환성 확보
  • 트리 구조는 ParentNode + Children 배열로 표현
  • NPC 액터(ACMNpcBase)가
    • RootDialogueNode (루트 노드)
    • AllDialogueNodes (생성된 모든 노드) 를 UPROPERTY로 보유 → GC에 안전하고, 순회/디버그에 용이
  • 액션 노드는 별도 타입(UCMActionNode)으로 구분
    • ActionType: ECMNpcComponentType
    • 트리 순회 중 액션 노드를 만나면 HandleActionByType 호출

ECMNpcComponentType: 블루프린트에서 쓰는 컴포넌트 타입 enum

UENUM(BlueprintType)
enum class ECMNpcComponentType: uint8
{
    Default UMETA(DisplayName = "Default"),
    DialogueComponent UMETA(DisplayName = "Dialogue Component"),
    QuestComponent UMETA(DisplayName = "Quest Component"),
    ShopComponent UMETA(DisplayName = "Shop Component"),
};

• 역할
  • NPC에 붙는 컴포넌트의 종류(대화, 퀘스트, 상점 등)를 식별하기 위한 enum
  • ACMNpcBase의 RegisteredComponentMap 키로 사용
  • UCMActionNode의 ActionType에도 사용 → 트리 상에서 어느 컴포넌트를 실행할지 지정

• 선언 방식
  • 언리얼 리플렉션 + 블루프린트 노출을 위해 UENUM(BlueprintType) 사용
  • 기본형은 int (언더라이잉 타입 명시 생략)으로 유지

UCMDialoagueNode: 기본 대화 노드 설계

• 타입
  • UCLASS(BlueprintType) class UCMDialoagueNode : public UObject

UCLASS(BlueprintType)
class UCMDialoagueNode : public UObject
{
    GENERATED_BODY()

public:
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Dialogue")
    TObjectPtr<UCMDialoagueNode> ParentNode = nullptr;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Dialogue")
    TArray<TObjectPtr<UCMDialoagueNode>> Children;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Dialogue")
    FText DialogueText;
};

• 주요 필드

  • ParentNode : UCMDialoagueNode*
    • UPROPERTY(VisibleAnywhere, BlueprintReadOnly)
    • 상위 노드 참조 (루트의 경우 nullptr)
  • Children : TArray<UCMDialoagueNode*>
    • UPROPERTY(EditAnywhere, BlueprintReadWrite)
    • 자식 노드들(다중 분기 지원)
  • DialogueText : FText
    • UPROPERTY(EditAnywhere, BlueprintReadWrite)
    • 실제로 화면/UI에 보여줄 대사 텍스트

• 특징

  • UObject 기반이라 언리얼 GC 관리 대상
  • 블루프린트에서
    • 노드의 텍스트를 수정
    • Parent/Children를 직접 연결하여 트리 구성 가능

UCMActionNode: 액션을 수행하는 특수 대화 노드

• 타입
  • UCLASS(BlueprintType) class UCMActionNode : public UCMDialoagueNode

UCLASS(BlueprintType)
class UCMActionNode : public UCMDialoagueNode
{
    GENERATED_BODY()

public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Dialogue")
    ECMNpcComponentType ActionType;
};

• 추가 필드

  • ActionType : ECMNpcComponentType
    • UPROPERTY(EditAnywhere, BlueprintReadWrite)
    • 이 노드에 도달했을 때 어떤 타입의 NPC 컴포넌트를 실행할지 지정

• 동작

  • 트리 순회 중 UCMActionNode로 캐스팅에 성공하면
    • ActionType 값을 읽어
    • ACMNpcBase::HandleActionByType(ActionType) 호출
  • 예: ShopComponent → 상점 열기 컴포넌트의 PerformAction 호출

ACMNpcBase: NPC 액터와 대화 트리 관리

• 타입

  • class ACMNpcBase : public AActor, public ICMNpcHandler

• 주요 프로퍼티

  • RootDialogueNode : UCMDialoagueNode*
    • 대화 트리의 루트 노드
  • AllDialogueNodes : TArray<UCMDialoagueNode*>
    • 생성된 모든 대화 노드 모음 (GC + 디버그용)
  • CurrentNode : UCMDialoagueNode*
    • 런타임에 현재 플레이어가 위치한 노드(향후 사용 예정)
  • NpcComponents : TArray<TSubclassOf<UCMNpcComponentBase>>
    • 에디터에서 지정하는 NPC용 컴포넌트 클래스 목록
  • ActiveNpcComponents : TArray<UCMNpcComponentBase*>
    • BeginPlay에서 실제 인스턴스로 생성 후 보관
  • RegisteredComponentMap : TMap<ECMNpcComponentType, UCMNpcComponentBase*>
    • 각 컴포넌트 타입에 해당하는 인스턴스를 등록/맵핑

• BeginPlay 흐름

  • RegisteredComponentMap.Empty() : 초기화
  • NpcComponents를 순회하며
    • NewObject<UCMNpcComponentBase>(this, ComponentClass) 로 생성
    • RegisterComponent() 호출 → 언리얼 라이프사이클에 등록
    • ActiveNpcComponents에 추가
  • 생성된 각 컴포넌트는 자기 BeginPlay에서
    • 핸들러(ACMNpcBase)에 RegisterComponent를 호출하여 스스로 등록
  • 마지막에 테스트용:
    • FTimerHandle을 사용해 BeginPlay + 1초 후 LogAllDialogueNodeTexts() 실행

노드 생성 함수 설계 (ACMNpcBase)

CreateDialogueNode

• 시그니처

  • UCMDialoagueNode* CreateDialogueNode(TSubclassOf<UCMDialoagueNode> NodeClass, const FText& InDialogueText);

• 역할

  • 특정 NodeClass (기본은 UCMDialoagueNode)로 새 노드를 생성하고 텍스트 설정
  • AllDialogueNodes 배열에 추가
  • 첫 번째 생성 노드는 자동으로 RootDialogueNode로 설정

• 동작 요약

  • if (!*NodeClass) NodeClass = UCMDialoagueNode::StaticClass();
  • NewObject<UCMDialoagueNode>(this, NodeClass)
  • NewNode->DialogueText = InDialogueText;
  • AllDialogueNodes.Add(NewNode);
  • RootDialogueNode가 비어 있으면 첫 노드를 루트로 등록

CreateDialogueNodeWithSettings

• 시그니처

  • UCMDialoagueNode* CreateDialogueNodeWithSettings(TSubclassOf<UCMDialoagueNode> NodeClass, UCMDialoagueNode* Parent, const FText& InDialogueText);

• 역할

  • CreateDialogueNode를 호출해 노드를 생성하고
  • 부모/자식 관계를 동시에 설정하는 편의 함수

• 연결 로직

  • NewNode->ParentNode = Parent;
  • Parent->Children.Add(NewNode);

CreateActionNodeWithSettings

• 시그니처

  • UCMDialoagueNode* CreateActionNodeWithSettings(TSubclassOf<UCMActionNode> NodeClass, UCMDialoagueNode* Parent, const FText& InDialogueText, ECMNpcComponentType InActionType);

• 역할

  • UCMActionNode 타입으로 노드를 생성
  • DialogueText + ActionType + 부모/자식 관계를 한 번에 설정

• 동작 요약

  • if (!*NodeClass) NodeClass = UCMActionNode::StaticClass();
  • NewObject<UCMActionNode>(this, NodeClass) 로 액션 노드 생성
  • NewNode->DialogueText = InDialogueText;
  • NewNode->ActionType = InActionType;
  • Parent가 있으면
    • NewNode->ParentNode = Parent;
    • Parent->Children.Add(NewNode);

• 블루프린트 사용성

  • InActionType가 ECMNpcComponentType 이라 BP 노드에서 드롭다운으로 선택 가능
  • BP에서 함수를 배치할 때, 트리 상에 어떤 액션을 둘지 직관적으로 설정 가능

블루프린트에서의 사용 패턴

• 기본 대화 노드 생성

  • CreateDialogueNode(UCMDialoagueNode, "대사 텍스트")
  • 또는 CreateDialogueNodeWithSettings(UCMDialoagueNode, ParentNode, "텍스트")

• 액션 노드 생성

  • CreateActionNodeWithSettings(UCMActionNode, ParentNode, "텍스트", ECMNpcComponentType::ShopComponent)
  • 분기 지점에 여러 액션 노드를 붙여서 다양한 상호작용 표현

• 트리 테스트
  • NPC 스폰 → BeginPlay 후 1초 뒤
  • LogAllDialogueNodeTexts() 자동 호출
  • Output Log에서
    • 각 노드 텍스트
    • 어떤 액션 타입이 처리되었는지 로그
  • 화면(OnScreenDebug)에서는 상점 액션 등 실제 PerformAction의 효과 확인 가능

결론

이번 NPC Dialogue 시스템 구현에서는 단순한 대사 나열을 넘어서, 트리 구조와 액션 노드를 결합한 대화 흐름을 구축해 보았습니다. 대화 노드를 UObject로 분리하고, NPC 액터가 트리 전체를 관리하도록 설계함으로써 재사용성과 확장성을 높이고자 하였습니다. 또한, 블루프린트에서 노드를 생성하고 텍스트/액션 타입을 직관적으로 지정할 수 있도록 API를 정리한 덕분에, 디자이너 입장에서의 사용성도 어느 정도 확보할 수 있었습니다.

앞으로는 이 구조를 기반으로 실제 게임 플레이에 필요한 UI 연동, 선택지 표시, 조건부 분기(퀘스트 진행도, 인벤토리 상태 등)에 따른 동적 트리 탐색 등을 추가해 볼 예정입니다. 이번 작업을 통해 언리얼 엔진의 UObject/Actor/Component 구조와 블루프린트 연동 방식에 대한 이해를 한층 더 깊게 할 수 있었던 의미 있는 경험이었습니다.

먼저 일반적으로 알려진 메모리 구조는 다음과 같습니다.

주소 ↑

하지만 VMMap에서의 구성은 다음과 같았습니다.

여기서 알게 된 점은 Image가 우리가 알고 있던 Code가 저장되는 영역이라는 점입니다. 실제로 더미코드를 아주 많이 추가했을 때 아래와 같은 차이점을 보였습니다.

도움이 되는 유틸리티를 사용할 때, 사용되는 키워드의 차이점을 인지해야 효율적으로 사용할 수 있겠습니다.

심볼(Symbol)이란?

심볼은 컴파일러·링커가 프로그램 내부 엔티티를 식별하기 위해 생성하는 이름 정보입니다. 즉, 우리가 작성한 C++ 코드를 기계어가 이해할 수 있도록 내부적으로 사용하는 식별자입니다.

C++에서 심볼이 만들어지는 대상은 다음과 같습니다.

• 함수
• 전역 변수
• static 변수
• 클래스 멤버 함수
• 템플릿 인스턴스
• 가상 함수 테이블(vtable)

심볼은 실제 바이너리 내부에 기록되며, 링커가 여러 개의 obj 파일을 연결할 때 이 정보를 사용합니다.

C++ 심볼의 실제 형태 (Name Mangling)

C++ 함수는 오버로딩, 네임스페이스, 클래스 등 구조가 복잡해서 컴파일하면 내부적으로 이름이 변형됩니다. 이를 네임 맹글링(Name Mangling) 이라고 합니다.

예를 들어:

int Add(int a, int b);

이 함수는 컴파일 후 다음과 같은 이름으로 변환될 수 있습니다.

?Add@@YAHHH@Z

이런 형태의 이름이 바로 심볼(Symbol) 입니다.

3. 심볼과 링키지(Linkage)

심볼에는 "어디까지 보이는가?" 를 나타내는 링키지(Linkage) 개념이 붙습니다.

✔ External Linkage

다른 파일에서도 접근 가능한 심볼 (기본적인 전역 함수/전역 변수)

int gValue;
void Foo();

✔ Internal Linkage

파일 내부에서만 보이는 심볼 static 키워드로 생성됩니다.

static int localGlobal = 10;

✔ No Linkage

지역 변수처럼 링커가 관여하지 않는 경우, 심볼 테이블에 올라가지 않음

Undefined Symbol (미정의 심볼)

C++ 컴파일 시 선언만 있고 정의가 없는 심볼은 링커가 처리해야 합니다.

예:

extern int Value;

Value의 정의가 없다면 링크 단계에서 오류가 발생합니다.

undefined reference to `Value`

즉, 심볼은 선언 → 참조 → 정의가 일치해야 linking이 성공합니다.

Symbol Table (심볼 테이블)

컴파일러와 링커는 심볼 정보를 다음과 같이 테이블로 관리합니다

• 변수 이름, 타입, 메모리 위치
• 함수의 주소
• 템플릿 인스턴스 정보
• 가상 함수 테이블 정보
• 접근 범위 및 링크 여부

.obj 파일을 열면 심볼 테이블을 확인할 수 있습니다.

실제 심볼 테이블을 확인해보기 위해 DUMPBIN을 사용해보겠습니다.

VS2022의 터미널에서 실행했습니다.

obj 파일에서 심볼 테이블을 확인할 수 있었습니다.

왜 중요한가?

심볼은 다음 문제들의 핵심 원인/해결책이 됩니다.

• 함수 중복 정의 오류
• undefined reference 링크 오류
• static 전역과 일반 전역 변수 차이
• 템플릿 인스턴스 중복 생성 문제
• vtable 관련 링크 에러

즉, C++ 빌드 과정에서 발생하는 대부분의 문제는 결국 심볼에 대한 이해로 해결됩니다.

핵심 요약

• 심볼은 C++ 코드의 컴파일·링크 과정에서 생성되는 내부 이름
• C++은 오버로딩 때문에 Name Mangling이 적용된다.
• 심볼에는 External / Internal / No Linkage가 있다.
• 정의되지 않은 심볼은 링크 에러를 만든다.
• obj 파일 내부의 모든 정보는 Symbol Table에 기록되어 있다.

설계 목표

• 컴포넌트 기반 NPC 확장 구조 설계
  • 공통된 NPC 베이스 클래스: ACMNpcBase
  • 기능 단위의 컴포넌트: UCMNpcComponentBase 파생 클래스들
• 기능별 책임 분리
  • 대화(Dialogue), 퀘스트(Quest), 상점(Shop) 기능을 각각 독립된 컴포넌트로 관리
• 타입 기반 액션 처리
  • ECMNpcComponentType + HandleActionByType() 조합으로 컴포넌트 접근
• 향후 기능 추가에 대비한 확장성
  • 새로운 NPC 기능을 추가할 때 기존 코드 수정을 최소화

핵심 클래스 및 인터페이스 구조

• ACMNpcBase : AActor, ICMNpcHandler
  • NPC의 공통 베이스 액터
  • ICMNpcHandler 인터페이스를 구현하여 외부에서 통합된 방식으로 NPC에 요청 전달
• ICMNpcHandler
  • NPC가 공통으로 가져야 할 행동 인터페이스 정의
  • 예: HandleActionByType(ECMNpcComponentType ComponentType)
• UCMNpcComponentBase
  • NPC 기능용 베이스 컴포넌트 클래스
  • Dialogue / Quest / Shop 등 기능 컴포넌트의 부모 타입
• ECMNpcComponentType
  • NPC 컴포넌트 타입 식별용 enum
  • Default, DialogueComponent, QuestComponent, ShopComponent 등 정의

클래스 다이어그램

ACMNpcBase의 역할 및 책임 정리

• NPC 공통 Actor 베이스
  • 카메라 컴포넌트: NpcCameraComponent
  • 캡슐 콜라이더: CapsuleComponent
  • 스켈레탈 메시: MeshComponent
• NPC 기능 컴포넌트 관리
  • NpcComponents 배열로 부착된 컴포넌트들을 보관
  • RegisteredComponentMap<ECMNpcComponentType, UCMNpcComponentBase*>로 타입-컴포넌트 매핑
• 컴포넌트 등록 로직
  • RegisterComponent(ECMNpcComponentType ComponentType, UCMNpcComponentBase* NewComponent)
    • 외부/컴포넌트에서 자기 자신을 등록하는 공용 인터페이스
  • PerformRegisterComponent(...)
    • 중복 등록 체크, 맵 갱신 등 실제 등록 로직 처리
• 상호작용 처리
  • PerformInteract()
    • 플레이어가 NPC와 상호작용할 때 호출되는 Entry Point
    • 적절한 ECMNpcComponentType를 결정 후 HandleActionByType() 호출 가능

ICMNpcHandler 인터페이스 활용

• 공통 액션 처리 진입점 제공
  • HandleActionByType(ECMNpcComponentType ComponentType)
    • 컴포넌트 타입 기반으로 적절한 NPC 컴포넌트를 찾아 액션 실행
• 컴포넌트 등록 책임의 일원화
  • RegisterComponent(ECMNpcComponentType ComponentType, UCMNpcComponentBase* NewComponent)
    • NPC 베이스에서만 타입-컴포넌트 매핑을 관리하도록 강제
• 장점
  • 외부에서 NPC의 내부 구조(어떤 컴포넌트가 있는지)를 몰라도, enum 타입과 핸들러 메서드만으로 행동 요청 가능
  • 추후 새로운 컴포넌트 타입이 추가되어도, 인터페이스 시그니처는 유지되므로 기존 호출부 영향 최소화

컴포넌트 기반 확장성 (Dialogue / Quest / Shop)

• 컴포넌트 유형 정의
  • ECMNpcComponentType::DialogueComponent
  • ECMNpcComponentType::QuestComponent
  • ECMNpcComponentType::ShopComponent
• 각 기능의 책임 분리
  • Dialogue 컴포넌트
    • NPC 대사를 관리하고, 트리 기반 대화 흐름 제어
  • Quest 컴포넌트
    • 퀘스트 제공, 진행 상태 관리, 완료 조건 체크
  • Shop 컴포넌트
    • 상점 인벤토리, 구매/판매 로직 관리
• 확장성 포인트
  • 새로운 기능(예: ECMNpcComponentType::TrainingComponent, CraftComponent 등)을 추가할 때
    • enum에 타입만 추가
    • 해당 타입을 담당하는 UCMNpcComponentBase 파생 컴포넌트 생성
    • RegisterComponent()를 통해 ACMNpcBase에 등록
  • 기존 HandleActionByType() 호출 구조는 그대로 유지
• 유지보수성 향상 요소
  • 기능 단위로 클래스가 나뉘어 있어, 버그 수정 또는 기능 변경 시 해당 컴포넌트에만 집중 가능
  • 공통 인터페이스(ICMNpcHandler, UCMNpcComponentBase)를 통해 일관된 사용법 제공

8. HandleActionByType() 기반 액션 라우팅

• 목적
  • 외부 코드(플레이어 상호작용, 트리거, UI 등)에서 NPC에게 특정 기능을 요청할 때, 컴포넌트를 직접 참조하지 않고 타입 기반으로 접근
• 처리 흐름
  • 입력: ECMNpcComponentType ComponentType
  • RegisteredComponentMap에서 해당 타입의 컴포넌트 조회
  • 컴포넌트가 존재하면 UCMNpcComponentBase::HandleAction() (또는 유사 메서드) 호출
• 장점
  • NPC 내부 구조 변경(컴포넌트 교체, 리팩토링)에도 외부 인터페이스 유지
  • 다양한 상호작용(예: 대화 / 퀘스트 수락 / 상점 열기)을 타입 하나로 추상화 가능

트리형 Dialogue 설계와 HandleActionByType() 연계

• 트리형 Dialogue 구조 계획
  • 노드 기반 대화 구조
    • 각 노드는 대사 내용, 선택지, 다음 노드에 대한 참조를 가짐
  • 플레이어 선택에 따라 다른 노드로 분기하는 트리(또는 DAG) 형태
• Dialogue 컴포넌트 역할
  • 내부에 대화 트리 데이터 구조 보관
  • StartDialogue(), ProceedToNextNode(ChoiceIndex), EndDialogue() 등의 메서드 제공
  • HandleAction()에서 초기 진입점(StartDialogue()) 호출
• HandleActionByType() 활용 시나리오
  • 플레이어가 NPC와 상호작용 → ACMNpcBase::PerformInteract() 호출
  • 현재 상황(퀘스트 단계, 게임 모드 등)에 따라 아래 중 하나를 선택
    • HandleActionByType(ECMNpcComponentType::DialogueComponent)
    • HandleActionByType(ECMNpcComponentType::QuestComponent)
    • HandleActionByType(ECMNpcComponentType::ShopComponent)
  • Dialogue 선택 시
    • 등록된 Dialogue 컴포넌트를 조회 → 대화 트리의 루트 노드에서 대화 시작
• 확장 시 이점
  • 트리 구조나 대화 데이터 포맷이 바뀌더라도 HandleActionByType(DialogueComponent) 호출부는 변경 없이 유지 가능
  • 대화 로직 복잡도가 커져도, NPC 베이스/외부 호출부와 분리되어 유지보수 부담 감소

마치며

이번 NPC 설계에서는 Actor + Interface + Component + Enum을 조합하여, NPC의 다양한 기능을 느슨하게 결합된 형태로 구성해 보았습니다. 특히 HandleActionByType()과 ECMNpcComponentType을 활용하여 컴포넌트에 접근하는 방식은, 이후 Dialogue, Quest, Shop 컴포넌트가 추가되더라도 외부 인터페이스를 거의 건드리지 않고 확장이 가능하다는 장점이 있었습니다.

앞으로는 실제 트리형 Dialogue 데이터를 설계하고, 이를 처리하는 Dialogue 컴포넌트를 구현하면서, 이번에 정의한 NPC 베이스 구조가 얼마나 유연하게 동작하는지 검증해 볼 예정입니다. 이를 통해 상호작용이 복잡해지는 RPG 스타일 게임에서도 유지보수성과 확장성을 동시에 확보하는 NPC 아키텍처를 완성하는 것을 목표로 삼겠습니다.

이 글에서는 문제를 해결하기까지의 시행착오 과정을 정리하여, 비슷한 이슈를 겪는 분들께 참고가 될 만한 내용을 공유드리고자 합니다.

1.1 문제 상황 요약

• Steam 초대 수락 후 JoinSession 까지는 성공 로그가 뜸
• 하지만 실제로는 호스트에 접속되지 않고, 일정 시간이 지난 후 타임아웃
• 클라이언트 로그 상 주요 현상:
  • OnSessionUserInviteAccepted 성공
  • JoinSession 성공
  • Browse: steam.7656.../Game/Maps/MainMenu 까지 진행
  • 이후 Your connection to the host has been lost. 로 실패

1.2 최초 에러: NetworkDriver 생성 실패

• 로그 예시

Failed to find object 'Class /Script/Engine.IpNetDriver'
CreateNamedNetDriver failed to create driver from definition GameNetDriver
Error initializing the pending net driver. Check the configuration of NetDriverDefinitions...

• 원인 추정
  • DefaultEngine.ini 에서 GameNetDriver 설정이 제대로 되어 있지 않아서, 엔진이 NetDriver 클래스를 찾지 못함

1.2.1 NetDriver 설정 수정

• DefaultEngine.ini 에 다음과 같이 설정
  • [/Script/Engine.GameEngine]
  • !NetDriverDefinitions=ClearArray
  • NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/OnlineSubsystemSteam.SteamNetDriver",DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver")
• 효과
  • 이후 로그에서 InitBase PendingNetDriver (NetDriverDefinition GameNetDriver) 로 정상 초기화되는 것을 확인
  • 더 이상 IpNetDriver 클래스를 못 찾는 에러는 발생하지 않음

1.3 두 번째 문제: P2P 연결 타임아웃

• 수정 후 클라이언트 로그
  • InitBase PendingNetDriver (NetDriverDefinition GameNetDriver)
  • Game client on port 7777, rate 100000
  • 잠시 대기 후
  • Timed out attempting to connect
  • Your connection to the host has been lost.
• 특징
  • 세션 검색, 초대, JoinSession 까지는 모두 정상 동작
  • 실제 P2P 연결 수립 단계에서 일정 시간 후 타임아웃 발생

1.4 Listen 서버 생성 실패 로그 분석

• 호스트 쪽 로그에서 다음 메시지 확인
  • LoadMap: failed to Listen(/Game/MainStage/L_GenerateMapTest?Name=Player?listen)
• 다른 시점에는
  • LoadMap: failed to Listen(/Game/Maps/MainMenu?Name=Player?listen)
• 의미
  • 호스트가 맵을 로드하면서 ?listen 옵션으로 Listen 서버를 열려고 시도했으나 실패
  • 즉, 클라이언트 문제 이전에 호스트가 제대로 Listen 서버를 띄우지 못함

1.4.1 세션 생성과 Travel 순서

• 초기 구현
  • OnCreateSessionComplete() 안에서 바로 ServerTravel + ?listen 수행
  • 또는 세션 생성 직후 약간의 딜레이를 준 뒤 ServerTravel 호출
• 문제점
  • 세션 생성 직후 엔진/Steam 쪽 초기화가 완전히 끝나지 않은 상태에서 ServerTravel 을 수행하면 Listen 서버 생성이 실패할 수 있음
  • 다만 이 경우에는 궁극적인 원인은 아니었음 (딜레이를 줘도 근본 문제가 남아 있었음)

1.4.2 기능 분리

• 조치 사항
  • "Online Session 생성" 과 "ServerTravel(맵 이동 + ?listen)" 을 별도의 함수로 분리
  • 세션 생성 성공 콜백에서는 세션 관련 처리만 담당
  • 맵 이동은 명시적으로 별도 타이밍에 호출하도록 구조 개선
• 의도
  • 디버깅 편의성 향상
  • 세션/네트 워킹 문제와 레벨 로딩/게임 로직을 명확하게 분리

1.5 게임 타겟 vs 클라이언트 타겟

• 핵심 원인
  • 프로젝트를 Client 타겟(CrimsonMoonClient) 으로 빌드하고 실행하고 있었음
  • Client 타겟은 기본적으로 Listen 서버를 열 수 없는 구성
• 결과적으로
  • 호스트를 Client 타겟 실행 파일로 실행 → ?listen 으로 서버를 열려고 해도 계속 실패
  • 따라서 클라이언트 입장에서는 P2P 연결을 시도하나, 실제로는 열려 있는 Listen 서버가 없어서 결국 타임아웃 발생

1.5.1 해결책: Game 타겟으로 빌드

• 빌드 대상 변경

  • 기존: CrimsonMoonClient.Target.cs 기반 빌드 (클라이언트 전용)
  • 변경: CrimsonMoon.Target.cs 기반 Game 타겟 빌드

• 변경 후 현상

  • 호스트가 ?listen 으로 정상적으로 Listen 서버를 생성
  • 클라이언트에서 Steam 초대 수락 → JoinSession → Browse steam.xxx/Map → 정상 접속
  • 실제로 친구 초대 후 함께 플레이 가능한 상태 확인

  

1.6 정리: 왜 Client 타겟으로는 안 되었는가

• Client 타겟의 특징 (언리얼 빌드 관점 가정)
  • 전용 클라이언트 실행용, 서버 관련 일부 기능이 비활성화/제한될 수 있음
  • Listen 서버(클라이언트 + 서버 겸용)를 여는 패턴에는 적합하지 않음
• Listen 서버 패턴
  • 한 플레이어가 호스트이자 클라이언트 역할을 하면서 ?listen 으로 서버를 열고, 나머지는 그 호스트에 접속하는 구조
  • 이 패턴은 Game 타겟(또는 Editor)에서 실행해야 정상 동작

2. 배운 점 정리 (TIL)

2.1 Steam + UE5 멀티플레이 기본 흐름

• 세션 생성
  • Steam Online Subsystem 이용
  • CreateSession → OnCreateSessionComplete 콜백 확인
• 호스트 측 레벨 이동
  • Listen 서버를 사용할 경우: /Game/Map/YourMap?listen 으로 ServerTravel
• 클라이언트 초대 및 Join
  • Steam 초대 → OnSessionUserInviteAccepted 콜백
  • JoinSession 호출, 성공 시 GetResolvedConnectString 으로 주소 획득
  • ClientTravel 로 steam.XXX/Map 주소로 이동

2.2 설정/코드 레벨에서의 체크리스트

• DefaultEngine.ini
  • [/Script/Engine.GameEngine]
  • !NetDriverDefinitions=ClearArray
  • NetDriverDefinitions=(DefName="GameNetDriver", DriverClassName="/Script/OnlineSubsystemSteam.SteamNetDriver", DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver")
• 세션 생성과 맵 이동 분리
  • 세션 생성 전용 함수
  • Listen 서버용 ServerTravel 전용 함수
• Host 빌드 타겟
  • 반드시 Game 타겟(CrimsonMoon.exe) 로 빌드/실행
  • Client 전용 타겟(CrimsonMoonClient.exe)으로는 Listen 서버를 열 수 없음

2.3 로그를 볼 때 집중해서 봐야 하는 포인트

• NetDriver 관련
  • CreateNamedNetDriver failed to create driver from definition GameNetDriver
  • Failed to find object 'Class /Script/Engine.IpNetDriver'
• Listen 서버 관련
  • LoadMap: failed to Listen( ... ?listen)
• 연결 실패 관련
  • Timed out attempting to connect
  • Your connection to the host has been lost.
• Steam Sockets 관련 경고
  • Relay candidates enabled by P2P_Transport_ICE_Enable, but P2P_TURN_ServerList is empty
  • 단순 경고일 수 있으며, 치명적인 에러는 아닐 수 있음 → 진짜 실패 원인은 NetDriver/Listen 쪽에 있을 가능성이 높음

2.4 앞으로 비슷한 기능을 구현할 때 주의할 점

• 먼저 호스트가 제대로 Listen 서버를 뜨는지 단독 실행으로 확인
• 클라이언트/게임 타겟, 서버 타겟 빌드 설정을 명확하게 구분
• Online Subsystem 설정(DefaultEngine.ini) 과 NetDriver 설정을 초기 단계에서 정확히 맞춰둘 것
• 세션 로직과 게임 레벨 로딩/게임플레이 초기화 로직을 분리해서 디버깅 가능하게 설계

결론

이번 구현의 핵심은 코드나 Steam API 사용법 자체의 문제라기보다는, 빌드 타겟 선택(Game vs Client) 과 엔진 설정(NetDriver, Listen 서버 가능 여부) 이었습니다. 언리얼 멀티플레이를 Steam과 연동해서 구현할 때는, 에디터에서 잘 되던 것이 패키징 후 동작하지 않을 수 있으므로, 어떤 타겟으로 빌드하고 실행하는지부터 확실히 인지하는 것이 중요하다는 점을 다시 한 번 느꼈습니다.

이 TIL이 이후에 비슷한 문제를 겪을 때 빠르게 원인을 좁히는 데 도움이 되기를 바랍니다.

이번 글에서는 ACMProcedualMapGenerator + UCMMapGenerateLogicBaseComponent + ACMRoom 조합으로 작성된 맵 생성 로직에서 어떤 문제가 있었고, 이를 어떻게 디버깅하고 정리했는지 트러블슈팅 과정을 정리합니다.

1. 상황 정리

1.1. 관련 클래스 구조

• ACMProcedualMapGenerator

  • 맵 전체를 생성하는 Actor
  • GenerateMap(int32 InSeed, UCMRoomDataDefinition* InMapData) 에서 맵 생성 컴포넌트들을 동적으로 생성/교체
  • MapGenerateLogicComponent : UCMMapGenerateLogicBaseComponent 기반
  • SpawnPositionSelectorComponent : 스폰 위치 선택 담당
  • 결과를 TMap<FCMRoomPosition, TObjectPtr<ACMRoom>> RoomMap 에 저장

• UCMMapGenerateLogicBaseComponent

  • 실제 방 배치, 연결, 보스/보물 방 결정 등 맵 생성 알고리즘 구현
  • 주요 함수
    • ExecuteMapGenerationLogic : 전체 생성 파이프라인
    • GenerateRoom : 좌표 기반 그래프 생성 및 ACMRoom 스폰
    • PlaceWallsAndEntrances : 각 방 주변에 Entrance/Wall 스폰

• ACMRoom

  • 한 개의 방을 나타내는 Actor
  • RoomBoundsBox, 4방향 Entrance 포인트, Entrance/Wall 클래스를 보유
  • ExcuteSpawnRoom(int32 DirectionIndex, bool bIsEntrance) 에서 실제로 Entrance/Wall Actor 스폰

1.2. 문제가 된 코드 (요약)

void UCMMapGenerateLogicBaseComponent::PlaceWallsAndEntrances(TMap<FCMRoomPosition, TObjectPtr<ACMRoom>>& OutRoomMap)
{
    ENetMode NetMode = GetWorld() ? GetWorld()->GetNetMode() : NM_Standalone;
    for (const TPair<FCMRoomPosition, TObjectPtr<ACMRoom>>& Pair : OutRoomMap)
    {
        if (ACMRoom* Room = Pair.Value.Get())
        {
            for (int32 i = 0; i < 4; ++i)
            {
                FCMRoomPosition CurrentPos(Pair.Key.X + DirectionX[i], Pair.Key.Y + DirectionY[i]);
                if (OutRoomMap.Contains(CurrentPos))
                {
                    if (NetMode != NM_Client)
                    {
                        UE_LOG(LogTemp, Log, TEXT("HasAuthority: %d, NetMode: %d"),
                            GetOwner()->HasAuthority(),
                            static_cast<int32>(NetMode));
                        Room->ExcuteSpawnRoom(i, true); // Entrance
                    }
                }
                else
                {
                    Room->ExcuteSpawnRoom(i, false); // Wall
                }
            }
        }
    }
}

1.3. 증상

• bReplicates 를 블루프린트에서 켜지 않았는데도, 클라이언트에서 방/Entrance/Wall 이 모두 보임
• GetOwner()->HasAuthority() 로 조건을 걸어도, 여전히 호스트와 클라이언트 양쪽에서 Entrance/Wall 이 각각 생성됨
• 로그 상으로는 HasAuthority: 1 이 서버와 클라이언트 양쪽에서 모두 찍히는 듯한 결과

2. 개념 정리: HasAuthority, NetMode, 복제 유무

2.1. HasAuthority()

• AActor::HasAuthority() 는 내부적으로 Role == ROLE_Authority 를 의미
• 복제된 Actor 의 경우
  • 서버에 있는 인스턴스: HasAuthority() == true
  • 클라에 있는 인스턴스: HasAuthority() == false
• 하지만 비복제 Actor 의 경우
  • 서버에서 스폰된 인스턴스: HasAuthority() == true
  • 클라에서 별도로 스폰된 인스턴스: 여기도 그 월드에서 유일한 Actor 라서 Role = ROLE_Authority → HasAuthority() == true
• 따라서, "HasAuthority 가 true면 서버"라고 단정하면 안 됨

2.2. NetMode

• UWorld::GetNetMode() 로 현재 월드의 네트워크 모드를 알 수 있음
  • NM_Standalone (0) : 싱글 플레이
  • NM_DedicatedServer (1) : 디디케이티드 서버
  • NM_ListenServer (2) : 리슨 서버(호스트)
  • NM_Client (3) : 클라이언트
• "이 코드가 서버에서 실행 중인가?" 를 알고 싶다면:
  • World->GetNetMode() == NM_Client 이면 클라이언트 → 서버 전용 로직은 실행하지 않도록 Early Return
  • 또는 World->GetNetMode() != NM_Client 을 서버/호스트 쪽으로 간주해도 됨

3. 실제 원인 분석

3.1. MapGenerator 가 서버/클라에 각각 존재

• ACMProcedualMapGenerator 는 단순 AActor 이고, bReplicates 세팅이나 서버 전용 제약 없이 월드에 배치/생성되어 있었음
• 리슨 서버 + 클라이언트 환경에서
  • 서버 월드에 ACMProcedualMapGenerator 한 개
  • 클라이언트 월드에도 ACMProcedualMapGenerator 한 개
  • 둘 다 자기 월드에서 유일한 존재 → 둘 다 HasAuthority() == true
• GenerateMap() 호출 또한 서버/클라 각각에서 트리거되는 구조였기 때문에,
  • UCMMapGenerateLogicBaseComponent::ExecuteMapGenerationLogic
  • UCMMapGenerateLogicBaseComponent::PlaceWallsAndEntrances
  • ACMRoom::ExcuteSpawnRoom 이 세트가 서버와 클라이언트에서 각각 한 번씩 실행됨

3.2. PlaceWallsAndEntrances 의 조건

• 초기 버전에서는 GetOwner()->HasAuthority() 만 보고 Entrance 를 생성
• 이후 ENetMode NetMode = GetWorld()->GetNetMode() 를 도입해 NetMode != NM_Client 인 경우에만 Entrance 를 생성하도록 변경
• 하지만 여전히 문제가 남았던 부분:
  • else 분기 (OutRoomMap 에 인접 방이 없을 때)에서 Wall 스폰은 권한/NetMode 체크 없이 항상 실행
  • ExcuteSpawnRoom 내부에서도 별도의 HasAuthority() 체크가 없으면, 양쪽에서 모두 스폰
• 최종적으로는:
  • 서버 MapGenerator → Entrance + Wall 스폰
  • 클라 MapGenerator → (NetMode 체크 추가 후) Entrance 는 안 만들더라도, Wall 은 만들 수 있음
  • 그리고 ACMRoom 이 비복제라면, 서버/클라 각각의 ACMRoom 인스턴스도 자기 기준에서는 HasAuthority() == true

3.3. 로그가 둘 다 1로 찍히는 이유

• UE_LOG(LogTemp, Log, TEXT("HasAuthority: %d, NetMode: %d"), GetOwner()->HasAuthority(), (int32)NetMode);
• 위 로그에서:
  • 서버 월드: HasAuthority = 1, NetMode = 2 (ListenServer) 또는 1 (DedicatedServer)
  • 클라 월드: HasAuthority = 1, NetMode = 3 (Client) 인 케이스가 가능
• 즉, 단순히 HasAuthority 칼럼만 보면 둘 다 1로 찍히기 때문에,
  • "Authority 를 둘 다 갖고 있는 것 같다" 는 인상을 받게 됨
  • 실제로는 서로 다른 월드에서 각각 Authority 인 비복제 Actor 일 뿐, 네트워크 복제와는 무관

4. 해결 전략

4.1. 서버/클라이언트 분기 기준을 명확히

• "맵을 생성하는 로직은 서버/호스트에서만 실행한다" 를 명확한 정책으로 잡음
• 이를 위해 다음 기준을 사용
  • UWorld::GetNetMode() 가 NM_Client 이면 → 맵 생성 로직/스폰 로직은 아예 실행하지 않음
  • HasAuthority() 는 보조적으로 사용하되, 비복제 Actor 도 Authority 일 수 있다는 점을 항상 염두에 둠

5. 최종 정리

아래는 Entrance 인스턴스가 정상적으로 Replication On/Off 되는 결과물입니다.

• 언리얼 네트워크에서 HasAuthority() 와 NetMode 는 비슷해 보이지만, 서로 다른 레이어의 개념이라는 점을 다시 상기

  • HasAuthority() : 이 Actor 인스턴스가 자기 월드에서 서버 역할인지
  • NetMode : 이 월드가 DedicatedServer / ListenServer / Client / Standalone 인지

• 비복제 Actor 는 서버와 클라이언트에서 각각 스폰되면, 둘 다 HasAuthority() == true 라는 점이 핵심 포인트

• 따라서, 서버/클라이언트를 분기하고 싶을 때는 다음 우선순위를 지키는 것이 좋다고 정리

• 우선순위

  1. UWorld::GetNetMode() 로 프로세스 레벨(서버/클라) 구분
     • NM_Client 인 경우 서버 전용 로직을 실행하지 않음
  2. AActor::HasAuthority() 는 복제된 Actor 의 서버/클라 인스턴스 구분에 사용
  3. 스폰 로직이 있는 함수(예: ExcuteSpawnRoom) 내부에도 HasAuthority() 체크를 두어 이중 방어

• 이번 트러블슈팅을 통해 얻은 교훈

  • 단순히 "Authority 가 true 니까 서버겠지" 라고 생각하면 쉽게 헷갈린다.
  • 맵 생성처럼 월드 전체에 영향을 주는 로직은 반드시 서버/호스트 한 곳에서만 실행되도록 구조를 잡는 것이 중요하다.
  • 디버깅 시에는 HasAuthority 뿐 아니라 NetMode 값도 함께 로그로 남겨야, "어느 월드에서 무슨 역할로" 실행 중인지 명확히 볼 수 있다.

1. 문제 상황 정리

• 증상 요약

  • 같은 위치(두 방 사이의 경계)에 Entrance(문 같은 Border 액터)가 겹쳐서 여러 개 생성됨

• 관련 주요 컴포넌트

  • UCMMapGenerateLogicBaseComponent::GenerateRoom()
    • DFS로 격자 기반 방 위치(FCMRoomPosition)를 생성
    • OutRoomMap: TMap<FCMRoomPosition, ACMRoom*> 에 방 스폰 결과 저장
  • UCMMapGenerateLogicBaseComponent::PlaceWallsAndEntrances()
    • OutRoomMap을 순회하면서 각 방향에 Wall / Entrance 스폰
  • ACMRoom::SpawnBorderElement()
    • 실제 Entrance / Wall 액터를 스폰하고, RoomBorderActors[4] 에 캐시

이 세 곳의 로직이 서로 어떻게 엮이는지 이해하는 것이 문제 해결의 핵심이었습니다.

2. 1차 원인: 방향 인덱스(상/좌/하/우) 불일치

2-1. GenerateRoom과 DirectionX/DirectionY의 불일치

• GenerateRoom 내부 정의

  • 방향 인덱스 체계(0~3)를 다음과 같이 사용하고 있었습니다.
    • DirOffset[4] = {(0,1), (1,0), (0,-1), (-1,0)}
    • DirIndexFromDelta(DX, DY) → 0:Up, 1:Left, 2:Down, 3:Right
    • OppositeDir(Dir) → 0↔2, 1↔3

• PlaceWallsAndEntrances에서 사용하던 배열 (초기 상태)

  • DirectionX[4] = {1, 0, -1, 0}; // 우, 하, 좌, 상
  • DirectionY[4] = {0, -1, 0, 1}; // 우, 하, 좌, 상
  • 즉, 0:Right, 1:Down, 2:Left, 3:Up 구조였고, GenerateRoom의 0:Up,1:Left,2:Down,3:Right 와 정반대 순서였습니다.

• 이로 인한 문제

  • 방의 좌표(FCMRoomPosition)와 그래프(Adjacency, ConnectedRooms)는 상/좌/하/우 기준으로 잘 생성됨
  • 하지만 Wall/Entrance 판단은 우/하/좌/상 기준으로 검사
  • 결과적으로, 바로 옆에 방이 있어도 "없는 것처럼" 판단하거나, 반대로 다른 방향을 인접한 것으로 취급하는 문제가 발생
  • 눈으로 보면 방 배치는 그럴싸한데, 문과 벽이 이상한 방향에 생성되어 전체가 어그러져 보임

2-2. 해결: 모든 방향 관련 정의를 상/좌/하/우로 통일

• 조치

  • UCMMapGenerateLogicBaseComponent 헤더에서 DirectionX/DirectionY 를 다음과 같이 수정:
    • DirectionX[4] = { 0, -1, 0, 1}; // 상, 좌, 하, 우
    • DirectionY[4] = { 1, 0, -1, 0}; // 상, 좌, 하, 우
  • 이렇게 해서 다음 4개가 모두 동일한 인덱스 체계(0:Up,1:Left,2:Down,3:Right)를 사용하도록 맞추었습니다.
    • DirOffset
    • DirIndexFromDelta
    • OppositeDir
    • DirectionX/DirectionY 및 ACMRoom::ConnectedRooms[4] / RoomBorderActors[4]

• 교훈

  • 방향 인덱스/좌표계를 여러 곳에서 정의할 때는 하나의 기준(예: 상/좌/하/우) 을 정하고, 전역적으로 사용해야 디버깅이 쉬워집니다.

3. 2차 원인: SpawnBorderElement의 인덱스 버그로 인해 Entrance 다중 스폰

3-1. 증상: 같은 경계에 Entrance가 여러 개 생김

• 특정 두 방 사이에 문이 한 쌍만 있어야 하는데, 실제로는 같은 위치에 Entrance 액터가 여러 개 겹쳐서 생성됨
• 처음에는 "PlaceWallsAndEntrances에서 같은 경계를 두 번 처리(A→B, B→A)해서 그런가?" 정도로 추측

3-2. SpawnBorderElement 내부의 중복 방지 로직 분석

• 원래 의도

  • ACMRoom::SpawnBorderElement(int32 DirectionIndex, bool bIsEntrance) 는 같은 방향으로 여러 번 호출되더라도 한 번만 SpawnActor 하고, 이후에는 캐싱된 액터 포인터를 재사용해야 했습니다.
  • 중복 방지 코드 (초기 상태):
    • if (RoomBorderActors[DirectionIndex]) return RoomBorderActors[DirectionIndex];

• 문제 구간

  • 스폰 후 반대편 룸에도 같은 BorderActor를 공유해 주려던 로직:
    • if (ConnectedRooms[DirectionIndex + 2 % 4])
    • ConnectedRooms[DirectionIndex + 2 % 4]->RoomBorderActors[DirectionIndex] = SpawnedActor;

• 버그 1: 연산자 우선순위 실수

  • DirectionIndex + 2 % 4 는 DirectionIndex + (2 % 4) 로 계산됨 → DirectionIndex + 2
  • 의도는 (DirectionIndex + 2) % 4 로 0↔2, 1↔3 매핑이었지만, 실제로는
    • 0 → 2 (우연히 맞음)
    • 1 → 3 (우연히 맞음)
    • 2 → 4 (배열 범위 밖)
    • 3 → 5 (배열 범위 밖)
  • 이로 인해 ConnectedRooms 배열 범위를 벗어나 잘못된 메모리를 읽거나 쓰게 되고, RoomBorderActors 중복 체크가 붕괴될 위험이 생겼습니다.

• 버그 2: 반대편 룸에 잘못된 인덱스로 저장

  • ConnectedRooms[DirectionIndex + 2 % 4]->RoomBorderActors[DirectionIndex] = SpawnedActor;
  • 반대편 룸에서는 반대 방향 인덱스(OppDir) 에 저장해야 하는데, 여전히 DirectionIndex 를 사용하고 있었습니다.
  • 예를 들어, 현재 방에서 Up(0) 방향 Entrance를 만들 때 반대편(Down 방향)의 인덱스는 2가 되어야 하는데, 잘못된 인덱스에 기록될 수 있습니다.

• 결과

  • 중복 방지용 RoomBorderActors[DirectionIndex] 또는 이웃 룸의 RoomBorderActors 가 꼬이면서,
  • 같은 경계를 여러 번 처리할 때마다 SpawnActor 가 재호출되어 Entrance가 계속 쌓이는 현상으로 이어졌습니다.

3-3. 해결: SpawnBorderElement 로직 수정

• 수정 포인트

  • 반대 방향 인덱스를 정확히 계산:
    • const int32 OppDir = (DirectionIndex + 2) % 4;
  • 현재 룸과, 연결된 반대편 룸 모두에 동일 BorderActor를 공유:
    • 현재 룸:
      • RoomBorderActors[DirectionIndex] = SpawnedActor;
    • 반대편 룸이 이미 연결되어 있다면:
      • ConnectedRooms[OppDir]->RoomBorderActors[OppDir] = SpawnedActor;

• 핵심 아이디어

  • 경계 하나(두 방 사이)에 Border 액터는 하나만 존재해야 하고,
  • 두 방은 각각 자신의 RoomBorderActors[해당 방향] 에서 동일한 액터 포인터를 가지도록 설계
  • 이렇게 하면, A→B, B→A 어느 쪽에서 먼저 SpawnBorderElement 를 호출해도,
    • 최초 1회만 SpawnActor가 실행되고,
    • 이후에는 캐싱된 포인터를 재사용하게 됩니다.

4. 3차 원인: 쿼드트리 기반 생성 과정에서의 이슈 (물리적 인접 Room 문제)

4-1. 문제 인식

• 맵을 쿼드트리(QuadTree) 기반으로 생성하다 보니, 논리적인 그래프/트리 상에서의 인접 관계와 실제 격자 좌표 상의 물리적 인접 관계가 항상 일치하지 않는 문제가 발생
  • 예시 상황
    • 쿼드트리의 어떤 노드가 서브 트리로 분기되면서, 실제로는 (0,0)과 (1,0) 같은 이웃 타일이 물리적으로는 맞닿아 있지만,
    • 트리 구조 상으로는 서로 다른 브랜치에 속해 있어 "인접 노드"로 간주되지 않는 경우가 발생
• 따라서, Room에서 캐싱한 ConnectedRooms[]으로는 인접한 방이 존재하는지 확인할 수 있는 방법 X
• 방이나 Border가 없다고 판단되어 벽을 생성하는 문제 발생

4-2. 해결: FCMRoomPosition 기반 재캐싱

• 해결 전략: FCMRoomPosition 기반 재캐싱
  • 트리/그래프 상의 인접 정보(Adjacency)에만 의존하지 않고, 항상 최종 좌표(FCMRoomPosition)를 기준으로 인접성을 재검증하도록 설계 방향을 변경
  • 구체적으로는:
    • 쿼드트리 분기, DFS/스패닝 트리 생성 등을 모두 마친 뒤,
    • 최종적으로 OutRoomMap 에 담긴 (FCMRoomPosition → ACMRoom*) 정보를 다시 순회하면서
    • 각 좌표의 상/좌/하/우 방향에 대해 직접 OutRoomMap.Find(NeighborPos) 를 호출
    • 이렇게 해서 물리적으로 인접한 방들만 ConnectedRooms 로 다시 묶어 주도록 후처리
  • 이 재캐싱 단계 덕분에
    • 쿼드트리 상으로는 떨어진 브랜치에 있더라도, 실제 그리드 상에서 붙어 있는 방들은 모두 인접 방으로 인식
    • Entrance/Wall 생성 로직은 오직 FCMRoomPosition 기반 인접성에만 의존하게 되어, 트리 구조에 의해 왜곡되지 않음

4-3: 효과

• 최종적으로는 격자 상에서 인접한 방들끼리는 항상 ConnectedRooms가 양방향으로 일관되게 채워짐
• 쿼드트리/그래프 구조가 어떻게 변하더라도, FCMRoomPosition 기반 재캐싱 과정 덕분에 Entrance/Wall 스폰 로직이 올바른 인접 정보를 참조할 수 있게됨

이번 트러블슈팅을 통해, 단순히 "Entrance가 여러 개 생긴다"는 증상을 해결하는 데에도 여러 층위의 문제가 겹쳐 있을 수 있음을 체감했습니다. 방향 인덱스와 좌표계 정의가 조금만 어긋나도 전체 구조가 틀어지고, 작은 연산자 우선순위 실수 하나가 메모리 오염과 중복 스폰으로 이어질 수 있음을 경험했습니다.

앞으로는 방향/인덱스/좌표 체계를 프로젝트 초기에 명확히 문서화하고, 경계(Entrance/Wall)와 같은 공유 리소스는 "한 번만 스폰, 양쪽에서 공유"라는 설계를 기본 원칙으로 삼으려 합니다.

발생한 현상 요약

• 리슨 서버에서 StreamingLevelName = L_StreamingTest2 설정 후 LoadLevelInstance 계열 로직으로 레벨 인스턴스 생성

• 리슨 서버 단독 플레이에서는 정상적으로 방이 원하는 위치에 생성

• 두 번째 클라이언트가 접속하면 다음과 같은 로그 출력 후 연결 끊김

  • ServerUpdateLevelVisibility() ignored non-existant package
  • MissingLevelPackage
  • Your connection to the host has been lost.

• 결과적으로, 서버 입장에서는 스트리밍이 성공한 것처럼 보이나, 새로 접속한 클라이언트 기준에서는 해당 패키지를 찾지 못해 접속이 강제로 종료되는 상황 발생

근본 원인 1: ULevelStreamingDynamic 이름 비결정성

• 문제가 된 코드에서 사용한 것은 ULevelStreamingDynamic / LoadLevelInstance 계열 API
• LoadLevelInstance 내부 구현
  • MakeUniqueObjectName(..., TEXT("_LevelInstance")) 로 스트리밍 레벨 인스턴스 이름 자동 생성
  • _LevelInstance_135, _LevelInstance_396 같이 접미사 숫자가 내부 카운터 기반으로 붙음
• 서버/클라이언트 각각이 같은 맵 이름으로 LoadLevelInstance를 호출해도
  • 서버: L_StreamingTest2_LevelInstance_135
  • 클라: L_StreamingTest2_LevelInstance_396
  • 이런 식으로 서로 다른 이름의 패키지 생성
• 결과적으로 서버가 가진 스트리밍 패키지 이름과 클라이언트가 가진 패키지 이름이 일치하지 않음
  • 서버는 ..._135를 visibility 업데이트 대상으로 삼지만
  • 클라이언트 월드에는 ..._135가 존재하지 않음 → ignored non-existant package 로그 출력

근본 원인 2: 동적 스트리밍 레벨 정보는 Replication 되지 않음

• 언리얼 기본 네트워크 동기화는 액터 / 컴포넌트 / 프로퍼티에 초점
• ULevelStreamingDynamic 으로 런타임에 새 스트리밍 레벨을 로드하는 행위 자체
  • 서버에서 생성했다고 해서 해당 스트리밍 레벨 정보가 클라이언트로 자동 복제되지 않음
• 서버 기준 흐름
  • 서버: Dynamic Streaming Level 생성 및 로드, visible 상태로 전환
  • 서버: ServerUpdateLevelVisibility 에서 해당 패키지를 클라에게도 보여주려고 시도
• 클라이언트 기준 상황
  • 클라이언트: 해당 이름의 스트리밍 레벨 인스턴스를 가진 적이 없음
  • 네트워크를 통해 "이 이름의 스트리밍 레벨을 같이 로드하자" 라는 정보가 구조적으로 내려오지 않음
• 따라서 서버와 클라의 스트리밍 레벨 목록이 서로 일치하지 않는 상태에서 visibility 동기화가 수행됨
  • 없는 패키지에 대해 visibility 업데이트를 시도 → MissingLevelPackage 로 연결 종료

근본 원인 3: 호출 타이밍·월드 상태의 비결정성

• LoadLevelInstance 는 다음 요소들에 의존하는 비결정적(Non-Deterministic) 특성 존재
  • 오브젝트 이름 카운터
  • GC 및 기존 객체 존재 여부
  • 호출 시점, 호출 순서
• 서버와 클라이언트가 같은 프레임에 같은 코드 경로를 탄다 하더라도
  • 내부적으로 생성되는 LevelInstance 이름, 로딩 완료 시점, 스트리밍 레벨 배열에 들어가는 순서는 항상 일치한다고 보장할 수 없음
• 특히 리슨 서버 환경에서
  • 서버와 첫 번째 클라이언트는 같은 프로세스 내에서 이상 없이 보이지만
  • 두 번째 클라이언트는 이미 월드 상태가 바뀐 뒤 접속하기 때문에, 기존에 서버에서 만든 Dynamic Level과 맞출 수 있는 정보가 더더욱 부족

멀티플레이에서 Dynamic Level Instance를 쓰기 어려운 이유 정리

• ULevelStreamingDynamic / LoadLevelInstance 기반 구조는 멀티플레이에서 다음 이유로 부적합
  • 인스턴스 이름이 자동 생성 → 서버/클라 이름 불일치
  • 동적으로 추가한 스트리밍 레벨 목록이 replication 되지 않음
  • 기존 네트워크 레벨 로딩/전환 파이프라인과 분리된 별도 경로로 동작
  • 접속 중인 플레이어별로 월드 상태가 달라질 수 있어, 새로 접속한 플레이어가 기존 동적 레벨 상태를 재현하기 어려움
• 따라서 "서버가 동적으로 레벨 인스턴스를 만든 뒤, 그걸 그대로 클라이언트에게 복제하는 구조"는 언리얼 기본 기능만으로는 성립하지 않음

이번 프로젝트에서 드러난 오해 정리

• 오해 1
  • "서버에서만 맵 스트리밍을 하면, 그 지형 정보가 자동으로 클라이언트에게 복제된다"
  • 실제로는 동적 스트리밍 레벨 자체는 복제가 안 되고, 고정된 맵 전환/스트리밍에만 네트워크 지원이 붙어 있음
• 오해 2
  • "서버와 클라이언트가 같은 함수를 호출하면, 같은 LevelInstance 이름으로 생성될 것이다"
  • 실제로는 MakeUniqueObjectName 특성상 이름이 달라질 수밖에 없고, 호출 순서/개수 차이로 완전히 다른 결과가 나옴
• 오해 3
  • "에러 로그에 나오는 패키지 이름만 맞춰주면 된다"
  • 실제로는 이름만의 문제가 아니라, 스트리밍 레벨의 생성·레이아웃·오너십 전체가 네트워크 파이프라인 밖에 있어서 구조적으로 어긋나 있음

앞으로의 설계 방향 메모

• 방 단위 맵 생성이 필요할 때 고려할 선택지
  • 고정 Streaming Level 여러 개를 에디터에 등록한 뒤, 서버/클라 모두 같은 이름으로 Stream In/Out
  • 완전히 동적인 던전은 "레벨 스트리밍" 대신 "액터 스폰 + 랜덤 시드 동기화" 패턴 적용
  • 장기적으로는 World Partition 기반으로 전환하고 Data Layer를 사용해 가시성/로딩 제어
• 특히 멀티플레이를 고려하는 시스템에서는
  • "서버가 만든 레벨이 그대로 클라에 복제된다"는 가정을 버리고
  • "항상 서버/클라가 같은 규칙으로 월드를 재구성한다"는 관점에서 설계하는 편이 안전함

마치며

이번 문제는 단순히 코드 버그라기보다, 언리얼 엔진의 레벨 스트리밍과 네트워크 동기화가 어떻게 설계되어 있는지 충분히 이해하지 못한 상태에서 ULevelStreamingDynamic을 멀티플레이 환경에 그대로 적용한 데에서 비롯된 것이었습니다. 서버와 클라이언트가 동일한 레벨 인스턴스를 공유한다고 가정하고 구현했으나, 실제로는 인스턴스 이름 생성, 스트리밍 레벨 목록 관리, 패키지 로딩 흐름이 네트워크와 분리되어 있어, 새로 접속한 클라이언트가 동적으로 생성된 레벨을 찾지 못하는 상황이 발생했습니다.

이 TIL을 통해, 멀티플레이에서 레벨을 다루는 방법은 기존 싱글 플레이/에디터 중심 사고방식과는 다르게 접근해야 한다는 점을 다시 한 번 정리하게 되었습니다. 앞으로는 월드 파티션, 고정 스트리밍 레벨, 액터 기반 동적 생성 등 언리얼이 제공하는 네트워크 친화적 구조를 우선적으로 고려하여 설계하고, 특히 "서버가 만든 것을 클라에 그대로 복제한다"는 직관적인 기대 대신, "서버와 클라가 합의된 규칙에 따라 동일한 월드를 재구성한다"는 관점에서 시스템을 구성하고자 합니다.

초기 데이터 설정

데이터 설정은 UCMRoomDataDefinition을 기반으로 결정됩니다. 이 곳에서 넓이, 방의 갯수, 방 종류 등을 셋팅합니다. 또한, 맵 생성 알고리즘과 시작 지점 선택 알고리즘도 컴포넌트화시켜 기획 담당자가 쉽게 변경할 수 있도록 설계했습니다.

맵 생성 전반 구조

• 맵 생성의 진입점

  • UCMMapGenerateLogicBaseComponent::ExecuteMapGenerationLogic
  • 입력
    • 시드 값 InSeed
    • 맵 정의 데이터 UCMRoomDataDefinition* InMapData
    • 결과를 담을 TMap<FCMRoomPosition, TObjectPtr<ACMRoom>>& OutRoomMap
  • 내부 흐름
    • GenerateRoom에서 방 그래프 및 방 액터 생성
    • PlaceWallsAndEntrances에서 각 방의 벽과 입구(Entrance) 스폰

• 핵심 데이터 구조

  • FCMRoomPosition
    • 정수 좌표 (X, Y)로 방의 격자 상 위치 표현
  • OutRoomMap
    • FCMRoomPosition → ACMRoom* 매핑
    • 맵 생성 알고리즘과 실제 액터 스폰을 연결하는 브리지 역할

방 그래프 생성 알고리즘 개요

1. 사용한 알고리즘

• 전체 알고리즘 성격

  • 격자 기반 그래프 위에서 랜덤 DFS(깊이 우선 탐색) 를 이용해 스패닝 트리 형태의 맵을 만듭니다
  • 시작점에서 멀리 떨어진 리프 노드를 보스 방으로, 그 외 후보에서 보물 방을 선정하는 구조

• 주요 의도

  • 항상 연결 그래프를 유지해 플레이어가 어디서든 막히지 않고 진행 가능
  • 랜덤 시드를 사용해 재현 가능한(random but reproducible) 맵 구조 생성
  • 시작 방에서 거리가 먼 리프에 보스를 배치해 자연스러운 진행 경로 유도

2. 좌표계 및 경계 설정

• 맵 크기 정의
  • UCMRoomDataDefinition에 너비/높이/최대 방 수, 보물 방 수, 보스 방 수를 정의
• 중심 기준 경계 계산
  • 맵의 중심을 (0, 0)으로 두고
  • X, Y 축에 대해 MinX, MaxX, MinY, MaxY 계산
  • 생성 중인 방 위치가 이 범위를 벗어나지 않도록 검사

3. DFS 기반 방 확장

• 시작점 설정

  • Start = FCMRoomPosition(0, 0)
  • OutRoomMap.Add(Start, nullptr)로 먼저 좌표만 점유
  • DFS 스택에 시작 노드를 push

• 방향 정의

  • 인덱스 0~3에 상, 좌, 하, 우를 고정 매핑
  • DirOffset[4] 배열을 사용해 FCMRoomPosition 델타 계산

• 확장 로직

  • DFS 스택의 top을 현재 노드로 사용
  • 상하좌우 중 아직 점유되지 않았고, 맵 경계 안에 있는 방향만 후보에 추가
  • FRandomStream(시드 고정 랜덤)으로 후보 방향 중 하나를 선택
  • 다음 좌표 Next를 계산하고, OutRoomMap.Add(Next, nullptr)로 점유
  • 인접성 정보 Adjacency에 Curr <-> Next 양방향으로 추가
  • 부모 방향 정보 ParentDirIndex를 기록해 나중에 트리 구조 복원에 사용
  • 더 이상 확장할 방향이 없으면 DFS 스택 pop으로 백트래킹

• 결과

  • OutRoomMap.Keys()가 전체 방 좌표 집합
  • Adjacency가 그래프의 엣지 집합
  • 구조적으로 사이클이 거의 없는 트리 또는 트리 기반 그래프가 형성

4. 거리 계산과 리프 노드 분석

• 거리 계산

  • 시작점에서 BFS를 돌며 각 방까지의 최단 거리 Distance 계산
  • Adjacency를 그대로 사용해 그래프 탐색

• 리프 노드 추출

  • 각 좌표에 대해 인접 방 개수(차수)가 1인 노드를 리프로 간주
  • 시작점(0, 0)은 예외로 처리

• 거리 기반 정렬

  • 리프 리스트를 Distance 내림차순으로 정렬
  • 시작점에서 멀리 떨어진 리프일수록 우선순위가 높음

• 보스/보물 방 배치

  • 보스 방
    • 정렬된 리프들 중 앞에서부터 DesiredBoss 개수만큼 선택
    • BossPositions 집합에 좌표 저장
  • 보물 방
    • 시작점과 보스 방을 제외한 모든 좌표를 후보로 수집
    • 랜덤 셔플 후 상위 DesiredTreasure개를 TreasurePositions 집합으로 선택

방 액터 스폰과 월드 좌표 매핑

1. 방 크기 측정과 간격 계산

• 방 크기 측정 방법

  • ACMRoom은 UCMRoomBoundsBox 컴포넌트를 통해 실제 방의 월드 상 가로, 세로 크기를 노출
  • GetRoomWidth, GetRoomHeight에서 박스 익스텐트를 2배한 값으로 길이 산출

• 대표 간격 계산

  • 몬스터/보물/보스 방 클래스들의 CDO를 순회해 최대 폭/높이 측정
  • 값이 너무 작거나 0일 경우, 실제 방을 임시 스폰해 한 번 더 측정
  • 최종적으로 X, Y 방향 SpacingX, SpacingY를 결정

• 좌표 → 월드 위치 매핑

  • FVector Location(Pos.X * SpacingX, Pos.Y * SpacingY, 0.f)
  • 격자 좌표를 그대로 월드 좌표에 선형 변환
  • 방들 사이에 겹침 없이 일정 간격을 확보하는 구조

2. 방 타입에 따른 클래스 선택

• 룸 타입 판정

  • 좌표가 BossPositions에 포함되면 보스 방
  • 그 외 TreasurePositions에 포함되면 보물 방
  • 둘 다 아니면 일반 몬스터 방

• 클래스 선택 로직

  • UCMRoomDataDefinition에 각 타입별 클래스 배열 보유
  • FRandomStream으로 해당 배열에서 하나를 랜덤 선택
  • 타입별 클래스가 비어 있으면 몬스터 방 클래스로 폴백

• 스폰

  • World->SpawnActor<ACMRoom>(ClassToSpawn, Location, Rotation, SpawnParams)
  • 성공 시 OutRoomMap[Pos]를 실제 포인터로 덮어써서 좌표와 액터 인스턴스를 연결

방 간 연결 정보와 입구/벽 배치

1. 연결 방향 인덱스 계산

• DirIndexFromDelta(DX, DY)

  • 두 좌표 차이(델타)를 상/좌/하/우 인덱스로 변환
  • 예시
    • (0, +1) → 0 (Up)
    • (-1, 0) → 1 (Left)
    • (0, -1) → 2 (Down)
    • (+1, 0) → 3 (Right)

• OppositeDir(Dir)

  • 상↔하, 좌↔우로 대응되는 반대 방향 인덱스를 반환

2. 연결 바인딩

• 맵 생성 후, 모든 방에 대해 인접 좌표 리스트를 순회

• 인접 좌표에 해당하는 ACMRoom*를 찾아 상호 연결

  • Room->SetConnectedRoom(Dir, NeighborRoom)
  • NeighborRoom->SetConnectedRoom(OppositeDir(Dir), Room)

• 디버그 로그

  • 각 연결 설정 시 UE_LOG로 양 끝 좌표와 방향 인덱스를 출력해 검증

3. 입구와 벽 스폰

• PlaceWallsAndEntrances(OutRoomMap) 단계

  • 각 ACMRoom에 대해 GetConnectedRooms()로 상하좌우 연결 상태 조회
  • 네 방향에 대해
    • 연결된 방이 있으면 Entrance 스폰
    • 없으면 Wall 스폰

• ACMRoom::SpawnBorderElement

  • 각 방향별 USceneComponent(North/South/East/West EntrancePoint)를 기준으로 좌표와 회전값 계산
  • RoomEntranceClass 또는 RoomWallClass를 사용해 액터 스폰
  • 이미 한 번 스폰된 Border는 재사용해 중복 스폰 방지

레벨 스트리밍 구조

1. ACMRoom과 StreamingLevelName

• ACMRoom에 추가된 프로퍼티

  • UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Streaming") FName StreamingLevelName;

• 역할

  • 각 방이 어떤 서브 레벨과 연결되는지를 에디터에서 직접 지정 가능
  • 예: L_StreamingTest1, L_StreamingTest2 같은 이름을 방마다 다르게 설정해 사용

• Getter/Setter

  • FName GetStreamingLevelName() const로 외부에서 조회
  • void SetStreamingLevelName(FName InLevelName)로 런타임 중 변경 가능

2. 동적 스트리밍 인 함수: StreamingLevelStreamIn

• 진입점

  • void ACMRoom::StreamingLevelStreamIn()
  • 방이 활성화될 때, 혹은 입구를 통해 진입할 때 호출하는 것을 상정

• 처리 흐름

  • World와 StreamingLevelName 유효성 검사
  • StreamingLevelName을 레벨 애셋 이름으로 보고, 경로 문자열 생성
    • 현재 구현 예
      • StreamingLevelName = "L_StreamingTest1"
      • LevelPath = "/Game/MainStage/L_StreamingTest1"
  • Room의 월드 위치를 가져와 스트리밍 레벨의 기준 위치로 사용
    • RoomLocation = GetActorLocation()
  • ULevelStreamingDynamic::LoadLevelInstance 호출
    • 매번 새로운 스트리밍 레벨 인스턴스를 동적으로 생성
    • 인자
      • World
      • LevelPath (패키지 경로)
      • RoomLocation
      • FRotator::ZeroRotator
      • bSuccess (성공 여부)

• 결과

  • 호출할 때마다 해당 레벨이 Room 위치에 복제되듯이 로드
  • 여러 Room에서 같은 StreamingLevelName을 사용하면, 같은 레벨이 여러 위치에 여러 인스턴스로 생성되는 효과

• 성공/실패 로그

  • 실패 시
    • StreamingLevelStreamIn: Failed to dynamically load level '...' for Room ...
  • 성공 시
    • StreamingLevelStreamIn: Dynamically loaded level '...' at Room ... Location=(x, y, z)

3. Room 생성과 스트리밍의 연결

• Room 생성 시점

  • UCMMapGenerateLogicBaseComponent::GenerateRoom 안에서 방 액터가 스폰됩니다

• 스트리밍 호출 시점

  • 현재 코드에서는 예시로 ACMRoom::ExcuteSpawnRoom에서
    • StreamingLevelStreamIn();
    • SpawnBorderElement(DirectionIndex, bIsEntrance);
  • 특정 방향으로 출입구를 생성하는 타이밍에 스트리밍을 함께 트리거하는 구조

• 활용 아이디어

  • 플레이어가 특정 방에 입장할 때 해당 방의 서브 레벨을 Stream In
  • 반대로 이전 방에서 멀어졌을 때 Stream Out 함수(추가 구현)를 호출해 메모리 사용량 관리
  • Room 타입(일반/보스/보물)에 따라 서로 다른 서브 레벨을 바인딩해 다양한 룸 구성을 만듦

구현 결과

마치며

이번 글에서는 적용한 맵 생성과 레벨 스트리밍 구조를 정리해 보았습니다. 격자 기반 DFS 스패닝 트리 알고리즘을 이용해 항상 연결된 방 그래프를 만들고, 시작점에서의 거리 정보를 활용해 보스 방과 보물 방을 자연스럽게 배치하였습니다. 이후 방의 크기를 기반으로 월드 좌표를 계산해 액터를 스폰하고, 인접 정보에 따라 입구와 벽을 자동으로 구성하는 과정을 정리해 보았습니다.

또한 각 방에 스트리밍 레벨 이름을 직접 바인딩할 수 있는 구조를 만들고, ULevelStreamingDynamic::LoadLevelInstance를 통해 방 위치에 맞춰 서브 레벨을 동적으로 로드하는 방식을 도입하였습니다. 이를 통해 동일한 레벨 자산을 여러 방에서 재사용하거나, 방 타입에 따라 서로 다른 레벨 레이아웃을 바인딩하는 등 확장성이 높은 구조를 갖추게 되었습니다.

멀티 스레드 환경에서 자원 잠금을 잘못 처리하면 쉽게 발생할 수 있는 대표적인 동시성 문제입니다.

데드락이 발생하기 위한 4가지 조건 (Coffman 조건)

데드락은 아래 4가지 조건이 모두 만족해야 발생합니다.

1. 상호 배제(Mutual Exclusion)

   • 자원을 동시에 사용할 수 없습니다. (예: mutex)

2. 점유와 대기(Hold and Wait)

   • 이미 자원을 보유한 상태에서 다른 자원을 기다립니다.

3. 비선점(No Preemption)

   • 다른 프로세스가 보유한 자원을 강제로 빼앗을 수 없습니다.

4. 순환 대기(Circular Wait)

   • 여러 프로세스가 서로가 보유한 자원을 기다리는 순환 구조가 형성됩니다.

이 중 하나라도 깨면 데드락을 방지할 수 있습니다. (중요)

데드락 예시: 두 개의 Mutex 잠금 순서 충돌

아래 예시는 데드락이 실제로 발생하는 C++ 코드입니다. ThreadA와 ThreadB가 서로 반대로 mutex를 잠금으로써 데드락이 발생합니다.

#include <iostream>
#include <thread>
#include <mutex>
#include <chrono>

using namespace std;

mutex m1;
mutex m2;

void ThreadA() {
    cout << "[ThreadA] Lock m1\n";
    m1.lock();
    this_thread::sleep_for(chrono::milliseconds(100));

    cout << "[ThreadA] Try Lock m2\n";
    m2.lock();  // ThreadB가 m2를 잡고 있으므로 데드락
}

void ThreadB() {
    cout << "[ThreadB] Lock m2\n";
    m2.lock();
    this_thread::sleep_for(chrono::milliseconds(100));

    cout << "[ThreadB] Try Lock m1\n";
    m1.lock();  // ThreadA가 m1을 잡고 있으므로 데드락
}

int main() {
    thread t1(ThreadA);
    thread t2(ThreadB);

    t1.join();
    t2.join();

    return 0;
}

실행결과

이 상태에서 프로그램이 더 이상 진행되지 않았습니다.

데드락을 예방하는 방법

1) 자원 획득 순서를 통일하기

모든 스레드가 항상 같은 순서(A → B)로 자원을 잠그도록 합니다. 이렇게 하면 순환 대기 조건을 깨뜨릴 수 있습니다. => AB/BA 금지

2) std::scoped_lock 사용하기 (C++17 이상)

std::scoped_lock lock(m1, m2);

두 mutex를 데드락 없이 안전하게 한 번에 잠글 수 있습니다.

3) 타임아웃 기반 try_lock 사용

자원을 못 획득하면 아예 포기하거나 재시도하여 무한 대기를 피합니다.

증상(오류 메시지/현상)

• TMap<FCMRoomPosition, ...> 사용 시 컴파일 오류 발생
• 대표 오류 형태
  • ‘GetTypeHash’: 일치하는 오버로드된 함수가 없습니다 (no matching overloaded function found)
  • TMap 키 타입에 대해 해시를 찾을 수 없습니다 (no hash function for type ‘FCMRoomPosition’)
• 문제 구문 예시
  • TMap<FCMRoomPosition, TObjectPtr> Rooms;

원인 분석

• TMap은 해시 컨테이너로서 키의 해시 함수가 필요함
• 사용자 정의 USTRUCT 키는 기본 해시가 제공되지 않음
• 전역 범위의 GetTypeHash(const FCMRoomPosition&) 미구현
• 키 동등성 판단을 위한 operator== 미구현 또는 const/시그니처 부적합
• 헤더 분리 시 가시성 문제로 인해 TMap 선언 시점에 GetTypeHash 심볼이 보이지 않는 경우도 발생 가능

해결

• FCMRoomPosition에 const operator== 정의
• 전역 범위에 FORCEINLINE GetTypeHash(const FCMRoomPosition&) 구현
• 좌표형 int32에 대해 HashCombine(::GetTypeHash(X), ::GetTypeHash(Y)) 사용
• 키/해시 정의가 TMap 선언보다 먼저 포함되도록 include 순서 정리
• 빌드/리빌드로 오류 제거 확인

적용 코드

USTRUCT()
struct FCMRoomPosition
{
    GENERATED_BODY()

    int32 X;
    int32 Y;

    FORCEINLINE FCMRoomPosition() : X(0), Y(0) {}
    FORCEINLINE FCMRoomPosition(int32 InX, int32 InY) : X(InX), Y(InY) {}

    FORCEINLINE bool operator==(const FCMRoomPosition& Other) const
    {
        return X == Other.X && Y == Other.Y;
    }
};

// 전역 해시 함수
FORCEINLINE uint32 GetTypeHash(const FCMRoomPosition& Pos)
{
    // 두 좌표 해시 결합
    return HashCombine(::GetTypeHash(Pos.X), ::GetTypeHash(Pos.Y));
}

이번 이슈는 TMap이 요구하는 키 타입 계약(operator==, GetTypeHash)을 간과해서 발생한 문제였습니다. 사용자 정의 구조체를 컨테이너의 키로 사용하려면 비교와 해시의 정의가 반드시 필요하다는 점을 다시금 확인했습니다. 향후에는 키 타입을 설계할 때 동등성/해시의 일관성과 가시성(선언 순서)까지 함께 점검하여 유사한 빌드 오류를 사전에 방지해야겠습니다.