UE5 MMORPG 퀘스트 시스템

서버 책임 (데이터)

• 퀘스트 수락/진행/완료 상태
• 각 미션의 CurrentCount, RequiredCount, bClear 등 진행도
• 어떤 퀘스트가 수락 가능/완료 가능 인지 (NPC별 가능한 퀘스트 목록)
• 퀘스트 추적 여부(bIsTracking)의 최종 상태
• 재접속/로그인 시, 현재 퀘스트 전체 상태 제공

클라이언트 책임 (표현 + 런타임 캐시 데이터)

위 값들은 모두 서버에서 내려준 패킷을 기반으로 재구성하며,
퀘스트 완료 여부, 미션 달성 여부 자체의 판정은 항상 서버가 최종 권위를 가집니다.

ID 체계 차이

• 서버: QuestID, MissionID, NpcID를 모두 int32 ID로 관리
• 클라이언트: 기획 DataTable / DataAsset이 Q001, MIS001 같은 문자열 ID를 FName 키로 사용

ID 변환 유틸 함수 예시

패킷 파싱 & 큐 적재 예시

Dispatcher->RegisterHandler(EPacketType::SC_QUEST_START, [this](const TArray<uint8>& RawData)
{
    PKT_SC_QUEST_START* Pkt = (PKT_SC_QUEST_START*)RawData.GetData();

    FQuestStartPacketData PacketData;
    PacketData.QuestID = Pkt->QuestID;              // int32
    PacketData.NpcID = Pkt->NpcID;                  // int32
    PacketData.bHasTimeLimit = Pkt->HasTimeLimit;
    PacketData.TimeLimitSeconds = Pkt->TimeLimitSeconds;
    PacketData.bIsTracking = Pkt->bIsTracking;

    for (int32 i = 0; i < Pkt->MissionCount; ++i)
    {
        FMissionInfo MissionData;
        // 여기서 FName 변환 수행
        MissionData.MissionID = IntToMissionID(Pkt->Missions[i].MissionID); 
        MissionData.CurrentCount = Pkt->Missions[i].CurrentCount;
        MissionData.RequiredCount = Pkt->Missions[i].RequiredCount;

        PacketData.Missions.Add(MissionData);
    }

    QuestStartQueue.Enqueue(PacketData);
});

1-1. 큐와 델리게이트 기반의 상태 동기화

서버에서 받은 패킷을 즉시 처리하지 않고 타입별 큐(QuestInitialQueue, QuestStartQueue 등)에 적재한 뒤, UQuestManageSubSystem::Tick()에서 순차적으로 처리합니다.

[이벤트 기반의 퀘스트 상태 동기화 파이프라인]

1-2. 패킷 ID 변환 및 큐 적재 (Dispatcher)

서버의 int32 ID를 클라이언트 기획 데이터인 FName(Q001, MIS001 등) 체계로 변환하여 큐에 적재합니다.

Dispatcher->RegisterHandler(EPacketType::SC_QUEST_START, [this](const TArray<uint8>& RawData)
{
    // 1. 수신된 Raw 데이터를 패킷 구조체로 역직렬화
    PKT_SC_QUEST_START* Pkt = (PKT_SC_QUEST_START*)RawData.GetData();

    // 2. 클라이언트 내부 통신용 구조체(FQuestStartPacketData) 생성 및 기본 정보 복사
    FQuestStartPacketData PacketData;
    PacketData.QuestID = Pkt->QuestID;
    PacketData.NpcID = Pkt->NpcID;
    PacketData.bHasTimeLimit = Pkt->HasTimeLimit;
    PacketData.TimeLimitSeconds = Pkt->TimeLimitSeconds;
    PacketData.bIsTracking = Pkt->bIsTracking;

    // 3. 미션 목록 가공: 서버 ID(int32)를 클라이언트 ID(FName)로 변환하며 리스트화
    for (int32 i = 0; i < Pkt->MissionCount; ++i)
    {
        FMissionInfo MissionData;
        // 유틸 함수를 사용해 서버 ID를 기획 데이터 키(FName)로 매핑
        MissionData.MissionID = IntToMissionID(Pkt->Missions[i].MissionID);
        MissionData.CurrentCount = Pkt->Missions[i].CurrentCount;
        MissionData.RequiredCount = Pkt->Missions[i].RequiredCount;

        PacketData.Missions.Add(MissionData);
    }

    // 4. 가공 완료된 데이터를 퀘스트 전용 처리 큐에 적재
    QuestStartQueue.Enqueue(PacketData);
});

1-3. Tick 기반 데이터 갱신 및 브로드캐스트

게임 스레드의 Tick에서 큐에 쌓인 데이터를 소비하며 실제 런타임 인스턴스를 생성하고 UI에 이벤트를 전파합니다.

퀘스트 저널은 현재 진행 중인 퀘스트들을 카테고리(지역)별로 정리하고, 선택한 퀘스트의 상세 설명, 미션 목록, 보상을 보여주는 메인 UI입니다.

리스트, 카테고리, 상세 패널은 모두 퀘스트 서브시스템을 통해 데이터를 조회하며, OnQuestStarted 등의 델리게이트를 구독하여 서버 상태와 실시간으로 동기화됩니다.

4-1. 루트 저널 위젯: 델리게이트 구독 및 패널 연결

void UQuestJournalWidget::NativeConstruct()
{
    Super::NativeConstruct();
    QuestManager = GetGameInstance()->GetSubsystem<UQuestManageSubSystem>();

    // 서브시스템의 상태 변화 델리게이트 구독
    QuestManager->OnQuestStarted.AddDynamic(this, &UQuestJournalWidget::OnQuestStarted);
    QuestManager->OnQuestUpdated.AddDynamic(this, &UQuestJournalWidget::OnQuestUpdated);
    QuestManager->OnQuestCompleted.AddDynamic(this, &UQuestJournalWidget::OnQuestCompleted);

    if (QuestJournal_List)
    {
        QuestJournal_List->OnQuestSelected.AddDynamic(this, &UQuestJournalWidget::OnQuestSelected);
    }
}

4-2. 카테고리별 리스트 구성 (Region 기반 그룹핑)

리스트 위젯은 QuestID로 정적 데이터를 조회하여 Region(지역) 정보를 얻고, 이를 기준으로 카테고리를 동적 생성하거나 기존 카테고리에 아이템을 분류합니다.

void UQuestJournalListWidget::AddQuest(FName QuestID)
{
    const FQuestRow* QuestRow = QuestManager->GetQuestData(QuestID);
    if (!QuestRow) return;
    
    // 지역별 카테고리 맵핑 및 동적 위젯 생성
    if (CategoryMap.Contains(QuestRow->Region))
    {
        CategoryMap[QuestRow->Region]->AddCategoryItem(QuestID);
    }
    else
    {
        auto NewCategory = CreateWidget<UQuestJournalListCategoryWidget>(this, CategoryClass);
        NewCategory->Setup(QuestID, OnQuestSelected);
        CategoryMap.Add(QuestRow->Region, NewCategory);
        VerticalBox_CategoryBox->AddChild(NewCategory);
    }
    SortQuestItems(); // 기획 데이터의 정렬 순서 적용
}

4-3. 상세 패널: 정적 데이터와 런타임 상태의 결합

상세 패널은 DataTable의 데이터와 ActiveQuests의 진행도 정보를 실시간으로 조합하여 출력합니다.

void UQuestJournalDetailWidget::ShowDetail(FName QuestID)
{
    if (CurrentQuestID == QuestID) return;
    
    auto* QuestManager = GetGameInstance()->GetSubsystem<UQuestManageSubSystem>();
    if (!QuestManager) return;

    // 1. 정적 기획 데이터(DataTable) 조회
    const FQuestRow* SelectedQuestData = QuestManager->GetQuestData(QuestID);
    if (!SelectedQuestData) return;
    
    CurrentQuestID = QuestID;

    // 2. 기본 정보 갱신 (아이콘, 타이틀, 설명)
    if (const auto Icon = QuestManager->GetQuestIcon(SelectedQuestData->Type))
    {
        Image_QuestIcon->SetVisibility(ESlateVisibility::Visible);
        Image_QuestIcon->SetBrushFromAtlasInterface(Icon);
    }

    TextBlock_QuestTitle->SetText(SelectedQuestData->Title);
    TextBlock_QuestDescription->SetText(SelectedQuestData->Description);

    // 3. 기존 리스트 클리어
    VerticalBox_MissionContainer->ClearChildren();
    HorizontalBox_RewardBox->ClearChildren();

    // 4. 서버로부터 동기화된 런타임 인스턴스 정보 조회
    const FQuestInstance* ActiveQuest = QuestManager->GetActiveQuest(QuestID);
    if (!ActiveQuest) return;

    // 5. 미션 위젯 동적 생성 및 진행도 반영
    for (const auto& MissionPair : ActiveQuest->MissionInstances)
    {
        if (UJournalMissionWidget* MissionWidget = CreateWidget<UJournalMissionWidget>(this, MissionWidgetClass))
        {
            // 정적 미션 데이터 + 서버의 진행 수치 전달
            const FMissionRow* MData = QuestManager->GetMissionData(MissionPair.Key);
            MissionWidget->InitMission(MData, MissionPair.Value.CurrentCount, MissionPair.Value.RequiredCount);
            VerticalBox_MissionContainer->AddChildToVerticalBox(MissionWidget);
        }
    }

    // 6. 보상 정보 구성
    TArray<FQuestRewardInfo> Rewards = QuestManager->GetQuestRewardInfo(QuestID);
    for (const FQuestRewardInfo& Reward : Rewards)
    {
        if (UQuestRewardItemWidget* RewardWidget = CreateWidget<UQuestRewardItemWidget>(this, RewardWidgetClass))
        {
            RewardWidget->SetReward(Reward);
            HorizontalBox_RewardBox->AddChildToHorizontalBox(RewardWidget);
        }
    }
}

4-4. 퀘스트 트래킹 상태 변경 (서버 ↔ 클라이언트 플로우)

체크박스를 통한 트래킹 요청 시, 클라이언트가 즉시 UI를 변경하지 않고 서버의 판단을 기다립니다. 서버에서 트래킹 가능 여부를 판단해 패킷을 보내면, 서브시스템의 델리게이트를 통해 저널 아이콘과 트래커 리스트가 동시에 동기화됩니다.

1) 저널 아이템 위젯: 체크박스 바인딩 및 동기화

void UQuestJournalListCategoryItemWidget::SetupItem(FName QuestID)
{
// 1. 초기 트래킹 상태 설정
bool bIsCurrentlyTracking = QuestManager->IsQuestTracking(QuestID);
CheckBox_IsTracking->SetCheckedState(bIsCurrentlyTracking ? ECheckBoxState::Checked : ECheckBoxState::Unchecked);

// 2. 사용자의 체크 조작 이벤트 바인딩
CheckBox_IsTracking->OnCheckStateChanged.AddDynamic(this, &UQuestJournalListCategoryItemWidget::OnTrackingStateChanged);

// 3. 서버 응답 시 UI를 갱신해줄 델리게이트 구독
if (auto QM = GetGameInstance()->GetSubsystem<UQuestManageSubSystem>())
{
    QM->OnQuestTrackingChanged.AddDynamic(this, &UQuestJournalListCategoryItemWidget::SyncTrackingState);
}

}

// [클라이언트 -> 서버 요청]
void UQuestJournalListCategoryItemWidget::OnTrackingStateChanged(bool bIsChecked)
{
// 서버에 트래킹 상태 변경 패킷 요청 전송
    QuestManager->SetQuestTracking(TargetQuestID, bIsChecked);
}

// [서버 패킷 도착 -> UI 갱신]
void UQuestJournalListCategoryItemWidget::SyncTrackingState(FName QuestID, bool bIsTracking)
{
if (QuestID == TargetQuestID)
{
CheckBox_IsTracking->SetCheckedState(bIsTracking ? ECheckBoxState::Checked : ECheckBoxState::Unchecked);
}
}

2) 퀘스트 트래커(HUD): 실시간 리스트 갱신

저널뿐만 아니라 HUD에 항상 떠있는 QuestTracker 위젯도 동일한 델리게이트를 통해 리스트를 즉시 업데이트합니다.

void UQuestTrackerWidget::OnQuestTracking(FName QuestID, bool bIsTracking)
{
    if (bIsTracking)
    {
        AddQuestItem(QuestID); // 트래커 리스트에 추가
    }
    else
    {
        RemoveQuestItem(QuestID); // 트래커 리스트에서 제거
    }

    SortQuestItems(); // 트래킹 순서에 따른 리스트 재정렬
}

NPC 머리 위에는 해당 NPC와 연관된 퀘스트 상태(수락 가능 / 완료 가능)를 표시하는 아이콘이 출력됩니다.

서버 패킷을 바탕으로 QuestManageSubSystem이 관리하는 상태 맵을 조회하여, 현재 NPC가 가져야 할 가장 우선순위가 높은 아이콘을 동적으로 결정합니다.

[퀘스트 상태에 따른 NPC 헤드 UI 변화]

5-1. 상태 결정 로직

한 NPC가 여러 퀘스트를 가질 수 있으므로, '완료 가능' 상태를 '수락 가능'보다 우선하여 표시하도록 설계했습니다.
서버에서 받은 패킷을 바탕으로, 퀘스트 서브 시스템이 NpcToAcceptableQuestsMap, NpcToACompletableQuestsMap 을 업데이트합니다.

EUEQuestState UQuestManageSubSystem::GetBestQuestStateForNPC(FName NpcID)
{
    // 1순위: 완료 가능한 퀘스트가 있는지 확인
    if (NpcToACompletableQuestsMap.Contains(NpcID))
    {
        return EUEQuestState::Completed;
    }

    // 2순위: 수락 가능한 퀘스트가 있는지 확인
    if (NpcToAcceptableQuestsMap.Contains(NpcID))
    {
        return EUEQuestState::Acceptable;
    }
    
    return EUEQuestState::None;
}

5-2. NPC 액터: 이벤트 구독 및 상태 갱신

NPC 액터는 퀘스트 시스템의 다양한 이벤트를 구독하며, 상태 변경이 감지될 때마다 RefreshQuestIcon()을 호출하여 자신의 헤드 UI를 동기화합니다.

void ANPCBase::RefreshQuestIcon()
{
    if (auto* QM = GetQuestManager())
    {
        // 최우선 상태를 계산하여 위젯 갱신
        EUEQuestState BestState = QM->GetBestQuestStateForNPC(NpcID);
        StatusWidget->UpdateStatus(BestState);
    }
}

5-3. 헤드 UI 위젯: 데이터 에셋 기반 비주얼라이징

UI 위젯은 오직 서브시스템이 DataAsset(DA)으로부터 가져온 리소스를 화면에 그리는 역할만 수행합니다.

void UNPCStatusWidget::UpdateStatus(EUEQuestState State)
{
    if (State != EUEQuestState::None)
    {
        Image_QuestIcon->SetVisibility(ESlateVisibility::Visible);
        // 서브시스템을 통해 캐싱된 데이터 에셋의 아이콘 로드
        auto Icon = QuestManager->GetQuestStateIcon(State);
        Image_QuestIcon->SetBrushFromAtlasInterface(Icon);
    }
    else
    {
        Image_QuestIcon->SetVisibility(ESlateVisibility::Collapsed);
    }
}

// [Subsystem] 데이터 에셋으로부터 스프라이트 조회
UPaperSprite* UQuestManageSubSystem::GetQuestStateIcon(EUEQuestState State)
{
    if (!CachedNPCVisualDataAsset) return nullptr;

    auto Icon = CachedNPCVisualDataAsset->QuestStateIconMap.FindRef(State);
    return Icon.IsValid() ? Icon.Get() : Icon.LoadSynchronous();
}

6-1. FText 기반 설계 및 현지화

[로컬라이제이션 대시보드를 통한 텍스트 수집 및 관리]

// 1. NPC 상호작용 데이터: NPC 이름 및 기본 대사
USTRUCT(BlueprintType)
struct RPG_API FNPCInteractionRow : public FTableRowBase
{
    GENERATED_BODY()
    
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName NPCID;
    
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FText NPCName;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FText DefaultDialog;
};

// 2. NPC 퀘스트 대화 데이터 구조체
USTRUCT(BlueprintType)
struct RPG_API FNPCDialogRow : public FTableRowBase
{
    GENERATED_BODY()

public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName DialogID;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FText DialogText;
};