개발 블로그를 github로 이전하게 되었습니다.

Copyright (c) Microsoft Corporation. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 모든 코드는 표기된 라이센스를 따르며, 설명을 위해 수정된 사항이 있습니다

원문 출처

https://github.com/microsoft/STL/blob/main/stl/inc/iterator https://github.com/microsoft/STL/blob/main/stl/inc/xutility https://learn.microsoft.com/ko-kr/cpp/standard-library/reverse-iterator-class?view=msvc-170 https://learn.microsoft.com/ko-kr/cpp/standard-library/iterator?view=msvc-170 https://en.cppreference.com/cpp/iterator/reverse_iterator

STL vector에서 rbegin()으로 리턴받은 iterator를 인자로 사용하여 erase()를 시도했지만 타입이 맞지 않는다는 에러가 발생했습니다.

begin()은 vector<T>::iterator을 반환하고 rbegin()은 vector<T>::reverse_iterator를 반환하고 있었습니다. 또한, 연산 방향이나 종료 지점에도 차이가 존재했습니다.

그럼 reverse_iterator로 erase()를 실행하려면 어떻게 해야할까요?

먼저 reverse_iterator에 대해 알아봤습니다.

https://github.com/microsoft/STL/blob/main/stl/inc/xutility

reverse_iterator는 기본적으로 사용하던 양방향 반복자(Bidirectional Iterator, BidIt)를 기본적으로 가지고 있으며, 이를 랩핑하여 구현하고 있습니다.

_NODISCARD _CONSTEXPR17 _BidIt base() const noexcept(...) {
    return current; // 내부에 들고 있던 원본 iterator를 그대로 반환
}

base()는 이 current(기존 iterator)를 그대로 반환합니다.

그럼 rit.base()를 사용하면 erase()를 정상적으로 호출할 수 있을까요? 호출은 할 수 있지만 의도와는 다르게 작동합니다. *rit은 current에서 왼쪽 주소를 역참조할 뿐, 실제 물리적 주소는 의도와 다르기 때문입니다.

_NODISCARD _CONSTEXPR17 reference operator*() const noexcept(...) {
    _BidIt _Tmp = current; // 현재 들고 있는 iterator(current)를 복사
    return *--_Tmp;        // 복사본을 1칸 앞으로(--) 이동시킨 후 역참조(*)해서 반환
}

따라서, 역참조한 주소의 데이터를 지우고 싶다면 전후에 값을 왼쪽으로 옮겨줘야 합니다.

소스코드 및 결과

int main() {
    vector<int> v = { 10, 20, 30, 40, 50 };

    // 역방향 순회 중 '30'을 삭제하고 싶은 경우
    for (auto rit = v.rbegin(); rit != v.rend(); ) {
        if (*rit == 30) {
            cout << "반복자를 이동시키지 않았을 때, 반환되는 역참조 값: " << *rit.base() << '\n';

            // rit.base()는 30이 아닌 '40'의 위치를 가리키고 있음
            // 따라서 next(rit).base()를 전달해야 정확히 '30' 위치의 iterator가 됨
            auto it = std::next(rit).base();

            // erase는 삭제 후 다음 위치의 정방향 iterator를 반환하므로,
            // 이를 다시 reverse_iterator로 감싸서 갱신
            rit = vector<int>::reverse_iterator(v.erase(it));
        }
        else {
            ++rit;
        }
    }

    // 결과 출력: 10 20 40 50
    for (int n : v) cout << n << " ";
}

교점에 별 만들기 https://school.programmers.co.kr/learn/courses/30/lessons/87377

교점을 찾은 후 출력하는 문제였습니다. 처음에는 가감법을 사용해서 풀었지만, 예외 처리와 계수항을 맞추기 위한 과정들이 너무 복잡했습니다. 또한, 들어오는 값의 범위가 -100k ~ 100k이다보니 int를 가볍게 뛰어넘는 값들이 사용됐습니다. 이는 std::lcm을 사용할 때 문제를 발생시켰습니다.

더 효율적으로 정답을 찾을 수 있는 방법은 크래머 공식을 사용하는 것이었습니다.

행렬식(Determinant, $\det$)

크래머 공식에 대해 이해하려면 먼저 행렬식에 대해 이해해야 합니다.

(중요)아래 글은 행렬식에 대한 정확한 정의가 아니며, 제가 행렬식을 이해하기 위한 과정입니다. 틀린점에 대해서 피드백을 주시면 감사합니다.

먼저, 행렬식은 정사각 행렬을 스칼라로 바꾸어 주는 함수입니다.

제가 이해한 바로는 행렬식의 결과 값이 모눈종이(좌표계) 격자를 찌그러트리고 늘렸을 때, 변형된 모눈종이가 원본에 비해 얼만큼 변했는가?에 가까운 것 같습니다. 즉, 행렬이 공간을 얼마나 변형시키는가(길이/면적/부피 및 방향의 변화 비율)를 나타내는 수입니다.

쉽게 이해하기 위해 직선을 사용했습니다(이미지의 좌표평면은 2차원이지만, 1차원이라고 생각하고 봐주셔야 합니다). 좌측의 공간에 대해 $det=2$을 적용한 이미지를 예시로 보겠습니다.

이미지 처럼 공간 자체가 확대되었기 때문에, 직선(빨간선)은 실제로 2배 길어진 16의 길이를 갖게 됩니다. (0, 8)까지의 무수한 점의 위치가 (0, 16)까지로 변형되었기 때문입니다. 하지만, 변형된 공간의 관점에서 봤을 때는 여전히 좌표 값은 변하지 않은 상태입니다. 좌표는 기저벡터를 몇개 사용했는가를 의미하기 때문입니다.

이때, 주의해야 할 점은 1개의 공간만 가지고는 어떻게 변형되었는지는 정확히 알 수 없는 것에 유의해야 합니다. 또한, n차원의 길이/면적/부피가 몇 배가 되었는지에 대해 알려주는 것이기 때문에 모든 방향에 $det$을 곱하는 것이 아닙니다.

예를 들어서, 2차원 공간의 사각형에 $det=2$라고 해서 두 방향의 기저에 모두 2를 곱하면 사각형의 넓이는 4배가 됩니다. (그래서 위 예시 이미지를 x축으로만 늘린 것입니다)

또한, 하나의 원본을 기준으로 다른 공간과 비교했을 때 $det$을 통해 변형된 방향와 크기를 알 수 있습니다.

$det$의 부호

행렬식에서 $det$의 부호는 아래와 같은 규칙을 가집니다.

• $det > 0$ → 방향 유지
• $det < 0$ → 방향 반전
• $det = 0$ → 공간이 납작하게 찌그러짐

예를 들어서, $det = -2$인 경우에는 면적은 2배인데 방향이 반전된 것을 의미합니다.

중요한 것은 $det = 0$일때 입니다. 0이 되면 공간이 납작하게 찌그러진 것과 같이 되어 좌표축 하나가 의미를 잃게 됩니다.

행렬식 활용하기

위에서 행렬식은 공간을 얼마나 변형시키는가를 나타내는 수라고 말씀드렸습니다. 이 개념을 이용하면 평행사변형의 넓이도 아주 쉽게 이해할 수 있습니다. 가로와 세로가 각각 1인 단위 정사각형을 특정 행렬로 변환하면 새로운 평행사변형이 만들어지는데, 이때 변화된 넓이 자체가 바로 행렬식의 값($\det$)이 됩니다.

두 2차원 벡터 $a = (a_1, a_2)$와 $b = (b_1, b_2)$가 이루는 평행사변형의 넓이는 두 벡터의 외적 크기, 혹은 삼각함수를 이용해 계산할 수 있습니다.

$$\text{넓이} = \vert{}a_1 b_2 - a_2 b_1\vert{}$$

이 식을 $2 \times 2$ 행렬 형태로 쓴 것이 바로 행렬식입니다.

$$\det \begin{pmatrix} a_1 & b_1 \ a_2 & b_2 \end{pmatrix} = a_1 b_2 - a_2 b_1$$

이제 두 일차 방정식(직선)을 보겠습니다.

$$\begin{cases} a_1 x + b_1 y = c_1 \ a_2 x + b_2 y = c_2 \end{cases}$$

이 방정식의 목표는 두 직선이 만나는 교점 $(x, y)$를 찾는 것입니다. 이 방정식을 행렬 형태로 바꾸면 다음과 같습니다.

$$\begin{pmatrix} a_1 & b_1 \ a_2 & b_2 \end{pmatrix} \begin{pmatrix} x \ y \end{pmatrix} = \begin{pmatrix} c_1 \ c_2 \end{pmatrix}$$

이것을 벡터의 합 형태로 다시 풀어서 써보면

$$x \begin{pmatrix} a_1 \ a_2 \end{pmatrix} + y \begin{pmatrix} b_1 \ b_2 \end{pmatrix} = \begin{pmatrix} c_1 \ c_2 \end{pmatrix}$$

이 식을 말로 풀어보면 다음과 같습니다

기반이 되는 두 벡터 $A = \begin{pmatrix} a_1 \ a_2 \end{pmatrix}$와 $B = \begin{pmatrix} b_1 \ b_2 \end{pmatrix}$를 각각 $x$배, $y$배 늘려서 더했더니, 목표 벡터 $C = \begin{pmatrix} c_1 \ c_2 \end{pmatrix}$가 되었다. 이때 배율 $x$와 $y$는 얼마인가?"

즉, $det \ne 0$라는 것은 평행사변형이 생성된다는 것을 의미합니다. 반대로 0이 나온다면 교점이 생성되지 않았음을 의미합니다. 이를 활용해서 제가 예외 처리하기 위해 만들었던 복잡한 코드를 간편하게 해결할 수 있습니다.

크래머 공식을 사용해서 교점 찾기

방금 방법으로 교점 여부를 확인했다면, 크래머 공식을 통해 교점의 정확한 위치를 알아낼 수 있습니다.

다시, 두 개의 1차 함수(직선의 방정식)가 다음과 같이 주어졌다고 가정해 보겠습니다.

$$a_1 x + b_1 y = c_1$$ $$a_2 x + b_2 y = c_2$$

이를 행렬의 형태로 변환하면 다음과 같습니다.

$$\begin{pmatrix} a_1 & b_1 \ a_2 & b_2 \end{pmatrix} \begin{pmatrix} x \ y \end{pmatrix} = \begin{pmatrix} c_1 \ c_2 \end{pmatrix}$$

여기서 크래머 공식을 사용하면 행렬식만으로 교점 $(x, y)$를 쉽게 구할 수 있습니다.

1. 기본 행렬식 ($D$): $x, y$의 계수들로 이루어진 행렬식입니다.

   $$D = a_1 b_2 - a_2 b_1$$

2. $x$를 위한 행렬식 ($D_x$): 기본 행렬의 첫 번째 열(x의 계수)을 결과값 $c_1, c_2$로 바꾼 행렬식입니다.

   $$D_x = c_1 b_2 - c_2 b_1$$

3. $y$를 위한 행렬식 ($D_y$): 기본 행렬의 두 번째 열(y의 계수)을 결과값 $c_1, c_2$로 바꾼 행렬식입니다.
   $$D_y = a_1 c_2 - a_2 c_1$$

최종적으로 교점의 좌표는 각 변수의 행렬식을 기본 행렬식으로 나눈 값입니다.

$$x = \frac{D_x}{D}, \quad y = \frac{D_y}{D}$$

코드

bool inter(int idx1, int idx2, const vector<vector<int>>& line, arg& args) {
    // 오버플로우 방지를 위해 long long 변환
    long long A = line[idx1][0], B = line[idx1][1], E = line[idx1][2];
    long long C = line[idx2][0], D = line[idx2][1], F = line[idx2][2];

    // 1. 분모(det) 계산
    long long det = A * D - B * C;

    // 평행하거나 일치하면 교점 없음
    if (det == 0) return false;

    // 2. 분자 계산
    long long num_x = B * F - E * D;
    long long num_y = E * C - A * F;

    // 3. 정수로 딱 나누어떨어지는지 확인
    if (num_x % det != 0 || num_y % det != 0) return false;

    // 4. 정수 교점 저장
    args.x = num_x / det;
    args.y = num_y / det;

    return true;
}

기존처럼 LCM을 구해서 계수를 맞추거나 $x, y$ 계수가 $0$일 때 분기 처리를 수십 줄 작성하는 대신, 이 공식 하나로 수십 줄의 코드를 몇 줄로 축소하고 안전하게 처리할 수 있었습니다.

Copyright (c) Microsoft Corporation. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 모든 코드는 표기된 라이센스를 따르며, 설명을 위해 수정된 사항이 있습니다

해시 충돌에 대한 글: https://en.wikipedia.org/wiki/Hash_table https://preamtree.tistory.com/20

해시 충돌이 발생하면 개방 주소법이나 체이닝을 통해 해결한다는 것은 익히 들어 알고 있을 것입니다. 그런데 문득 이런 생각이 들었습니다. 충돌이 발생한다는 것은 해시 함수가 return하는 해시 값이 동일하다는 것인데, 어떻게 프로그램이 원하는 값을 정확히 찾아올 수 있냐는 것입니다.

해시 값만 사용하는 것이 아님

해시 테이블은 해시 값 하나만 믿고 데이터를 찾지 않습니다. 충돌이 발생하면 ① 충돌을 해결하는 규칙(개방 주소법 또는 체이닝)에 따라 보관해 두고, 나중에 값을 찾을 때는 ② 주소를 따라간 뒤 "진짜 내가 찾던 키(Key)가 맞는지" 실제 키 값을 직접 비교하는 과정을 거칩니다.

구체적으로 두 방식이 충돌을 해결하고 원하는 값을 찾아가는 과정은 다음과 같습니다.

1. 개방 주소법 (Open Addressing)

개방 주소법에서는 해시 테이블의 각 칸에 데이터(Key, Value)가 직접 들어갑니다.

동작 방식

예를 들어 Key A와 Key B가 모두 해시 값 3을 출력했다고 가정해 보겠습니다.

• 저장할 때:

1. Key A가 먼저 들어와 index 3에 저장됩니다.
2. Key B가 들어왔는데 index 3이 차 있습니다.
3. 약속된 규칙(예: 다음 칸으로 이동)에 따라 빈 칸인 index 4에 Key B를 저장합니다.

• 찾아갈 때 (Key B를 검색하는 과정):

1. Key B를 해시 함수에 넣어 index 3을 얻습니다.
2. index 3으로 가보니 Key A가 들어있습니다. "해시 값은 맞지만, 진짜 키(Key B)가 아니네?" 하고 확인합니다.
3. 저장할 때 썼던 규칙 그대로 다음 칸(index 4)으로 이동합니다.
4. index 4에서 Key B를 발견하고, 키가 일치하므로 해당 값을 반환합니다.

2. 체이닝 (Chaining)

체이닝 방식에서 해시 테이블의 각 칸은 데이터 자체가 아니라, 연결 리스트의 첫 번째 노드를 가리키는 포인터를 가집니다.

동작 방식

마찬가지로 Key A와 Key B의 해시 값이 둘 다 3인 경우입니다.

• 저장할 때:

1. Key A가 들어와 index 3번 방의 리스트에 첫 번째 노드로 들어갑니다. ([Key A]연결)
2. Key B가 들어오면 index 3번 방의 리스트 끝(또는 앞)에 추가로 연결합니다. ([Key A] -> [Key B] 연결)

• 찾아갈 때 (Key B를 검색하는 과정):

1. Key B를 해시 함수에 넣어 index 3을 얻습니다.
2. index 3번 방으로 찾아가 연결된 리스트를 첫 번째 노드부터 순회합니다.
3. 첫 노드 Key A 확인 $\rightarrow$ "내가 찾던 키가 아님"
4. 다음 노드 Key B 확인 $\rightarrow$ "진짜 키가 맞음!" $\rightarrow$ 검색 성공

결국, 해시 충돌이 발생하더라도 원하는 값을 정확히 찾을 수 있는 이유는 "해시 값(주소)"뿐만 아니라 "원래의 Key 값"도 함께 저장하여 최종 비교하기 때문입니다. 단순하면서도 당연한 방법이었습니다. 그럼 자주 사용해왔던 unordered_map은 내부적으로 어떻게 동작할까요? 또한, 체이닝을 사용하는지 개방 주소법을 사용하는지도 알아봤습니다.

C++ std::unordered_map

unordered_map은 체이닝(Chaining) 방식을 사용합니다. 각 버킷이 단방향 연결 리스트(Singly Linked List) 형태의 노드들을 가리키는 구조로 구현되어 있습니다. *여기서 중요한 것은 해시 충돌 여부와 상관없이 데이터가 들어오면 무조건 리스트 노트가 동적 할당되어 생성된다는 것입니다. *

template <class _Keyty, class _Mappedty>
    pair<iterator, bool> _Insert_or_assign(_Keyty&& _Keyval_arg, _Mappedty&& _Mapval) {
        const auto& _Keyval   = _Keyval_arg;

        // [해시 값 계산] 
        // 입력받은 키(_Keyval)를 해시 함수에 넣어 해시 숫자(_Hashval)를 얻어냅니다.
        const size_t _Hashval = this->_Traitsobj(_Keyval);

        // [기존 키 존재 여부 확인 및 리스트 순회]
        // _Find_last 함수를 통해 해당 해시값의 버킷으로 찾아가 연결 리스트를 뒤져서
        // 이미 똑같은 키(_Keyval)가 존재하는지 검사합니다.
        auto _Target          = this->_Find_last(_Keyval, _Hashval);

        // 만약 이미 일치하는 키가 존재한다면 (해시 충돌이 아니라 아예 동일한 키인 경우)
        if (_Target._Duplicate) {
            // 새 노드를 만들지 않고, 기존 노드의 Value(second) 값만 새로 덮어씌우고 종료합니다.
            _Target._Duplicate->_Myval.second = _STD forward<_Mappedty>(_Mapval);
            return {this->_List._Make_iter(_Target._Duplicate), false};
        }

        // 최대 사이즈(load factor 등)를 초과했는지 체크합니다.
        this->_Check_max_size();

        // [새로운 노드 생성 (해시 충돌 여부와 상관없이 무조건 생성)]
        // invalidates _Keyval:
        // _List_node_emplace_op2라는 객체를 통해 새로운 리스트 '노드(Node)'를 동적 할당하여 생성합니다.
        // 이 노드 안에는 키(_Keyval_arg)와 값(_Mapval)이 담기게 됩니다.
        _List_node_emplace_op2<_Alnode> _Newnode(
            this->_Getal(), _STD forward<_Keyty>(_Keyval_arg), _STD forward<_Mappedty>(_Mapval));

        // 만약 요소를 추가하기 전에 해시 테이블의 크기(버킷 수)를 늘려야 한다면 재해싱(Rehash)을 수행합니다.
        if (this->_Check_rehash_required_1()) {
            this->_Rehash_for_1();
            // 버킷 개수가 바뀌었으므로, 새로 만든 노드가 들어갈 위치를 다시 찾습니다.
            _Target = this->_Find_last(_Newnode._Ptr->_Myval.first, _Hashval);
        }

        // [체이닝 (리스트에 노드 연결)]
        // _Insert_new_node_before 함수를 호출하여, 방금 생성한 새 노드(_Newnode._Release())를
        // 해당 해시값(_Hashval) 버킷이 가리키는 연결 리스트의 특정 위치(_Target._Insert_before)에 
        // 체이닝(연결) 한 뒤 iterator를 반환합니다.
        return {this->_List._Make_iter(
                    this->_Insert_new_node_before(_Hashval, _Target._Insert_before, _Newnode._Release())),
            true};
    }

_NODISCARD mapped_type& at(const key_type& _Keyval) {
        // [해시 계산 및 타겟 탐색]
        // _Traitsobj(_Keyval)을 통해 해시값을 먼저 구합니다.
        // 그리고 부모 클래스(_Hash)의 _Find_last 함수에 '찾고자 하는 원본 키(_Keyval)'와 '해시값'을 같이 넘깁니다.
        // _Find_last 내부에서는 해시값으로 해당 버킷을 찾은 뒤, 버킷에 연결된 단방향 연결 리스트를 순회하며
        // 리스트 내 각 노드의 키와 전달한 '_Keyval'이 정확히 일치(key_equal)하는지 하나씩 비교합니다.
        const auto _Target = this->_Find_last(_Keyval, this->_Traitsobj(_Keyval));

        // [실제 키 일치 확인]
        // 해시값이 같고, 실제 키 값까지 정확히 일치하는 진짜 노드를 찾았다면 
        // _Target._Duplicate에 그 노드의 포인터가 담겨서 돌아옵니다.
        if (_Target._Duplicate) {
            // 찾은 노드의 실제 Value(_Myval.second)를 반환합니다.
            return _Target._Duplicate->_Myval.second;
        }

        // [탐색 실패]
        // 해시값이 같은 버킷으로 갔지만, 연결 리스트를 다 뒤져봐도
        // 실제 키 값이 일치하는 노드가 없다면 예외(out_of_range)를 던집니다.
        _Xout_of_range("invalid unordered_map<K, T> key");
    }

체이닝 과정을 확인하기 위해 디버깅 모드와 아래 소스코드를 활용했습니다.

#include <iostream>
#include <unordered_map>
#include <string>

// 1. 해시 충돌을 발생시키는 커스텀 해시 함수
struct CollisionHash {
    size_t operator()(const int& key) const {
        return 1; // 어떤 키가 들어와도 무조건 해시값 1을 반환! (같은 방 배정)
    }
};

// 2. 키 비교 과정을 관찰하기 위한 커스텀 동등성 비교 함수
struct TraceEqual {
    bool operator()(const int& lhs, const int& rhs) const {
        // 🔴 [디버깅 정지 지점 1]
        bool result = (lhs == rhs);
        std::cout << "[Trace] 키 비교 중: 기존 노드 키(" << lhs << ") vs 찾는 키(" << rhs << ") -> " << (result ? "일치" : "불일치") << "\n";
        return result;
    }
};

int main() {
    std::unordered_map<int, std::string, CollisionHash, TraceEqual> my_map;

    std::cout << "--- 데이터 삽입 시작 ---\n";
    my_map[10] = "Apple";  // 버킷 1에 삽입 (길이 1)

    // 🔴 [디버깅 정지 지점 2] 삽입 시 순회 확인을 원한다면 여기서 Step Into(F11)를 해보세요
    my_map[20] = "Banana"; // 해시가 1이므로 충돌! 리스트를 뒤지며 10과 20을 비교함
    my_map[30] = "Cherry"; // 해시가 1이므로 충돌! 리스트를 뒤지며 10, 20과 30을 순차적으로 비교함

    std::cout << "\n--- 데이터 탐색 시작 ---\n";
    // 🔴 [디버깅 정지 지점 3] 탐색 시 순회 확인을 원한다면 여기서 Step Into(F11)를 해보세요
    std::string value = my_map.at(30);
    std::cout << "찾은 값: " << value << "\n";

    return 0;
}

unordred_map은 체이닝을 사용하기 때문에 많은 데이터가 들어왔을 때, 다른 컨테이너에 비해 성능이 그다지 좋지 않습니다(캐시 효율성 문제). 그런데도 왜 체이닝을 사용했는지 이유가 궁금했습니다. 제 궁금증에 대한 답변은 아래 링크에서 얻을 수 있었습니다.

https://www.reddit.com/r/cpp/comments/sprdom/why_does_unordered_map_use_chaining_to_prevent/

번역하자면 다음과 같습니다.

1. 빈 자리와 이미 차 있는 자리를 구분할 필요가 있습니다.
2. 해시 테이블을 기본 생성자(default constructor)가 있는 타입으로만 제한하여 모든 배열 요소를 미리 생성해 두거나, 아니면 일부 요소는 객체이고 나머지는 가공되지 않은 순수 메모리(raw memory)로 이루어진 배열을 유지해야 합니다.
3. 개방 주소법(Open addressing)은 충돌 관리를 어렵게 만듭니다. 해시 코드가 이미 차 있는 위치에 매핑되는 요소를 삽입하려는 경우, 다음으로 어디를 시도해야 할지 알려주는 정책이 필요합니다. 이는 이미 해결된 문제이지만, 가장 잘 알려진 솔루션들도 복잡합니다.
4. 충돌 관리는 요소를 삭제(erase)할 수 있을 때 특히 더 복잡해집니다. (이와 관련해서는 크누스(Knuth) 교수의 논의를 참조하세요.) 표준 라이브러리용 컨테이너 클래스는 당연히 삭제를 허용해야 합니다.
5. 개방 주소법을 위한 충돌 관리 방식들은 대체로 최대 N개의 요소를 담을 수 있는 고정 크기 배열을 전제로 하는 경향이 있습니다. 표준 라이브러리용 컨테이너 클래스는 사용 가능한 메모리 한도 내에서 새 요소가 삽입될 때마다 필요한 만큼 크기가 늘어날 수 있어야 합니다.

현대에는 Swiss Map같은 방식을 이용해서 캐시 효율 문제를 해결했다고 합니다.

cppreference.com - priority_queue cppreference.com - make_heap cppreference.com - Compare

라이선스 표기

Copyright (c) Microsoft Corporation. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 모든 코드는 표기된 라이센스를 따르며, 설명을 위해 수정된 사항이 있습니다

C++ 코테와 개발을 하다 갑자기 궁금한 점이 생겼습니다. sort와 priority_queue에 동일한 비교 함수(예: greater<int>)를 넘겨주었는데, 출력되는 데이터의 정렬 순서가 정반대로 나오는 현상입니다.

• sort(..., std::greater<int>()) $\rightarrow$ 내림차순 (큰 값부터)
• priority_queue<int, vector<int>, greater<int>> $\rightarrow$ 오름차순 (작은 값부터 차례대로 top())

동일한 비교 함수(예: less<> 또는 a < b)를 전달했을 때 결과가 반대로 나오는 핵심 이유는 두 자료구조가 비교 함수의 결과를 해석하고 활용하는 목적이 정반대이기 때문입니다.

sort()는 배열을 선형적으로 정렬하기 위해 비교 함수를 '선행 조건'으로 사용하는 반면, priority_queue는 트리(Heap)의 루트에 최댓값을 올리기 위해 비교 함수를 '우선순위 역전 조건'으로 사용합니다.

1. sort의 선형 정렬과 엄격한 약한 순서(Strict Weak Ordering)

sort는 컨테이너의 요소들을 선형적으로 정렬합니다. C++의 모든 정렬 알고리즘은 엄격한 약한 순서(Strict Weak Ordering) 라는 수학적 규칙을 기반으로 동작합니다.

Strict Weak Ordering에 대해 요약한 블로그 글 https://hanarotg.tistory.com/224

sort에 전달된 비교 함수 comp(a, b)가 true를 반환한다는 것은 "정렬된 결과에서 a가 b보다 무조건 앞에 위치해야 한다"는 것을 의미합니다.

• less<T> 적용 시: 내부적으로 a < b를 평가합니다. 이 값이 true라면 더 작은 요소가 앞에 배치되므로 최종적으로 오름차순 정렬이 됩니다.
• greater<T> 적용 시: 내부적으로 a > b를 평가합니다. 더 큰 요소가 앞에 배치되어야 하므로 최종적으로 내림차순 정렬이 됩니다.

즉, sort에서 비교 연산자는 요소들의 최종적인 선형 배치 순서 그 자체를 결정합니다.

2. priority_queue의 힙(Heap) 구성 원리

반면 priority_queue는 내부적으로 트리 기반의 힙(Heap) 자료구조를 유지하기 위해 비교 연산자를 사용합니다. 컨테이너 어댑터인 priority_queue는 요소 삽입과 삭제 시 내부적으로 <algorithm> 헤더의 push_heap과 pop_heap 알고리즘을 호출합니다.

힙을 구성할 때 C++ 표준 알고리즘은 부모 노드와 자식 노드를 비교합니다. 이때 비교 함수 comp(parent, child)가 true를 반환하면, 부모 노드가 자식 노드보다 우선순위가 낮다고 판단하여 두 노드의 위치를 교환(Swap) 합니다. 즉, 자식 노드를 부모 위치로 끌어올립니다.

• less<T> 적용 시: parent < child가 true일 때 위치를 바꿉니다. 작은 값이 아래로 내려가고 큰 값이 루트 노드(Top)로 올라가게 됩니다. 그 결과, 가장 큰 값이 최상단에 위치하는 최대 힙(Max-Heap) 이 형성됩니다.
• greater<T> 적용 시: parent > child가 true일 때 위치를 바꿉니다. 큰 값이 아래로 내려가고 작은 값이 루트 노드로 올라갑니다. 결과적으로 가장 작은 값이 최상단에 위치하는 최소 힙(Min-Heap) 이 형성됩니다.

sort()가 힙 정렬을 사용하게 되면 priority_queue와는 어떤 차이가 있을까요?

sort()는 최악의 상황에서도 $O(N \log N)$의 시간 복잡도를 보장하면서, 평균적인 성능을 극대화하기 위해 하이브리드 정렬 알고리즘을 사용합니다. 퀵, 힙, 삽입 정렬을 기준에 따라 사용하게 되는데, 퀵 정렬을 사용하다가 재귀 깊이가 임계점을 초과하면 힙 정렬로 즉시 전환하게 됩니다.

//sort()
//<algorithm>
template <class _RanIt, class _Pr>
_CONSTEXPR20 void _Sort_unchecked(_RanIt _First, _RanIt _Last, _Iter_diff_t<_RanIt> _Ideal, _Pr _Pred) {
    // order [_First, _Last)
    for (;;) {
        if (_Last - _First <= _ISORT_MAX) { // small
            _STD _Insertion_sort_unchecked(_First, _Last, _Pred);
            return;
        }

        // 💡 [분기점] 재귀 깊이 임계값을 초과했을 때 (힙 정렬로 전환)
        // 피벗이 한쪽으로 계속 치우쳐서 퀵 정렬이 최악의 시간복잡도 O(N^2)로 향하고 있다면,
        // 허용된 분할 횟수(_Ideal)가 0 이하가 됩니다. 
        // 이때 즉시 '최소 힙'을 만들고 뒤집어서 강제로 정렬을 마칩니다.
        if (_Ideal <= 0) { // heap sort if too many divisions
            _STD _Make_heap_unchecked(_First, _Last, _Pred); // 1단계: 힙 생성[cite: 1]
            _STD _Sort_heap_unchecked(_First, _Last, _Pred); // 2단계: 뒤에서부터 재배치[cite: 1]
            return;
        }

        auto _Mid = _STD _Partition_by_median_guess_unchecked(_First, _Last, _Pred);

        _Ideal = (_Ideal >> 1) + (_Ideal >> 2); // allow 1.5 log2(N) divisions


        if (_Mid.first - _First < _Last - _Mid.second) { 
            _STD _Sort_unchecked(_First, _Mid.first, _Ideal, _Pred);
            _First = _Mid.second; // 다음 루프에서는 우측 영역을 대상으로 시작
        } else { 
            _STD _Sort_unchecked(_Mid.second, _Last, _Ideal, _Pred);
            _Last = _Mid.first; // 다음 루프에서는 좌측 영역을 대상으로 시작
        }
    }
}

이때, 힙을 생성하는 과정은 priority_queue와 같은 방법을 사용합니다. (__msvc_heap_algorithm.hpp)

//priority_queue
//<queue>
void _Make_heap() {
    _STD make_heap(c.begin(), c.end(), _STD _Pass_fn(comp));
}

// __msvc_heap_algorithms.hpp
_EXPORT_STD template <class _RanIt, class _Pr>
_CONSTEXPR20 void make_heap(_RanIt _First, _RanIt _Last, _Pr _Pred) { // make [_First, _Last) into a heap
    _STD _Adl_verify_range(_First, _Last);

    // ★ 같은 함수를 사용하는 지점
    _STD _Make_heap_unchecked(_STD _Get_unwrapped(_First), _STD _Get_unwrapped(_Last), _STD _Pass_fn(_Pred));
}

//sort()
//<algorithm>
_CONSTEXPR20 void _Sort_unchecked(_RanIt _First, _RanIt _Last, _Iter_diff_t<_RanIt> _Ideal, _Pr _Pred) {
(...)
if (_Ideal <= 0) { // heap sort if too many divisions
            // ★ 같은 함수를 사용하는 지점
            _STD _Make_heap_unchecked(_First, _Last, _Pred); // 1단계: 힙 생성[cite: 1]
            _STD _Sort_heap_unchecked(_First, _Last, _Pred); // 2단계: 뒤에서부터 재배치[cite: 1]
            return;
        }
(...)
}

순서가 뒤집히는 분기점은 _Sort_heap_unchecked였습니다. 정렬이 완료된 후, 힙에 쌓인 데이터를 배열에 재배치할 때 차이가 발생합니다.

template <class _RanIt, class _Pr>
_CONSTEXPR20 void _Sort_heap_unchecked(_RanIt _First, _RanIt _Last, _Pr _Pred) {
    // 힙 구조가 완성된 상태에서 맨 마지막 원소(_Last - 1)부터 역방향으로 진행합니다.
    for (; 2 <= _Last - _First; --_Last) {

        // 핵심 분기점: 루트 노드(_First)에 있는 최우선순위 값을 
        // 배열의 맨 마지막 칸(_Last - 1)으로 이동시키고 영역을 1칸 줄입니다.
        _STD _Pop_heap_unchecked(_First, _Last, _Pred);
    }
}

이 루프가 작동하는 과정은 다음과 같습니다.

첫 번째 루프: 현재 최소 힙의 루트(0번 칸)에 있는 가장 작은 값을 뽑아내어 배열의 맨 마지막 칸에 채워 넣습니다. 두 번째 루프: 남은 원소들로 다시 최소 힙을 구성하면 루트에 두 번째로 작은 값이 올라옵니다. 이 값을 다시 배열의 뒤에서 두 번째 칸에 채워 넣습니다. 반복 결과: 가장 작은 값들이 배열의 뒤쪽 공간부터 역순으로 차곡차곡 쌓이게 됩니다.

최종적으로 배열의 앞쪽에는 큰 값들이 남고, 배열의 맨 뒤에 가장 작은 값이 배치되므로 전체 배열을 출력했을 때 내림차순의 형태를 띠게 되는 것입니다.

결국 동일한 기준(e.g. comp 함수로 greater<>를 사용)을 적용하더라도 결과가 반대인 이유는 인출 및 저장 메커니즘의 차이 때문이었습니다.

1. 컴파일러의 과도한 친절: 암시적 변환(Implicit Conversion)

C++ 컴파일러는 친절하게 설계된 부분들이 많습니다. 함수나 연산이 특정 타입의 객체를 요구할 때, 코더가 다른 타입을 넘겨주면 컴파일러는 에러를 내뿜기 전에 어떻게든 객체를 변환해서 코드를 동작시키려고 시도합니다.

문제는 이 친절함이 개발자의 의도와 다르게 작동할 때 발생합니다.

아래는 게임이나 서비스에서 특정 고유 ID를 가진 엔티티(Entity) 객체를 다룰 때 발생할 수 있는 문제의 예시입니다.

class Player {
public:
    // 고유 ID를 받아서 플레이어 객체를 생성 (데이터베이스에서 불러온다고 가정)
    Player(int id) {
        cout << id << "번 유령 플레이어 임시 생성됨!\n";
    }
};

// 특정 플레이어에게 데미지를 입히는 함수
void attack(Player target) {
    cout << "타겟을 공격했습니다!\n";
}

int main() {
    int damageAmount = 50;

    // 개발자가 실수로 타겟 객체가 아닌 '데미지 수치'를 함수에 넣어버림
    attack(damageAmount); 
}

상식적으로 attack() 함수는 Player 객체를 요구하므로, 숫자 50을 넣으면 컴파일러가 타입이 맞지 않는다며 에러를 뱉어야 정상일 것입니다.

하지만 explicit이 없으면 컴파일러는 스스로 이렇게 생각합니다. "어? Player를 달라고 했는데 숫자 50을 줬네? 잠깐, Player 클래스에 숫자를 받아서 객체를 만드는 생성자가 있잖아? 내가 알아서 Player(50)을 만들어서 넘겨줄게!"

결과적으로 에러는 나지 않고, 50번 아이디를 가진 유령 플레이어가 허공에 생성된 뒤 공격을 받게 됩니다. 의도와 맞지 않는 명령이 실행되면서, 나중에 원인을 찾기 위해 밤을 새우게 만드는 최악의 논리 버그가 됩니다.

프로그램이 죽지는 않지만 이상하게 동작하는, 가장 디버깅하기 힘든 부류의 버그가 탄생하는 순간입니다.

만약, 생성자에 explicit Player(int id)를 붙였다면 애초에 attack(damageAmount)에서 컴파일 에러를 내주었을 것입니다.

2. explicit 키워드의 마법

생성자 앞에 explicit을 붙이면 컴파일러의 이런 자동 형변환을 금지할 수 있습니다. "내가 명시적으로 객체를 생성한다고 적지 않는 한, 네 맘대로 변환하지 마!"라고 컴파일러에게 선언하는 것입니다.

class MyString {
public:
    explicit MyString(int size) { /* ... */ }
    // ...
};

printString(10); // ❌ 컴파일 에러 발생! (Cannot convert 'int' to 'MyString')

printString(MyString(10)); // ✅ 의도를 명확하게 밝혀야 통과됨

런타임에 발생할 논리적 버그를 컴파일 타임 에러로 끌어올려 즉각적으로 수정할 수 있게 해줍니다.

3. 실제 상황에서 발생할 수 있는 치명적인 문제 예시

explicit이 없을 때 발생한 사례를 찾아보았습니다.

A. 예상치 못한 오버로딩 꼬임

https://www.reddit.com/r/cpp/comments/1hf4z7p/i_am_confused_as_to_when_to_use_explicit_in_a/?tl=ko

Reddit C++ 커뮤니티의 한 유저는 포인터가 암시적으로 bool로 변환되는 C++의 특성 때문에 버그를 겪은 사례를 공유했습니다.

예시로 어떤 함수 Foo(bool)과 Foo(MyClass)가 있을 때, 포인터를 넘겼더니 의도치 않게 bool 관련 로직이나 엉뚱한 암시적 생성자를 타고 들어가는 식의 오버로딩 꼬임 현상이 발생하였다고 합니다.

explicit은 타입 간의 조용한 변환을 막아 오버로딩 모호성을 줄이므로 이런 문제를 예방할 수 있습니다.

B. 숨겨진 성능 저하 (Hidden Performance Costs)

객체를 생성하는 데 비용이 많이 드는(Heavy) 클래스라면 암시적 변환은 치명적인 성능 저하를 유발합니다.

void processData(const BigDataContainer& data);

// 만약 BigDataContainer(int id)가 explicit이 아니라면?
processData(1004); // int 하나만 넘겼는데 뒤에서 수십 MB 메모리 할당이 일어날 수 있음

explicit을 사용하면 사용자가 processData(BigDataContainer(1004))처럼 명시적으로 코드를 작성해야 하므로, 무거운 객체가 여기서 생성 된다라는 것을 인지할 수 있게 됩니다.

C. C++11 이후: 다중 인자와 중괄호 초기화의 함정

과거에는 "인자가 1개인 생성자"만 조심하면 됐지만, C++11의 중괄호 초기화(Braced Initialization)가 도입되면서 다중 인자 생성자에서도 암시적 변환이 일어납니다.

struct Rectangle {
    Rectangle(int width, int height) {}
};
void draw(Rectangle r);

draw({10, 20}); // 암시적 변환 허용. 

편리해 보이지만, 코드가 복잡해질수록 {10, 20}이 무엇을 의미하는지 문맥상 파악하기 힘들어집니다. 생성자를 explicit Rectangle(int, int)로 만들면 draw(Rectangle{10, 20})으로 작성하도록 강제할 수 있어 코드의 가독성과 안전성이 높아집니다.

D. 배열 크기와 데이터 값의 혼동

#include <iostream>

class IntArray {
public:
    // 숫자를 하나 받아서 "그 숫자만큼의 크기"를 가진 빈 배열을 만듦
    IntArray(int size) {
        cout << "크기가 " << size << "인 빈 배열 생성\n";
    }
};

// 학생들의 시험 점수 배열을 받아서 평균을 계산하는 함수
void calculateAverage(const IntArray& scores) {
    // ... 평균 계산 로직 ...
}

int main() {
    int myScore = 95;

    // 개발자의 의도: "내 점수(95) 하나만 일단 넣어서 계산해볼까?"
    calculateAverage(myScore); 
}

개발자는 95점이라는 int형 데이터 하나를 전달하고 싶었습니다. 하지만 컴파일러는 또다시 친절함을 발휘해 IntArray(95)를 호출해 버립니다.

결과적으로 95점이라는 데이터가 전달된 것이 아니라, 크기가 95칸인 텅 빈 0점짜리 배열이 함수로 넘어가게 됩니다. 프로그램은 죽지 않고 평균 0점이라는 엉뚱한 결과를 출력하게 됩니다.

4. explicit 사용의 골든 룰 (언제 쓰고, 언제 생략할까?)

Arthur O'Dwyer는 "몇 가지 예외를 제외한 99%의 생성자에는 explicit을 붙이는 것이 옳다"고 강조합니다. C++의 기본값은 암시적 변환 허용이지만, 이는 과거 C언어와의 호환성 때문이며 현대적인 소프트웨어 공학 관점에서는 모든 생성자에 explicit을 기본으로 다는 것이 좋습니다.

하지만 반드시 explicit을 생략해야 하는 예외 상황들도 있습니다.

1. 복사 및 이동 생성자 MyClass(const MyClass&) 같은 복사 생성자를 명시적으로 만들면 MyClass a = b; 와 같은 기본적인 대입조차 막히게 되므로 절대 붙여서는 안 됩니다.
2. std::initializer_list를 받는 생성자 std::vector<int> v = {1, 2, 3}; 처럼 배열 형태로 값을 집어넣어 초기화하는 컨테이너 타입들은 암시적 변환이 그 자체의 목적이므로 생략해야 합니다.
3. 단순 데이터 묶음 (C-Struct 대체품) std::pair나 std::tuple처럼 순수하게 데이터를 담는 바구니 역할만 하는 구조체라면 중괄호 {}를 통한 암시적 변환을 허용하는 것이 자연스럽습니다.
4. 본질적으로 같은 데이터를 표현하는 경우 const char*에서 std::string으로 변환되거나, int에서 직접 만든 BigInt 클래스로 변환되는 것처럼 "의미론적으로 완전히 동일한 개념"일 때는 묵시적 변환이 편리합니다.

💡 operator bool에도 explicit을 붙이세요!

생성자 외에도 explicit이 빛을 발하는 곳이 바로 형변환 연산자입니다. 객체가 유효한지 검사하기 위해 operator bool을 정의하는 경우가 많습니다.

class SmartPtr {
public:
    explicit operator bool() const { return ptr != nullptr; }
    // ...
};

여기에 explicit을 붙이면 if (myPtr) 같이 조건문 안에서는 정상적으로 작동(Contextual conversion)하지만, int x = myPtr + 1; 처럼 포인터가 실수로 숫자로 변환되어 연산되는 대참사는 컴파일러가 막아줍니다. 아래는 예시 코드를 실제 IDE에 적용한 것입니다.

explicit 키워드 사용 전

explicit 키워드 사용 후

명확한 이유가 없다면 작성하는 모든 생성자(심지어 파라미터가 없는 기본 생성자 포함)에 일단 explicit을 붙이는 습관을 들이는 것이 더 안전한 C++ 코드를 작성하는 지름길이라는 것을 깨달았습니다.

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

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

프로젝트 초반, 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이 이후에 비슷한 문제를 겪을 때 빠르게 원인을 좁히는 데 도움이 되기를 바랍니다.