write76465 님의 블로그

비헤이비어 트리로 구현하는 언리얼 엔진 AI

write76465 — Mon, 27 Jul 2026 22:02:51 +0900

참고 영상: 비헤이비어 트리를 활용한 언리얼 엔진 AI | Unreal Engine KR

게임에서 적 캐릭터는 단순히 플레이어를 따라가기만 해서는 자연스럽게 보이지 않는다. 평소에는 주변을 순찰하고, 플레이어를 발견하면 추격하며, 시야에서 놓치면 마지막으로 목격한 장소를 조사해야 한다. 상황에 따라 적절한 엄폐 장소를 선택할 수도 있어야 한다.

이러한 여러 행동을 조건문만으로 구현하면 코드가 빠르게 복잡해진다.

플레이어를 발견했는가?
    발견했다면 추격한다.
    발견하지 못했다면 순찰한다.

추격 중 플레이어를 놓쳤는가?
    놓쳤다면 마지막 위치를 조사한다.

공격받았는가?
    공격받았다면 공격자를 찾는다.

행동이 추가될수록 조건문은 서로 얽히고, 현재 AI가 어떤 판단을 내리고 있는지 확인하기 어려워진다.

언리얼 엔진은 이런 문제를 해결하기 위해 다음과 같은 AI 시스템을 제공한다.

AI Perception
      ↓
Blackboard
      ↓
Behavior Tree
      ↓
EQS
      ↓
이동·추격·공격

각 시스템은 독립적인 기능을 담당하지만 서로 연결되어 하나의 AI를 구성한다.

1. 언리얼 엔진 AI의 전체 구조

언리얼 엔진에서 일반적인 적 AI는 다음 요소로 구성한다.

Character 또는 Pawn
AI Controller
Blackboard
Behavior Tree
AI Perception
Environment Query System

Character는 실제 게임 월드에 존재하는 몸체다. 이동하고 애니메이션을 재생하며 공격을 수행한다.

AI Controller는 Character를 조종하는 두뇌 역할을 한다. 플레이어가 Player Controller를 통해 캐릭터를 조작하는 것처럼 AI 캐릭터는 AI Controller의 제어를 받는다.

Behavior Tree는 AI가 어떤 행동을 실행할지 결정한다.

Blackboard는 Behavior Tree가 판단에 사용할 정보를 저장한다.

AI Perception은 시각과 청각 등의 감각 정보를 수집한다.

EQS는 주변 환경을 검사하여 이동하거나 숨기에 가장 적절한 위치를 선택한다.

감각 정보가 블랙보드에 저장되고, 비헤이비어 트리가 이를 바탕으로 캐릭터의 행동을 결정하는 과정이다.

Player
   ↓ 감지
AI Perception
   ↓ 정보 저장
Blackboard
   ↓ 조건 확인
Behavior Tree
   ↓ 명령
AI Controller
   ↓ 조종
AI Character

2. Behavior Tree란 무엇인가

Behavior Tree는 AI의 행동을 트리 형태로 구성하는 시스템이다.

예를 들어 적 AI가 다음 행동을 수행한다고 가정한다.

플레이어가 보이면 추격한다.
플레이어가 보이지 않으면 순찰한다.

이를 비헤이비어 트리로 표현하면 다음과 같다.

Root
 └─ Selector
     ├─ Sequence: 플레이어 추격
     │   ├─ 플레이어가 보이는가?
     │   ├─ 플레이어 방향으로 회전
     │   └─ 플레이어에게 이동
     │
     └─ Sequence: 순찰
         ├─ 순찰 위치 선택
         └─ 순찰 위치로 이동

언리얼 엔진의 비헤이비어 트리는 기본적으로 위에서 아래로 내려가며, 같은 높이에서는 왼쪽에서 오른쪽 순서로 실행한다. 따라서 왼쪽에 있는 브랜치가 더 높은 우선순위를 가진다.

언리얼 엔진의 비헤이비어 트리는 불필요한 조건을 매 프레임 검사하는 방식보다 이벤트 중심으로 동작하도록 설계되어 있다. 블랙보드 값이 변경되면 관련 브랜치를 중단하고 우선순위가 높은 행동으로 전환할 수 있다. 언리얼 엔진 Behavior Tree 개요

플레이어 감지 여부에 따라 추격 브랜치와 순찰 브랜치 중 하나를 선택하는 구조다.

              Root
                ↓
             Selector
          ↙              ↘
   플레이어 추격          순찰
   HasTarget = true     HasTarget = false

3. Selector와 Sequence의 차이

비헤이비어 트리에서 가장 중요한 Composite 노드는 Selector와 Sequence다.

Selector

Selector는 여러 행동 중 성공할 수 있는 하나를 선택한다.

왼쪽 자식부터 실행하며 성공한 브랜치가 발견되면 나머지 브랜치는 실행하지 않는다.

Selector
 ├─ 플레이어를 추격할 수 있는가?
 ├─ 마지막 위치를 조사할 수 있는가?
 └─ 순찰한다.

플레이어를 추격할 수 있다면 첫 번째 브랜치를 실행한다. 추격할 수 없다면 두 번째 브랜치를 검사한다. 두 번째도 실행할 수 없다면 마지막 순찰 브랜치를 실행한다.

프로그래밍의 if, else if, else 구조와 비슷하다.

if (CanChasePlayer)
{
    ChasePlayer();
}
else if (CanInvestigate)
{
    Investigate();
}
else
{
    Patrol();
}

Sequence

Sequence는 여러 행동을 순서대로 실행한다.

모든 자식이 성공해야 Sequence 전체가 성공한다. 중간 행동이 실패하면 이후 행동은 실행하지 않는다.

Sequence: 플레이어 공격
 ├─ 플레이어에게 이동한다.
 ├─ 공격 범위인지 확인한다.
 ├─ 플레이어 방향으로 회전한다.
 └─ 공격한다.

플레이어에게 이동하지 못하면 공격 범위 확인과 공격 행동은 실행하지 않는다.

Selector가 “어떤 행동을 할 것인가”를 선택한다면, Sequence는 “선택한 행동을 어떤 순서로 수행할 것인가”를 나타낸다. Behavior Tree Quick Start Guide

Selector는 행동을 선택하고, Sequence는 선택된 행동의 실행 순서를 구성한다.

노드실행 방식비슷한 코드

Selector	하나가 성공할 때까지 실행한다	if / else if / else
Sequence	하나가 실패할 때까지 순서대로 실행한다	A && B && C

4. Task, Decorator, Service

비헤이비어 트리에는 Composite 외에도 세 가지 중요한 노드가 있다.

Task

Task는 AI가 실제로 수행할 행동이다.

Move To
Wait
Play Animation
Run EQS Query
Attack
Find Patrol Location

Move To는 지정된 액터나 위치로 이동하는 Task다. 공격이나 순찰 위치 선택처럼 게임 고유의 행동은 Blueprint 또는 C++로 커스텀 Task를 만들어 구현할 수 있다.

Decorator

Decorator는 브랜치가 실행될 수 있는지 검사하는 조건이다.

HasTarget == true
CanAttack == true
Health <= 30
IsPlayerVisible == true

Decorator 조건이 거짓이면 해당 브랜치에 진입하지 않는다.

또한 Observer Aborts 설정을 이용하면 블랙보드 값이 변했을 때 현재 실행 중인 브랜치를 중단할 수 있다. 예를 들어 순찰 중 HasTarget이 참으로 변경되면 순찰을 중단하고 추격 브랜치로 전환한다.

Service

Service는 특정 브랜치가 실행되는 동안 주기적으로 정보를 갱신한다.

플레이어와의 거리 확인
공격 가능 여부 갱신
가장 가까운 적 검색
주변 위험도 계산

모든 기능을 Service의 Tick에 넣으면 주기적인 연산이 많아질 수 있다. 감지 결과처럼 이벤트로 받을 수 있는 정보는 AI Perception 이벤트를 이용하고, 반드시 주기적으로 확인해야 하는 값만 Service에서 갱신하는 편이 좋다.

비헤이비어 트리를 구성하는 네 가지 노드와 각 노드가 담당하는 역할이다.

Composite → 흐름을 제어한다.
Task      → 행동을 실행한다.
Decorator → 실행 조건을 검사한다.
Service   → 정보를 주기적으로 갱신한다.

5. Blackboard는 AI의 기억 공간이다

Blackboard는 AI가 판단에 사용할 값을 저장하는 데이터 공간이다.

다음과 같은 Key를 만들 수 있다.

Blackboard Key자료형의미

TargetActor	Object	현재 추적 중인 플레이어
HasLineOfSight	Bool	플레이어가 시야에 보이는지 여부
LastKnownLocation	Vector	마지막으로 확인한 플레이어 위치
PatrolLocation	Vector	다음 순찰 위치
CanAttack	Bool	현재 공격할 수 있는지 여부

Behavior Tree는 직접 모든 정보를 찾기보다 Blackboard 값을 읽어 행동을 결정한다.

HasLineOfSight == true
        ↓
TargetActor에게 이동한다.

HasLineOfSight == false
        ↓
LastKnownLocation으로 이동한다.

공식 문서에서도 Behavior Tree가 실행할 브랜치를 결정하기 위해 Blackboard Key를 사용한다고 설명한다. 언리얼 엔진 Behavior Tree 문서

Blackboard는 단순한 변수 모음이 아니다. AI Perception, Behavior Tree, EQS 사이에서 정보를 전달하는 공용 저장소에 가깝다.

감지 결과와 환경 탐색 결과가 블랙보드에 저장되고, 비헤이비어 트리가 값을 읽어 행동을 선택한다.

AI Perception ──쓰기──▶ Blackboard ◀──쓰기── EQS
                              │
                             읽기
                              ▼
                       Behavior Tree

6. AI Perception으로 플레이어를 감지한다

AI Perception은 AI에게 시각, 청각과 같은 감각 기능을 제공한다.

대표적인 Sense는 다음과 같다.

AI Sight: 시야 안의 액터를 감지한다.
AI Hearing: 발생한 소리를 감지한다.
AI Damage: 피해를 준 대상을 감지한다.
AI Touch: 접촉한 대상을 감지한다.

AI Controller에 AI Perception Component를 추가하면 감지 이벤트를 받을 수 있다.

플레이어를 시각으로 감지한 경우의 흐름은 다음과 같다.

플레이어가 시야에 들어온다.
        ↓
On Target Perception Updated
        ↓
Successfully Sensed 확인
        ↓
TargetActor = 플레이어
HasLineOfSight = true
        ↓
Behavior Tree의 추격 브랜치 실행

반대로 플레이어를 놓치면 다음처럼 처리할 수 있다.

Successfully Sensed = false
        ↓
LastKnownLocation 저장
        ↓
HasLineOfSight = false
        ↓
마지막 목격 위치 조사

AI Perception Component는 자극을 수집하고, 감지 결과가 변경되면 이벤트를 통해 Blueprint 로직이나 Behavior Tree가 사용하는 값을 갱신할 수 있다. AI Perception 공식 문서

플레이어가 AI의 시야 범위에 들어오면 감지 이벤트가 발생하고 블랙보드 값이 변경된다.

       AI 시야 범위
      ╱           ╲
   Enemy ───────▶ Player
      │
      └─ On Target Perception Updated
                    ↓
          HasLineOfSight = true

7. EQS로 최적의 위치를 찾는다

Behavior Tree가 “무엇을 할 것인가”를 정한다면, EQS는 “어디에서 할 것인가”를 계산한다.

예를 들어 AI가 엄폐할 위치를 찾는다고 가정한다.

주변에 이동 가능한 여러 후보 지점을 생성한 뒤 다음 조건으로 평가한다.

플레이어에게서 너무 가깝지 않은가?
AI가 이동할 수 있는 위치인가?
플레이어의 시야를 차단할 수 있는가?
공격할 수 있는 시야가 확보되는가?

EQS는 크게 세 요소로 구성한다.

Generator

검사할 후보 위치나 액터를 생성한다.

AI 주변의 원형 지점
플레이어 주변의 이동 가능 지점
레벨에 배치된 엄폐물

Context

거리나 방향을 계산할 때 기준이 되는 대상이다.

현재 AI
플레이어
마지막 목격 위치
특정 목표 액터

Test

각 후보가 조건을 만족하는지 검사하고 점수를 부여한다.

거리 검사
시야 검사
이동 가능 여부 검사
경로 비용 검사

모든 Test를 통과한 후보 중 가장 높은 점수를 얻은 위치를 최종 결과로 선택한다.

후보 위치 생성
      ↓
이동 불가능한 위치 제거
      ↓
플레이어와의 거리 평가
      ↓
시야 확보 여부 평가
      ↓
가장 높은 점수의 위치 선택

EQS Query는 Behavior Tree의 Run EQS Query Task에서 실행할 수 있으며, 결과 위치를 Blackboard에 저장한 뒤 Move To Task로 이동할 수 있다. EQS 공식 문서

주변 후보 지점을 생성한 뒤 거리·시야·이동 가능 여부를 평가하여 가장 높은 점수의 위치를 선택한다.

     후보 A  20점
후보 B  80점   Player
     AI       후보 C  45점
        후보 D 제외

최종 선택 → 후보 B

8. 잠입 게임 적 AI의 전체 동작

지금까지 살펴본 시스템을 하나로 연결하면 다음과 같은 AI를 만들 수 있다.

평상시

TargetActor가 없다.
        ↓
EQS로 순찰 위치를 찾는다.
        ↓
PatrolLocation에 저장한다.
        ↓
Move To로 이동한다.

플레이어 발견

AI Perception이 플레이어를 감지한다.
        ↓
TargetActor와 HasLineOfSight를 갱신한다.
        ↓
Decorator가 변경을 감지한다.
        ↓
순찰 브랜치를 중단한다.
        ↓
플레이어 추격 브랜치를 실행한다.

플레이어를 놓친 경우

HasLineOfSight = false
        ↓
마지막 목격 위치로 이동한다.
        ↓
주변을 일정 시간 조사한다.
        ↓
플레이어를 찾지 못하면 다시 순찰한다.

전투 위치 선택

Run EQS Query
        ↓
플레이어와 거리를 유지하면서
시야가 확보되는 위치를 찾는다.
        ↓
결과를 Blackboard에 저장한다.
        ↓
해당 위치로 이동한 뒤 공격한다.

감지 결과에 따라 순찰, 추격, 마지막 위치 조사 상태가 전환되는 과정이다.

        플레이어 발견
순찰 ─────────────▶ 추격
 ▲                    │
 │                    │ 시야 상실
 │                    ▼
 └─────────────── 마지막 위치 조사
      발견 실패

9. 구현할 때 주의할 점

Blackboard Key를 지나치게 많이 만들지 않는다

모든 임시 값을 Blackboard에 넣으면 데이터의 의미를 파악하기 어려워진다. 여러 Task와 시스템이 공유해야 하는 정보만 Blackboard에 저장한다.

Service의 갱신 주기를 조절한다

Service는 필요한 주기로만 실행한다. 매 프레임 실행할 필요가 없는 거리 계산이나 목표 탐색을 지나치게 자주 수행하면 AI 수가 증가했을 때 성능에 영향을 줄 수 있다.

왼쪽 브랜치에 높은 우선순위를 배치한다

언리얼 엔진의 비헤이비어 트리는 왼쪽에서 오른쪽 순서로 실행한다.

Selector
 ├─ 사망 처리
 ├─ 피격 대응
 ├─ 전투
 └─ 순찰

즉시 처리해야 하는 행동일수록 왼쪽에 배치하는 것이 자연스럽다.

감지와 판단을 분리한다

AI Perception은 정보를 감지하고, Blackboard는 정보를 저장하며, Behavior Tree는 행동을 결정하도록 역할을 분리한다.

AI Perception 이벤트 안에서 이동과 공격까지 모두 처리하면 시스템 간 책임이 뒤섞이게 된다.

마무리

비헤이비어 트리는 AI의 모든 기능을 직접 처리하는 시스템이 아니다. 여러 AI 시스템을 연결하여 행동의 우선순위와 실행 흐름을 관리하는 역할을 한다.

핵심 관계는 다음과 같이 정리할 수 있다.

AI Perception
→ 무엇을 보고 들었는지 감지한다.

Blackboard
→ AI가 알고 있는 정보를 저장한다.

Behavior Tree
→ 현재 실행할 행동을 결정한다.

EQS
→ 행동을 수행하기 가장 좋은 위치나 대상을 찾는다.

AI Controller
→ 결정된 행동을 Character에게 실행시킨다.

이 구조를 이해하면 단순한 순찰 AI부터 플레이어를 추적하고 엄폐물을 활용하는 전투 AI까지 단계적으로 확장할 수 있다.

영상은 2021년에 공개된 자료이므로 현재 언리얼 엔진 버전에서는 일부 메뉴와 에디터 화면이 달라질 수 있다. 하지만 Behavior Tree, Blackboard, AI Perception, EQS가 연결되는 기본 구조는 현재 공식 문서에서도 동일하게 설명한다.

배열의 한계를 넘는 연결 리스트: 노드, 포인터, 삽입과 삭제 원리

write76465 — Fri, 24 Jul 2026 14:41:28 +0900

배열은 같은 자료형의 데이터를 연속된 메모리 공간에 저장한다. 인덱스를 통해 빠르게 접근할 수 있다는 장점이 있지만, 크기가 고정되고 중간 데이터를 삽입하거나 삭제하기 어렵다는 단점도 존재한다.

연결 리스트는 각 데이터를 별도의 노드에 저장하고 포인터로 연결한다. 노드들이 메모리에 연속해서 배치될 필요가 없기 때문에 실행 중에 크기를 자유롭게 변경할 수 있다.

이 글에서는 코드조선의 Linked List 강의를 바탕으로 연결 리스트의 구조, 동적 메모리 할당, 앞·뒤 삽입, 이중 포인터를 이용한 순회와 삭제, 재귀적인 메모리 해제 원리를 정리한다.

1. 배열의 특징과 한계

배열은 여러 데이터를 연속된 메모리 공간에 저장한다.

int Numbers[4] = {10, 20, 30, 40};

메모리에서는 다음과 비슷한 형태로 배치된다.

주소      값
0x1000   10
0x1004   20
0x1008   30
0x100C   40

int가 4바이트라면 각 원소가 4바이트 간격으로 붙어 있다. 따라서 시작 주소와 인덱스를 이용해 원하는 원소의 위치를 바로 계산할 수 있다.

원소 주소 = 시작 주소 + 인덱스 × 자료형 크기

다음 접근의 시간복잡도는 O(1)이다.

printf("%d\n", Numbers[2]);

하지만 배열은 일반적으로 크기를 미리 결정해야 한다.

int Numbers[4];

원소가 4개보다 많아지면 더 큰 배열을 만들고 기존 데이터를 복사해야 한다.

배열 중간에 새로운 값을 삽입할 때도 문제가 생긴다.

삽입 전

10  20  30  40

20과 30 사이에 25를 삽입하려면 뒤쪽 값을 이동해야 한다.

10  20  25  30  40
            →   →

데이터가 N개라면 최악의 경우 N개에 가까운 데이터를 이동해야 하므로 삽입과 삭제의 시간복잡도는 O(N)이 된다.

2. 연결 리스트란 무엇인가?

연결 리스트는 데이터를 노드 단위로 저장하는 자료구조이다.

각 노드는 일반적으로 다음 두 가지 정보를 가진다.

1. 실제 데이터
2. 다음 노드의 주소

구조를 그림으로 표현하면 다음과 같다.

┌─────────────┬─────────────┐
│ Data        │ Next        │
│ 10          │ 다음 주소   │
└─────────────┴─────────────┘

여러 노드를 연결하면 다음과 같은 리스트가 만들어진다.

Head
 ↓
[10 | 다음] → [20 | 다음] → [30 | NULL]

마지막 노드는 다음 노드가 없으므로 NULL을 저장한다.

연결 리스트의 노드는 반드시 서로 붙어 있을 필요가 없다.

0x1000                0x3500                0x2200
[10 | 0x3500]   →    [20 | 0x2200]   →    [30 | NULL]

각 노드가 다음 노드의 메모리 주소를 알고 있으므로 메모리 위치가 떨어져 있어도 하나의 자료구조로 연결할 수 있다.

3. 연결 리스트의 노드 만들기

C 언어에서는 구조체로 노드를 정의할 수 있다.

struct Node
{
    int Data;
    struct Node* PtrToNextNode;
};

Data에는 실제 데이터를 저장한다.

int Data;

PtrToNextNode에는 다음 노드의 주소를 저장한다.

struct Node* PtrToNextNode;

같은 구조체를 반복해서 작성하지 않도록 typedef를 사용할 수 있다.

typedef struct Node Node_t;

전체 코드는 다음과 같다.

typedef struct Node
{
    int Data;
    struct Node* PtrToNextNode;
} Node_t;

이제 다음과 같이 간단하게 노드 자료형을 사용할 수 있다.

Node_t Node;
Node_t* PtrToNode;

4. Head 포인터의 역할

연결 리스트는 첫 번째 노드의 위치를 알아야 전체 노드를 탐색할 수 있다.

첫 번째 노드를 가리키는 포인터를 일반적으로 Head라고 한다.

Node_t* PtrToHeadNode = NULL;

리스트가 비어 있을 때 Head는 NULL이다.

Head → NULL

첫 번째 노드가 생기면 Head에 첫 번째 노드의 주소를 저장한다.

Head → [10 | NULL]

노드가 추가되면 각 노드의 PtrToNextNode를 따라간다.

Head
 ↓
[10] → [20] → [30] → NULL

Head를 잃어버리면 첫 번째 노드에 접근할 방법이 사라진다. 결과적으로 연결된 나머지 노드에도 접근할 수 없다.

따라서 Head는 연결 리스트의 시작점을 보관하는 중요한 포인터이다.

5. 노드는 동적 메모리에 생성한다

연결 리스트는 실행 중에 노드의 개수를 변경하기 위해 동적 메모리를 사용한다.

새로운 노드는 malloc()으로 생성한다.

Node_t* PtrToNewNode =
    (Node_t*)malloc(sizeof(Node_t));

sizeof(Node_t)는 노드 하나를 저장하는 데 필요한 메모리 크기를 계산한다.

malloc()이 메모리 할당에 실패하면 NULL을 반환한다. 따라서 결과를 확인해야 한다.

assert(PtrToNewNode != NULL);

메모리를 할당한 뒤에는 노드의 내용을 설정한다.

PtrToNewNode->Data = InData;
PtrToNewNode->PtrToNextNode = NULL;

처음 생성한 노드는 아직 연결 리스트에 포함된 것이 아니다.

기존 리스트

Head → [10] → [20] → NULL

새 노드

PtrToNewNode → [30 | NULL]

새 노드를 기존 노드와 연결하거나 Head에 넣어야 비로소 리스트의 일부가 된다.

6. 리스트 앞에 노드 삽입하기

리스트의 맨 앞에 노드를 삽입하는 함수는 다음과 같이 작성할 수 있다.

void InsertFront(
    Node_t** InPtrToPtrToHeadNode,
    int InData)
{
    Node_t* PtrToNewNode =
        (Node_t*)malloc(sizeof(Node_t));

    assert(PtrToNewNode != NULL);

    PtrToNewNode->Data = InData;

    PtrToNewNode->PtrToNextNode =
        *InPtrToPtrToHeadNode;

    *InPtrToPtrToHeadNode =
        PtrToNewNode;
}

함수 매개변수로 Node_t**를 받는 이유는 원래 Head 포인터의 값을 변경해야 하기 때문이다.

InsertFront(&PtrToHeadNode, 10);

삽입 전

Head → [20] → [30] → NULL

새 노드 → [10 | NULL]

먼저 새 노드가 기존 첫 번째 노드를 가리키게 한다.

PtrToNewNode->PtrToNextNode =
    *InPtrToPtrToHeadNode;

새 노드 [10] → [20] → [30] → NULL

그다음 Head가 새 노드를 가리키게 한다.

*InPtrToPtrToHeadNode =
    PtrToNewNode;

Head → [10] → [20] → [30] → NULL

이 두 문장의 순서가 중요하다.

Head를 먼저 새 노드로 변경하면 기존 첫 번째 노드의 주소를 잃어버릴 수 있다.

앞에 삽입하는 작업은 기존 노드 개수와 관계없이 포인터 두 개만 수정한다. 따라서 시간복잡도는 O(1)이다.

7. 리스트 뒤에 노드 삽입하기

뒤에 삽입하려면 마지막 노드까지 이동해야 한다.

영상에서는 이중 포인터를 이용해 다음과 같이 구현한다.

void InsertRear(
    Node_t** InPtrToPtrToHeadNode,
    int InData)
{
    Node_t* PtrToNewNode =
        (Node_t*)malloc(sizeof(Node_t));

    assert(PtrToNewNode != NULL);

    PtrToNewNode->Data = InData;
    PtrToNewNode->PtrToNextNode = NULL;

    Node_t** PtrToPtrToLastNode =
        InPtrToPtrToHeadNode;

    while (*PtrToPtrToLastNode != NULL)
    {
        PtrToPtrToLastNode =
            &((*PtrToPtrToLastNode)
                ->PtrToNextNode);
    }

    *PtrToPtrToLastNode =
        PtrToNewNode;
}

이 코드를 이해하려면 PtrToPtrToLastNode가 노드를 직접 가리키는 포인터가 아니라는 점을 알아야 한다.

Node_t** PtrToPtrToLastNode;

이 변수는 현재 노드를 가리키는 포인터의 주소를 저장한다.

처음에는 Head 포인터의 주소를 가진다.

PtrToPtrToLastNode
        ↓
     Head 포인터
        ↓
      첫 노드

반복문 안에서는 현재 노드의 PtrToNextNode 주소로 이동한다.

PtrToPtrToLastNode =
    &((*PtrToPtrToLastNode)
        ->PtrToNextNode);

여러 줄로 풀면 다음과 같다.

Node_t* PtrToCurrentNode =
    *PtrToPtrToLastNode;

Node_t** PtrToPtrToNextNode =
    &(PtrToCurrentNode->PtrToNextNode);

PtrToPtrToLastNode =
    PtrToPtrToNextNode;

리스트가 다음과 같다고 가정한다.

Head → [10] → [20] → [30] → NULL

반복할 때마다 가리키는 위치가 다음과 같이 이동한다.

Head 포인터의 주소
→ 10 노드의 next 주소
→ 20 노드의 next 주소
→ 30 노드의 next 주소

30 노드의 next에는 NULL이 들어 있다.

PtrToPtrToLastNode
        ↓
[30 노드의 next 포인터]
        ↓
       NULL

따라서 반복문이 종료된다.

마지막으로 그 위치에 새 노드의 주소를 넣는다.

*PtrToPtrToLastNode =
    PtrToNewNode;

Head → [10] → [20] → [30] → [40] → NULL

리스트가 비어 있어도 동작한다

리스트가 비어 있다면 처음부터 다음 상태이다.

PtrToPtrToLastNode → Head
*PtrToPtrToLastNode = NULL

반복문은 한 번도 실행되지 않는다.

그다음 문장이 Head에 새 노드의 주소를 넣는다.

*PtrToPtrToLastNode = PtrToNewNode;

Head → [새 노드] → NULL

이중 포인터를 사용했기 때문에 빈 리스트와 노드가 존재하는 리스트를 같은 코드로 처리할 수 있다.

마지막 노드를 찾기 위해 모든 노드를 지나가므로 시간복잡도는 O(N)이다. 별도의 Tail 포인터를 관리한다면 뒤쪽 삽입을 O(1)로 만들 수 있다.

8. 연결 리스트 전체를 출력하기

연결 리스트를 출력할 때는 Head부터 시작해 NULL을 만날 때까지 이동한다.

void Print(Node_t* InPtrToHeadNode)
{
    Node_t* PtrToCurrentNode =
        InPtrToHeadNode;

    while (PtrToCurrentNode != NULL)
    {
        printf("%d ", PtrToCurrentNode->Data);

        PtrToCurrentNode =
            PtrToCurrentNode->PtrToNextNode;
    }

    printf("\n");
}

실행 과정은 다음과 같다.

현재 노드: 10 → 출력
현재 노드: 20 → 출력
현재 노드: 30 → 출력
현재 노드: NULL → 종료

결과는 다음과 같다.

10 20 30

모든 노드를 확인하므로 시간복잡도는 O(N)이다.

배열은 인덱스를 이용해 특정 위치에 O(1)로 접근할 수 있다. 반면 단일 연결 리스트에서 세 번째 노드를 찾으려면 첫 번째 노드부터 포인터를 따라가야 한다.

Head → 첫 번째 → 두 번째 → 세 번째

따라서 특정 위치에 접근하는 시간복잡도도 O(N)이다.

9. 모든 노드를 재귀적으로 삭제하기

malloc()으로 할당한 노드는 사용이 끝났을 때 반드시 free()해야 한다.

영상에서는 재귀함수를 사용해 마지막 노드부터 메모리를 해제한다.

void DestroyRecursively(
    Node_t* InPtrToCurrentNode)
{
    if (InPtrToCurrentNode == NULL)
    {
        return;
    }

    DestroyRecursively(
        InPtrToCurrentNode->PtrToNextNode);

    printf(
        "%d has been deleted.\n",
        InPtrToCurrentNode->Data);

    free(InPtrToCurrentNode);
}

리스트가 다음과 같다고 가정한다.

Head → [10] → [20] → [30] → NULL

재귀함수는 먼저 끝까지 이동한다.

Destroy(10)
→ Destroy(20)
  → Destroy(30)
    → Destroy(NULL)

NULL에 도달하면 호출된 함수들이 반대 순서로 돌아온다.

30 노드 free()
20 노드 free()
10 노드 free()

다음 노드로 먼저 이동한 뒤 현재 노드를 해제하는 이유가 있다.

현재 노드를 먼저 해제하면 다음 노드의 주소도 읽을 수 없기 때문이다.

잘못된 순서는 다음과 같다.

free(InPtrToCurrentNode);

DestroyRecursively(
    InPtrToCurrentNode->PtrToNextNode);

free() 이후에 PtrToNextNode에 접근하므로 정의되지 않은 동작이 발생한다.

따라서 다음 노드의 주소를 사용한 뒤 현재 노드를 해제해야 한다.

10. free()와 댕글링 포인터

free()는 포인터 변수 자체를 삭제하는 함수가 아니다.

free(InPtrToCurrentNode);

포인터가 가리키고 있던 동적 메모리를 반환한다.

free 전

포인터 → 정상적인 노드 메모리

free 후

포인터 → 이미 반환된 메모리

free() 이후에도 포인터 변수에는 이전 주소가 남아 있다. 이처럼 이미 해제된 메모리를 가리키는 포인터를 댕글링 포인터라고 한다.

다음 접근은 위험하다.

free(PtrToNode);

printf("%d", PtrToNode->Data);  // 잘못된 접근

보통 해제한 뒤에는 포인터에 NULL을 저장한다.

free(PtrToNode);
PtrToNode = NULL;

그러나 함수 매개변수로 전달된 지역 포인터만 NULL로 바꾸어도 원래 Head는 바뀌지 않는다.

void DestroyRecursively(Node_t* Current)
{
    free(Current);
    Current = NULL;
}

Current는 함수 내부의 복사본이기 때문이다.

따라서 전체 삭제가 끝난 뒤 실제 Head를 직접 NULL로 변경한다.

void Destroy(
    Node_t** InPtrToPtrToHeadNode)
{
    if (*InPtrToPtrToHeadNode == NULL)
    {
        printf("Linked list is empty.\n");
        return;
    }

    DestroyRecursively(
        *InPtrToPtrToHeadNode);

    *InPtrToPtrToHeadNode = NULL;
}

11. 특정 데이터를 가진 노드 삭제하기

특정 노드를 삭제하려면 세 가지 작업이 필요하다.

1. 삭제할 노드를 찾는다.
2. 이전 연결을 다음 노드로 변경한다.
3. 삭제할 노드의 메모리를 해제한다.

다음 리스트에서 20을 삭제한다고 가정한다.

Head → [10] → [20] → [30] → NULL

단순히 20을 free()하면 안 된다.

Head → [10] → 해제된 메모리

              [30] → NULL

10 노드의 next가 여전히 해제된 20 노드의 주소를 가지고 있기 때문이다. 30 노드로 이어지는 연결도 끊어진다.

삭제하기 전에 10 노드의 next가 30 노드를 가리키도록 변경해야 한다.

연결 변경

[10] ─────────→ [30]
         [20]

그다음 20 노드를 해제한다.

삭제 완료

Head → [10] → [30] → NULL

12. 이중 포인터를 이용한 삭제

영상에서는 이중 포인터를 사용해 첫 번째 노드와 중간 노드를 같은 방식으로 삭제한다.

int Remove(
    Node_t** InPtrToPtrToHeadNode,
    int InData)
{
    Node_t** PtrToPtrToCurrentNode =
        InPtrToPtrToHeadNode;

    while (*PtrToPtrToCurrentNode != NULL)
    {
        if ((*PtrToPtrToCurrentNode)->Data
            == InData)
        {
            Node_t* PtrToDeletedNode =
                *PtrToPtrToCurrentNode;

            *PtrToPtrToCurrentNode =
                PtrToDeletedNode->PtrToNextNode;

            free(PtrToDeletedNode);
            PtrToDeletedNode = NULL;

            return 1;
        }

        PtrToPtrToCurrentNode =
            &((*PtrToPtrToCurrentNode)
                ->PtrToNextNode);
    }

    return 0;
}

PtrToPtrToCurrentNode는 항상 현재 노드를 가리키는 포인터의 주소를 저장한다.

현재 노드가 첫 번째 노드라면 Head 포인터의 주소를 가진다.

PtrToPtrToCurrentNode → Head → 첫 번째 노드

현재 노드가 두 번째 노드라면 첫 번째 노드의 next 주소를 가진다.

PtrToPtrToCurrentNode
        ↓
[첫 번째 노드의 next]
        ↓
     두 번째 노드

삭제할 노드를 찾으면 먼저 주소를 보관한다.

Node_t* PtrToDeletedNode =
    *PtrToPtrToCurrentNode;

그다음 현재 노드를 가리키던 포인터에 삭제할 노드의 다음 주소를 넣는다.

*PtrToPtrToCurrentNode =
    PtrToDeletedNode->PtrToNextNode;

마지막으로 삭제할 노드의 메모리를 해제한다.

free(PtrToDeletedNode);

첫 번째 노드를 삭제하는 경우

삭제 전

Head → [10] → [20] → NULL

PtrToPtrToCurrentNode는 Head의 주소를 가진다.

*PtrToPtrToCurrentNode =
    PtrToDeletedNode->PtrToNextNode;

따라서 Head가 바로 20 노드를 가리키게 된다.

삭제 후

Head → [20] → NULL

중간 노드를 삭제하는 경우

삭제 전

Head → [10] → [20] → [30] → NULL

20을 찾았을 때 PtrToPtrToCurrentNode는 10 노드의 next 주소를 가진다.

따라서 같은 대입문으로 10 노드의 next가 30을 가리키게 된다.

삭제 후

Head → [10] → [30] → NULL

이중 포인터를 사용하면 첫 번째 노드를 삭제하는 특별한 코드를 별도로 작성하지 않아도 된다.

13. 연결 리스트의 시간복잡도

단일 연결 리스트의 주요 연산을 정리하면 다음과 같다.

연산시간복잡도이유

앞쪽 삽입	O(1)	Head 주변의 포인터만 변경한다.
뒤쪽 삽입	O(N)	마지막 노드를 찾아야 한다.
값 탐색	O(N)	첫 노드부터 순서대로 확인한다.
특정 위치 접근	O(N)	포인터를 따라 해당 위치까지 이동한다.
값 삭제	O(N)	삭제할 노드를 먼저 찾아야 한다.
전체 출력	O(N)	모든 노드를 방문한다.
전체 삭제	O(N)	모든 노드를 한 번씩 해제한다.

별도의 Tail 포인터를 유지하면 뒤쪽 삽입을 O(1)로 만들 수 있다.

Head → [10] → [20] → [30] ← Tail

그러나 중간 노드를 찾거나 특정 인덱스에 접근하는 작업은 여전히 O(N)이다.

14. 배열과 연결 리스트 비교

구분배열연결 리스트

메모리 배치	연속적이다.	떨어져 있어도 된다.
크기	일반적으로 미리 결정한다.	실행 중 변경하기 쉽다.
인덱스 접근	O(1)이다.	O(N)이다.
앞쪽 삽입	O(N)이다.	O(1)이다.
중간 삭제	데이터 이동이 필요하다.	연결 변경이 필요하다.
추가 메모리	데이터만 저장한다.	노드마다 포인터가 필요하다.
캐시 효율	비교적 좋다.	비교적 낮을 수 있다.
구현 난이도	비교적 단순하다.	포인터 관리가 필요하다.

연결 리스트가 항상 배열보다 좋은 것은 아니다.

빠른 인덱스 접근이 중요하면 배열이 적합하다. 데이터의 앞쪽 삽입과 삭제가 자주 발생하거나 실행 중 크기가 자주 변한다면 연결 리스트가 적합할 수 있다.

15. 연결 리스트에서 주의할 점

새 노드를 반드시 기존 리스트에 연결해야 한다

Node_t* NewNode = malloc(sizeof(Node_t));

메모리만 할당했다고 리스트에 포함되는 것은 아니다.

NewNode->PtrToNextNode = *Head;
*Head = NewNode;

연결 작업까지 완료해야 한다.

NULL에 역참조를 사용하면 안 된다

Node_t* Ptr = NULL;

printf("%d", Ptr->Data); // 잘못된 접근

노드를 사용하기 전에 포인터가 NULL인지 확인해야 한다.

free() 이후에 노드에 접근하면 안 된다

free(PtrToNode);

PtrToNode->Data = 10; // 잘못된 접근

해제된 메모리는 더 이상 사용할 수 없다.

연결을 변경하기 전에 필요한 주소를 보관해야 한다

삭제할 노드의 다음 주소를 잃어버리면 이후 노드에 접근할 수 없게 된다.

Node_t* Deleted = *CurrentLink;
*CurrentLink = Deleted->PtrToNextNode;
free(Deleted);

할당한 노드는 반드시 해제해야 한다

malloc()으로 생성하고 free()하지 않으면 메모리 누수가 발생한다.

malloc()으로 할당
→ 사용
→ free()로 반환

마무리

연결 리스트는 각 데이터를 노드에 저장하고 포인터를 이용해 노드들을 연결하는 자료구조이다.

Head → [Data | Next] → [Data | Next] → NULL

연결 리스트를 이해하기 위한 핵심은 다음과 같다.

노드는 데이터와 다음 노드의 주소를 가진다.
Head는 첫 번째 노드를 가리킨다.
새 노드는 malloc()으로 동적 할당한다.
앞쪽 삽입은 새 노드를 기존 Head 앞에 연결한다.
뒤쪽 삽입은 마지막 NULL 포인터의 위치를 찾는다.
이중 포인터를 사용하면 Head와 노드의 next를 같은 방식으로 다룰 수 있다.
삭제할 때는 먼저 연결을 변경한 뒤 free()해야 한다.
전체 삭제 후에는 Head를 NULL로 변경해야 한다.

특히 영상 코드에서 반복해서 등장하는 이중 포인터는 다음 관점으로 이해하면 된다.

Node_t** PtrToPtrToCurrentNode;

이는 단순히 현재 노드를 가리키는 것이 아니다.

현재 노드를 가리키고 있는 포인터 변수의 주소를 저장한다.

이 관점을 이해하면 다음 코드도 자연스럽게 해석할 수 있다.

PtrToPtrToCurrentNode =
    &((*PtrToPtrToCurrentNode)
        ->PtrToNextNode);

현재 노드에서 다음 노드로 단순히 이동하는 것을 넘어, 다음 노드를 가리키는 포인터 변수의 위치로 이동한다는 뜻이다.

이 덕분에 삽입과 삭제에서 Head 포인터와 각 노드의 next 포인터를 동일한 방식으로 수정할 수 있다.

HashSet과 HashMap은 어떻게 빠르게 데이터를 찾을까?

write76465 — Thu, 23 Jul 2026 19:06:45 +0900

자료구조를 공부하다 보면 HashSet과 HashMap은 데이터를 평균 O(1)의 시간복잡도로 탐색한다고 배운다.

배열에서 데이터를 순서대로 찾으면 최악의 경우 모든 데이터를 확인해야 한다. 그런데 해시 자료구조는 데이터가 많아져도 어떻게 원하는 값을 빠르게 찾을 수 있을까?

이 글에서는 코드조선의 Hash Set과 Hash Map 강의를 바탕으로 해시 함수, 해시 충돌, 선형 탐사, HashSet과 HashMap의 차이를 정리한다. 강의에서는 C 언어로 단순화한 해시 자료구조를 직접 구현하면서 동작 원리를 설명한다.

1. 배열 탐색은 왜 느려질까?

다음과 같은 문자열 배열이 있다고 가정한다.

const char* names[] = {
    "Kim",
    "Lee",
    "Park",
    "Choi",
    "Jung"
};

배열에서 "Choi"를 찾으려면 앞에서부터 하나씩 비교해야 한다.

for (int i = 0; i < 5; i++) {
    if (strcmp(names[i], "Choi") == 0) {
        printf("찾았습니다.\n");
        break;
    }
}

찾으려는 데이터가 배열의 마지막에 있거나 존재하지 않는다면 배열 전체를 확인해야 한다.

데이터가 N개라면 최악의 경우 N번 비교하므로 시간복잡도는 다음과 같다.

O(N)

데이터가 10개일 때는 큰 문제가 아니다. 하지만 데이터가 수십만 개 이상이라면 매번 처음부터 확인하는 방식은 비효율적이다.

2. 해시 함수란 무엇인가?

해시 자료구조는 데이터를 처음부터 탐색하지 않는다. 대신 데이터가 저장될 위치를 계산한다.

이때 사용하는 것이 해시 함수이다.

데이터 → 해시 함수 → 해시값 → 배열 인덱스

예를 들어 문자열을 숫자로 변환하는 단순한 해시 함수가 있다고 가정한다.

unsigned int hashString(const char* text) {
    unsigned int hash = 0;

    while (*text != '\0') {
        hash += (unsigned char)*text;
        text++;
    }

    return hash;
}

문자열의 각 문자를 숫자로 바꿔 모두 더한 값을 반환한다.

그러나 해시값을 배열의 인덱스로 바로 사용할 수는 없다. 해시값이 배열 크기보다 클 수 있기 때문이다.

따라서 배열 크기로 나눈 나머지를 사용한다.

index = hashString(key) % CAPACITY;

배열 크기가 7이고 해시값이 24라면 다음과 같이 계산한다.

24 % 7 = 3

따라서 데이터는 배열의 3번 인덱스에 저장된다.

데이터를 찾을 때도 같은 해시 함수를 사용한다.

저장할 때: key → 해시 함수 → 3번 인덱스
찾을 때:   key → 해시 함수 → 3번 인덱스

처음부터 배열을 탐색하지 않고 계산된 위치로 바로 이동할 수 있는 것이다.

3. 해시 테이블의 크기를 소수로 정하는 이유

영상의 단순화된 구현에서는 해시 테이블의 크기로 7과 같은 소수를 사용한다.

#define CAPACITY 7

해시 테이블의 인덱스는 보통 나머지 연산으로 계산한다.

index = hashValue % CAPACITY;

배열의 크기가 특정 해시값 패턴과 공약수를 많이 가지면 데이터가 일부 인덱스에 집중될 수 있다.

예를 들어 해시값이 모두 짝수이고 배열의 크기도 짝수라면 특정 위치가 반복해서 선택될 가능성이 커진다.

소수 크기를 사용하면 이러한 규칙적인 패턴을 줄이는 데 도움이 된다. 특히 나머지 연산과 선형 탐사를 사용하는 단순한 해시 테이블에서 이해하기 쉬운 선택이다.

다만 실제 라이브러리가 반드시 소수 크기만 사용하는 것은 아니다. 구현 방식에 따라 2의 거듭제곱 크기를 사용하고 해시값의 비트를 별도로 섞기도 한다.

핵심은 테이블 크기 자체보다 데이터가 가능한 한 여러 인덱스에 고르게 분산되도록 만드는 것이다.

4. 서로 다른 데이터의 인덱스가 같다면?

해시 함수를 사용해도 모든 데이터가 서로 다른 인덱스를 가지는 것은 아니다.

예를 들어 다음과 같은 결과가 나올 수 있다.

hash("Kim")  % 7 = 3
hash("Park") % 7 = 3

서로 다른 두 문자열이 같은 인덱스 3을 얻게 된다.

이러한 현상을 해시 충돌이라고 한다.

Kim  ─┐
      ├─→ 3번 인덱스
Park ─┘

해시 충돌은 해시 함수가 잘못되었다는 의미가 아니다. 저장할 수 있는 데이터의 종류는 매우 많지만 배열의 인덱스 개수는 한정되어 있으므로 충돌을 완전히 피할 수는 없다.

따라서 해시 자료구조에는 충돌을 처리하는 방법이 반드시 필요하다.

5. 선형 탐사로 충돌 해결하기

영상의 단순화된 구현에서는 선형 탐사 방식으로 해시 충돌을 처리한다.

선형 탐사는 원래 위치가 이미 사용 중이라면 바로 다음 칸을 확인하는 방법이다.

다음과 같이 3번 인덱스에 데이터가 이미 저장되어 있다고 가정한다.

0   1   2   3   4   5   6
            Kim

새로운 데이터 "Park"의 인덱스도 3으로 계산되었다면 다음 칸을 확인한다.

3번 사용 중 → 4번 확인 → 비어 있음 → 4번에 저장

결과는 다음과 같다.

0   1   2   3     4      5   6
            Kim   Park

이를 코드로 표현하면 다음과 같은 형태가 된다.

int startIndex = hashString(key) % CAPACITY;
int index = startIndex;

do {
    if (table[index] == NULL) {
        table[index] = key;
        return 1;
    }

    index = (index + 1) % CAPACITY;

} while (index != startIndex);

return 0;

다음 인덱스를 계산할 때 다시 나머지 연산을 사용한다.

index = (index + 1) % CAPACITY;

현재 인덱스가 마지막인 6이라면 다음 위치는 다음과 같다.

(6 + 1) % 7 = 0

배열의 끝에 도달하면 다시 배열의 처음으로 돌아간다. 배열을 원형으로 탐색하는 것과 같은 효과가 발생한다.

처음 시작했던 인덱스로 다시 돌아왔다면 모든 칸을 확인했다는 의미이므로 탐색을 종료해야 한다.

6. HashSet이란 무엇인가?

HashSet은 중복되지 않는 데이터를 저장하는 자료구조이다.

{"Kim", "Lee", "Park"}

같은 데이터를 다시 삽입해도 하나만 저장한다.

"Kim" 삽입 → 성공
"Lee" 삽입 → 성공
"Kim" 삽입 → 이미 존재하므로 실패

HashSet에 필요한 대표적인 기능은 다음과 같다.

Insert(&set, "Kim");
Contains(&set, "Kim");
Delete(&set, "Kim");

HashSet은 특정 데이터의 존재 여부가 중요할 때 사용한다.

예를 들면 다음과 같다.

방문한 사용자 ID를 저장한다.
중복된 이름이나 번호를 제거한다.
이미 처리한 데이터를 기록한다.
게임에서 획득한 아이템 종류를 관리한다.
특정 값이 목록에 포함되어 있는지 빠르게 검사한다.

HashSet에는 데이터 하나만 저장한다. 데이터와 연결된 추가 정보는 저장하지 않는다.

HashSet = {데이터, 데이터, 데이터}

7. 중복 데이터는 어떻게 확인할까?

새로운 데이터를 삽입할 때는 빈칸만 찾으면 되는 것이 아니다. 같은 데이터가 이미 저장되어 있는지도 검사해야 한다.

if (table[index] != NULL &&
    strcmp(table[index], key) == 0) {
    return 0;
}

문자열의 해시값이 같다고 해서 반드시 같은 문자열인 것은 아니다. 서로 다른 문자열이 같은 해시값을 가질 수도 있기 때문이다.

따라서 일반적인 탐색 과정은 다음과 같다.

1. key의 해시값을 계산한다.
2. 시작 인덱스를 계산한다.
3. 해당 위치의 실제 데이터와 key를 비교한다.
4. 다르면 충돌 처리 규칙에 따라 다음 위치를 확인한다.
5. 같은 데이터를 찾거나 빈칸을 만나면 탐색을 종료한다.

해시값은 데이터를 찾을 후보 위치를 결정한다. 최종적으로 같은 데이터인지 확인하려면 실제 값의 비교도 필요하다.

8. 선형 탐사에서 삭제할 때 주의할 점

선형 탐사를 사용하는 해시 테이블에서는 데이터를 삭제할 때 단순히 빈칸으로 만들면 문제가 발생할 수 있다.

다음과 같은 상태를 가정한다.

3번: Kim
4번: Park
5번: Lee

세 데이터가 충돌로 인해 연속된 위치에 저장되었다고 한다.

이때 4번의 "Park"를 완전히 빈칸으로 만들면 다음 상태가 된다.

3번: Kim
4번: 비어 있음
5번: Lee

이후 "Lee"를 탐색할 때 3번부터 확인한다고 가정한다.

3번 확인 → 다른 데이터
4번 확인 → 비어 있음

탐색 알고리즘이 빈칸을 보고 종료하면 5번에 있는 "Lee"를 찾지 못한다.

따라서 선형 탐사 방식에서는 슬롯의 상태를 구분할 필요가 있다.

typedef enum {
    EMPTY,
    OCCUPIED,
    DELETED
} SlotState;

각 상태의 의미는 다음과 같다.

상태의미

EMPTY	처음부터 데이터가 저장된 적이 없는 칸이다.
OCCUPIED	현재 데이터가 저장된 칸이다.
DELETED	데이터가 있었지만 삭제된 칸이다.

탐색 중 EMPTY를 만나면 데이터가 없다고 판단할 수 있다. 하지만 DELETED를 만나면 뒤에 데이터가 있을 수 있으므로 계속 탐색해야 한다.

이러한 삭제 표시를 흔히 삭제 마커 또는 tombstone이라고 한다.

9. HashMap이란 무엇인가?

HashSet이 데이터의 존재 여부를 저장한다면, HashMap은 키와 값을 한 쌍으로 저장한다.

Key → Value

예를 들어 게임의 몬스터 정보를 다음과 같이 저장할 수 있다.

"Slime"  → 체력 30
"Goblin" → 체력 80
"Dragon" → 체력 1000

여기에서 몬스터 이름은 Key, 체력은 Value이다.

typedef struct {
    const char* key;
    int value;
} Entry;

HashMap은 키에 해시 함수를 적용해 저장 위치를 계산한다.

index = hashString(key) % CAPACITY;

배열의 각 칸에는 키만 저장하는 것이 아니라 키와 값이 함께 저장된다.

인덱스 0: 비어 있음
인덱스 1: {"Slime", 30}
인덱스 2: 비어 있음
인덱스 3: {"Dragon", 1000}

값을 가져올 때는 키를 전달한다.

int hp = Get(&monsterMap, "Dragon");

HashMap은 다음과 같은 상황에 적합하다.

이름으로 전화번호를 찾는다.
사용자 ID로 사용자 정보를 찾는다.
상품 코드로 가격을 찾는다.
단어별 등장 횟수를 저장한다.
몬스터 이름으로 능력치를 찾는다.
파일 이름으로 파일 정보를 찾는다.

10. HashSet과 HashMap의 차이

두 자료구조 모두 해시 함수를 사용해 저장 위치를 계산한다. 가장 큰 차이는 무엇을 저장하느냐에 있다.

구분HashSetHashMap

저장 형태	데이터 하나	Key–Value 쌍
중복	같은 데이터 저장 불가	같은 Key 저장 불가
주요 목적	존재 여부 확인	Key를 이용한 Value 탐색
삽입 예시	add("Kim")	put("Kim", 95)
탐색 결과	존재 여부	Key와 연결된 Value
활용 예시	중복 제거	이름별 점수 저장

HashSet은 다음 질문에 답한다.

"Kim"이 존재하는가?

HashMap은 다음 질문에 답한다.

"Kim"과 연결된 값은 무엇인가?

예를 들어 출석 여부만 확인한다면 HashSet이 적합하다.

출석한 학생 = {"Kim", "Lee", "Park"}

학생별 점수까지 저장해야 한다면 HashMap이 적합하다.

학생별 점수 = {
    "Kim": 90,
    "Lee": 85,
    "Park": 100
}

11. 해시 자료구조의 시간복잡도

해시 함수가 데이터를 여러 위치에 고르게 분산하고 충돌이 많지 않다면 삽입, 탐색, 삭제는 평균적으로 O(1)에 동작한다.

연산평균 시간복잡도 최악의 시간복잡도

삽입	O(1)	O(N)
탐색	O(1)	O(N)
삭제	O(1)	O(N)

평균 시간복잡도가 O(1)인 이유는 해시 함수를 이용해 데이터가 있을 것으로 예상되는 위치로 바로 이동하기 때문이다.

하지만 모든 데이터의 해시값이 같은 인덱스로 몰리면 충돌이 계속 발생한다.

시작 위치 확인
→ 다음 칸 확인
→ 다음 칸 확인
→ 다음 칸 확인
→ ...

최악의 경우 배열의 모든 칸을 확인해야 하므로 O(N)이 된다.

따라서 해시 자료구조에서 중요한 것은 단순히 해시 함수를 사용하는 것만이 아니다.

해시값을 고르게 분산해야 한다.
테이블이 지나치게 가득 차지 않도록 관리해야 한다.
충돌 처리 방법이 필요하다.
필요하면 테이블 크기를 늘리고 데이터를 다시 배치해야 한다.

12. 적재율이 높아지면 충돌도 증가한다

해시 테이블이 얼마나 차 있는지를 적재율이라고 한다.

적재율 = 저장된 데이터 수 / 전체 슬롯 수

슬롯이 10개이고 데이터가 7개라면 적재율은 다음과 같다.

7 / 10 = 0.7

테이블에 빈칸이 많으면 충돌이 발생하더라도 가까운 곳에서 빈칸을 찾을 수 있다.

반대로 테이블이 거의 가득 차면 빈칸을 찾기 위해 여러 칸을 이동해야 한다. 이 상태에서는 평균 O(1)이라는 장점을 유지하기 어렵다.

실제 해시 자료구조는 적재율이 특정 기준을 넘으면 더 큰 배열을 생성한 뒤 기존 데이터를 다시 저장한다. 이를 리사이징 또는 재해싱이라고 한다.

기존 테이블 생성
→ 적재율 증가
→ 더 큰 테이블 생성
→ 모든 데이터의 인덱스 재계산
→ 새 위치에 다시 저장

리사이징 한 번에는 많은 작업이 필요하지만, 매번 발생하는 작업은 아니므로 전체 연산을 평균 내면 삽입은 일반적으로 상각 O(1)로 설명한다.

13. 좋은 해시 함수의 조건

좋은 해시 함수는 다음 조건을 만족해야 한다.

같은 입력에는 같은 결과를 반환해야 한다

hash("Kim") → 123
hash("Kim") → 123

저장할 때와 찾을 때 결과가 달라지면 같은 위치로 이동할 수 없다.

서로 다른 데이터를 고르게 분산해야 한다

hash("Kim")  → 1
hash("Lee")  → 5
hash("Park") → 3

모든 데이터가 같은 인덱스로 몰리지 않아야 한다.

계산 속도가 빨라야 한다

해시값을 계산하는 작업 자체가 지나치게 오래 걸리면 빠른 탐색이라는 장점이 사라진다.

데이터의 일부만 지나치게 의존하지 않아야 한다

예를 들어 문자열의 첫 글자만 사용하면 같은 글자로 시작하는 데이터가 한곳에 몰릴 수 있다.

Kim
Kang
Kwon

학습용 구현에서는 문자 코드의 합처럼 단순한 함수를 사용할 수 있다. 하지만 실제 프로그램에서는 데이터 분산을 고려한 검증된 해시 함수나 언어의 표준 라이브러리를 사용하는 것이 안전하다.

14. 언제 무엇을 선택해야 할까?

데이터의 존재 여부만 필요하다면 HashSet을 선택한다.

이미 방문한 페이지인가?
이미 처리한 사용자 번호인가?
중복된 단어인가?

키를 이용해 연결된 값을 찾아야 한다면 HashMap을 선택한다.

사용자 번호에 해당하는 이름은 무엇인가?
상품 코드에 해당하는 가격은 얼마인가?
단어가 몇 번 등장했는가?

데이터의 순서를 유지해야 한다면 일반적인 HashSet이나 HashMap만으로는 부족할 수 있다. 사용하는 언어에서 순서를 보장하는 별도의 자료구조를 확인해야 한다.

데이터가 매우 적거나 단순히 한 번만 탐색한다면 배열이나 리스트가 더 간단할 수 있다. HashSet과 HashMap은 빠른 탐색이 반복적으로 필요한 상황에서 특히 유용하다.

마무리

HashSet과 HashMap이 빠른 이유는 데이터를 무작정 처음부터 찾지 않기 때문이다.

해시 함수를 사용해 데이터가 저장될 위치를 계산하고, 해당 위치로 바로 이동한다.

전체 동작은 다음과 같이 정리할 수 있다.

Key 입력
→ 해시 함수 실행
→ 해시값 생성
→ 나머지 연산으로 인덱스 계산
→ 해당 인덱스 확인
→ 충돌하면 다음 위치 탐색

HashSet과 HashMap의 차이는 저장하는 데이터의 형태에 있다.

HashSet = 데이터의 존재 여부를 저장한다.
HashMap = Key와 연결된 Value를 저장한다.

해시 함수가 데이터를 고르게 분산한다면 삽입, 탐색, 삭제는 평균 O(1)에 동작한다. 하지만 충돌이 많거나 테이블이 지나치게 가득 차면 최악의 경우 O(N)까지 느려질 수 있다.

따라서 해시 자료구조의 핵심은 단순히 해시값을 계산하는 것이 아니다.

좋은 해시 함수, 적절한 테이블 크기, 충돌 처리 방법을 함께 설계해야 빠른 탐색 성능을 얻을 수 있다.

재귀함수와 반복문의 시간복잡도, 그리고 출력 순서가 뒤집히는 이유

write76465 — Tue, 21 Jul 2026 17:38:01 +0900

프로그래밍에서 같은 작업을 여러 번 수행하는 대표적인 방법에는 반복문과 재귀함수가 있다. 반복문은 for, while과 같은 문법을 사용하고, 재귀함수는 함수가 자기 자신을 다시 호출하는 방식으로 동작한다.

두 방식은 비슷한 결과를 만들 수 있지만, 실행 과정과 메모리 사용 방식에는 중요한 차이가 있다. 특히 재귀 호출문의 앞과 뒤 중 어디에 출력문을 배치하느냐에 따라 출력 순서가 달라진다.

1. 반복문이란 무엇인가

반복문은 주어진 조건이 만족되는 동안 특정 코드를 계속 실행하는 문법이다.

다음 코드는 3부터 1까지 출력한다.

#include <stdio.h>

int main(void) {
    for (int i = 3; i >= 1; i--) {
        printf("%d ", i);
    }

    return 0;
}

실행 결과는 다음과 같다.

3 2 1

반복문은 하나의 함수 안에서 변수 i를 변경하면서 같은 코드를 반복해서 실행한다.

i 가 3부터 1까지 감소하며 출력되는 과정을 나타낸 이미지이다.

2. 재귀함수란 무엇인가

재귀함수는 함수 내부에서 자기 자신을 다시 호출하는 함수이다.

다음 코드는 재귀함수를 이용해 3부터 1까지 출력한다.

#include <stdio.h>

void printNumber(int n) {
    if (n == 0) {
        return;
    }

    printf("%d ", n);
    printNumber(n - 1);
}

int main(void) {
    printNumber(3);
    return 0;
}

함수 내부의 다음 문장이 자기 자신을 다시 호출한다.

printNumber(n - 1);

printNumber(3)을 호출하면 내부적으로 다음과 같이 실행된다.

printNumber(3)
→ printNumber(2)
→ printNumber(1)
→ printNumber(0)

각 함수가 다음 함수에 전달하는 값은 이전 값보다 1 작다. 결국 n이 0이 되면 다음 종료 조건에 의해 재귀 호출이 멈춘다.

if (n == 0) {
    return;
}

재귀함수에는 반드시 종료 조건이 필요하다. 종료 조건이 없다면 함수가 자기 자신을 끝없이 호출한다. 그러면 호출 정보가 메모리에 계속 쌓이고, 결국 스택 오버플로가 발생한다.

재귀함수의 핵심은 다음 두 가지이다.

if (n == 0) return;  // 종료 조건
printNumber(n - 1);  // 재귀 호출

재귀 호출을 엔진이라고 한다면 종료 조건은 브레이크라고 할 수 있다.

재귀함수가 자기 자신을 더 작은 값으로 호출하는 모습을 러시아 인형으로 표현한 이미지이다.

3. 재귀함수는 실제로 어떻게 실행되는가

재귀함수를 정확히 이해하려면 함수 호출이 끝날 때까지 기존 함수가 기다린다는 사실을 알아야 한다.

다음 코드를 살펴본다.

void printNumber(int n) {
    if (n == 0) return;

    printf("%d ", n);
    printNumber(n - 1);
}

printNumber(3)을 호출하면 먼저 3을 출력한다.

그다음 printNumber(2)를 호출한다. 이때 printNumber(3)이 완전히 종료되는 것은 아니다. 자신이 호출한 printNumber(2)가 끝날 때까지 기다린다.

전체 과정은 다음과 같다.

printNumber(3)
├─ 3 출력
└─ printNumber(2)
   ├─ 2 출력
   └─ printNumber(1)
      ├─ 1 출력
      └─ printNumber(0)
         └─ 종료

따라서 출력 결과는 다음과 같다.

3 2 1

함수 호출이 스택에 쌓였다가 역순으로 제거되는 과정을 나타낸 이미지이다.

호출된 함수가 종료되면 기다리고 있던 이전 함수로 돌아간다. 프로그램은 이렇게 돌아가야 할 위치와 각 함수의 지역변수 등을 호출 스택에 저장한다.

4. 재귀 호출 전에 출력하면 순차적으로 내려간다

다음 코드에서는 출력문이 재귀 호출문보다 앞에 있다.

void printNumber(int n) {
    if (n == 0) return;

    printf("%d ", n);
    printNumber(n - 1);
}

C 언어는 함수를 위에서 아래로 실행한다. 따라서 현재 숫자를 먼저 출력한 다음, 숫자를 1 줄여 자기 자신을 다시 호출한다.

입력이 3이라면 다음과 같이 실행된다.

printNumber(3)
1. 3을 출력한다.
2. printNumber(2)를 호출한다.

printNumber(2)
1. 2를 출력한다.
2. printNumber(1)을 호출한다.

printNumber(1)
1. 1을 출력한다.
2. printNumber(0)을 호출한다.

printNumber(0)
1. 종료한다.

결과는 다음과 같다.

3 2 1

이 경우 출력은 재귀 호출이 더 깊어지는 과정에서 발생한다. 즉, 계단을 내려가면서 숫자를 출력한다고 생각할 수 있다.

3 출력 → 한 층 내려감
2 출력 → 한 층 내려감
1 출력 → 한 층 내려감
0에서 종료

5. 재귀 호출 후에 출력하면 역순으로 올라온다

이번에는 출력문의 위치를 재귀 호출문 뒤로 옮긴다.

void printNumber(int n) {
    if (n == 0) return;

    printNumber(n - 1);
    printf("%d ", n);
}

입력이 3이라면 printf()를 바로 실행하지 않는다. 먼저 printNumber(n - 1)을 호출한다.

printNumber(3)
→ 출력을 미루고 printNumber(2)를 호출한다.

printNumber(2)
→ 출력을 미루고 printNumber(1)을 호출한다.

printNumber(1)
→ 출력을 미루고 printNumber(0)을 호출한다.

printNumber(0)
→ 종료한다.

printNumber(0)이 종료되면 기다리고 있던 함수로 돌아간다. 함수가 돌아가는 순서는 호출된 순서의 반대이다.

printNumber(1)로 돌아감 → 1 출력
printNumber(2)로 돌아감 → 2 출력
printNumber(3)으로 돌아감 → 3 출력

따라서 결과는 다음과 같다.

1 2 3

중요한 점은 함수 호출이 끝나도 이전 함수가 사라지지 않았다는 것이다. 이전 함수는 재귀 호출 다음 줄을 실행하기 위해 호출 스택에서 기다리고 있었다.

실행 흐름을 코드에 직접 표시하면 다음과 같다.

void printNumber(int n) {
    if (n == 0) return;

    printNumber(n - 1);  // 여기서 기다린다.
    printf("%d ", n);    // 호출이 끝나면 이곳으로 돌아온다.
}

재귀 호출 전에 작성한 코드는 내려가면서 실행되고, 재귀 호출 뒤에 작성한 코드는 돌아오면서 실행된다.

재귀 호출이 내려가는 과정과 함수가 다시 돌아오는 과정을 계단으로 표현한 이미지이다.

6. 두 출력 순서 비교하기

두 코드의 차이는 출력문의 위치뿐이다.

재귀 호출 전에 출력하는 경우

printf("%d ", n);
printNumber(n - 1);

현재 값을 먼저 출력하므로 다음 결과가 나온다.

3 2 1

재귀 호출 후에 출력하는 경우

printNumber(n - 1);
printf("%d ", n);

가장 깊은 호출까지 내려간 다음, 함수가 돌아오면서 출력하므로 다음 결과가 나온다.

1 2 3

이를 간단히 정리하면 다음과 같다.

출력문의 위치실행 시점입력이 3일 때 결과

재귀 호출 전	호출이 깊어지면서 실행	3 2 1
재귀 호출 후	함수가 돌아오면서 실행	1 2 3

7. 시간복잡도란 무엇인가

시간복잡도는 입력 크기가 증가할 때 연산 횟수가 얼마나 증가하는지를 나타낸다.

시간복잡도는 실제 실행 시간을 초 단위로 측정하는 개념이 아니다. 컴퓨터의 성능이나 실행 환경이 달라져도 알고리즘의 효율을 비교할 수 있도록 연산 횟수의 증가 형태를 표현한다.

대표적인 시간복잡도는 다음과 같다.

시간복잡도의미예시

O(1)	입력 크기와 관계없이 연산 횟수가 일정하다	배열의 특정 위치 확인
O(log n)	입력이 증가해도 연산 횟수가 천천히 증가한다	이진 탐색
O(n)	입력에 비례해 연산 횟수가 증가한다	1부터 N까지 출력
O(n²)	입력 크기의 제곱에 비례한다	이중 반복문
O(2ⁿ)	입력이 증가하면 연산 횟수가 매우 빠르게 증가한다	단순 피보나치 재귀

대표적인 시간복잡도별 연산 횟수의 증가 차이를 비교한 그래프이다.

8. 반복문의 시간복잡도

다음 반복문은 N번 실행된다.

for (int i = 1; i <= N; i++) {
    printf("%d ", i);
}

N이 3이면 출력문을 3번 실행하고, N이 100이면 출력문을 100번 실행한다.

입력 크기 N에 비례하여 작업 횟수가 증가하므로 시간복잡도는 다음과 같다.

O(N)

이 코드에서 사용하는 추가 변수는 i 정도이다. N이 커져도 필요한 변수의 개수가 증가하지 않는다. 따라서 추가 공간복잡도는 다음과 같다.

O(1)

9. 재귀함수의 시간복잡도

다음 재귀함수는 n을 1씩 줄이며 총 N번 호출된다.

void printNumber(int n) {
    if (n == 0) return;

    printf("%d ", n);
    printNumber(n - 1);
}

한 번 호출될 때마다 출력과 비교 같은 일정한 양의 작업을 수행한다.

이를 점화식으로 표현하면 다음과 같다.

T(N) = T(N - 1) + O(1)

이를 계속 전개하면 다음과 같다.

T(N)
= T(N - 1) + O(1)
= T(N - 2) + O(1) + O(1)
= T(N - 3) + O(1) + O(1) + O(1)
...
= T(0) + N × O(1)
= O(N)

따라서 이 재귀함수의 시간복잡도도 반복문과 동일한 O(N)이다.

반복문: O(N)
재귀함수: O(N)

출력문을 재귀 호출 전이나 후에 배치하더라도 실행 횟수는 달라지지 않는다. 출력 순서만 바뀌므로 두 코드의 시간복잡도는 모두 O(N)이다.

10. 시간복잡도가 같아도 메모리 사용량은 다르다

반복문과 재귀함수가 모두 O(N)의 시간복잡도를 가진다고 해서 완전히 같은 것은 아니다.

반복문은 일반적으로 하나의 함수 안에서 변수의 값만 변경한다.

for (int i = N; i >= 1; i--) {
    printf("%d ", i);
}

따라서 추가 공간복잡도는 보통 O(1)이다.

재귀함수는 호출할 때마다 현재 함수의 실행 상태를 호출 스택에 저장한다.

printNumber(3)
printNumber(2)
printNumber(1)

호출 깊이가 N까지 증가하므로 호출 스택에 저장되는 정보도 N에 비례하여 증가한다. 따라서 재귀함수의 추가 공간복잡도는 O(N)이다.

방식시간복잡도추가 공간복잡도

반복문	O(N)	O(1)
재귀함수	O(N)	O(N)

일반적으로 단순 반복 작업에서는 반복문이 메모리 면에서 더 효율적이다. 재귀함수는 호출할 때마다 함수 호출에 필요한 추가 작업도 발생하므로 실제 실행 속도에서도 반복문이 유리한 경우가 많다.

다만 재귀함수는 트리 탐색, 그래프 탐색, 분할 정복처럼 문제 자체가 재귀적인 구조를 가질 때 코드를 더 자연스럽고 간결하게 표현할 수 있다.

반복문과 재귀함수의 메모리 사용량 차이를 비교한 이미지이다.

11. 모든 재귀함수가 O(N)인 것은 아니다

재귀함수를 사용했다고 해서 시간복잡도가 항상 O(N)이 되는 것은 아니다. 한 번의 함수 호출에서 자기 자신을 몇 번 호출하는지와, 입력 크기가 어떻게 감소하는지에 따라 달라진다.

한 번씩 호출하는 경우

func(n - 1);

호출 횟수가 N에 비례하므로 일반적으로 O(N)이다.

입력을 절반씩 줄이는 경우

func(n / 2);

N → N/2 → N/4 → ... → 1로 감소하므로 일반적으로 O(log N)이다.

매번 두 번씩 호출하는 경우

func(n - 1);
func(n - 1);

각 호출이 다시 두 개의 호출을 만들기 때문에 호출 횟수가 급격히 증가한다. 일반적으로 O(2ⁿ)이 될 수 있다.

대표적인 예가 단순 재귀로 작성한 피보나치 함수이다.

int fibonacci(int n) {
    if (n <= 1) return n;

    return fibonacci(n - 1) + fibonacci(n - 2);
}

같은 값을 여러 번 중복 계산하므로 매우 비효율적이다. 따라서 재귀함수의 시간복잡도는 재귀 호출문의 개수와 입력 감소 방식을 함께 분석해야 한다.

12. 반복문과 재귀함수 중 무엇을 사용해야 하는가

단순히 숫자를 출력하거나 일정 횟수만큼 반복하는 작업에는 반복문이 더 적합한 경우가 많다.

for (int i = 1; i <= N; i++) {
    printf("%d ", i);
}

반복문은 동작이 직관적이고, 호출 스택을 추가로 사용하지 않는다.

반면 다음과 같이 문제 자체가 작은 문제로 계속 나뉘는 구조라면 재귀함수가 유용하다.

폴더 내부의 모든 파일을 탐색하는 작업
트리의 모든 노드를 탐색하는 작업
미로에서 경로를 찾는 작업
병합 정렬과 퀵 정렬
하노이의 탑
백트래킹 문제

재귀함수는 문제의 구조를 코드에 그대로 표현하기 쉽다는 장점이 있다. 그러나 종료 조건을 잘못 작성하거나 호출 깊이가 지나치게 커지면 스택 오버플로가 발생할 수 있으므로 주의해야 한다.

마무리

반복문과 재귀함수는 모두 반복 작업을 표현할 수 있지만 동작 방식은 다르다.

반복문은 한 함수 안에서 변수의 값을 변경하며 코드를 반복한다. 재귀함수는 자기 자신을 다시 호출하고, 기존 함수는 호출된 함수가 끝날 때까지 호출 스택에서 기다린다.

N부터 1까지 한 번씩 처리하는 단순한 코드라면 반복문과 재귀함수의 시간복잡도는 모두 O(N)이다. 하지만 반복문의 추가 공간복잡도는 O(1)이고, 재귀함수는 호출 스택을 사용하므로 O(N)이다.

재귀함수의 출력 순서는 출력문의 위치에 따라 달라진다.

printf("%d ", n);
printNumber(n - 1);

위 코드는 재귀 호출이 깊어지면서 출력하므로 3 2 1이 된다.

printNumber(n - 1);
printf("%d ", n);

위 코드는 가장 깊은 호출에서 돌아오면서 출력하므로 1 2 3이 된다.

결국 다음 한 문장으로 정리할 수 있다.

재귀 호출 앞의 코드는 내려가면서 실행하고, 재귀 호출 뒤의 코드는 돌아오면서 실행한다.

언리얼 엔진의 GAS란 무엇일까?

write76465 — Mon, 20 Jul 2026 19:09:24 +0900

언리얼 엔진으로 액션 게임이나 RPG를 개발하다 보면 GAS라는 용어를 자주 접하게 됩니다.

GAS는 Gameplay Ability System의 약자로, 캐릭터의 스킬과 능력치, 버프 및 디버프 같은 게임플레이 요소를 체계적으로 구현할 수 있도록 언리얼 엔진에서 제공하는 프레임워크입니다.

이름만 보면 단순히 캐릭터의 스킬을 만드는 시스템처럼 보이지만, 실제로는 스킬 사용부터 결과 적용까지의 전체적인 흐름을 관리하는 시스템에 가깝습니다.

GAS는 왜 필요할까?

캐릭터가 화염구를 사용하는 상황을 예로 들어보겠습니다.

화염구 스킬 하나를 구현하기 위해서도 생각보다 많은 처리가 필요합니다.

현재 마나가 충분한지 확인
스킬이 재사용 대기시간 중인지 확인
캐릭터가 기절하거나 침묵 상태인지 확인
스킬 애니메이션과 이펙트 재생
적에게 피해 적용
일정 확률로 화상 상태이상 적용
사용한 마나 차감
멀티플레이 환경에서 다른 플레이어에게 결과 동기화

간단한 프로젝트에서는 이러한 기능들을 각각 직접 구현해도 큰 문제가 없습니다. 하지만 캐릭터와 스킬의 종류가 많아지면 비슷한 로직이 여러 코드와 블루프린트에 반복해서 들어가기 시작합니다.

예를 들어 마나 확인 방식이나 쿨타임 처리 방식을 변경해야 할 때, 관련된 스킬을 하나씩 찾아 수정해야 할 수도 있습니다. 캐릭터의 상태가 늘어날수록 조건문도 계속 복잡해집니다.

GAS는 이런 기능들을 일정한 규칙과 구조 안에서 관리하도록 도와줍니다. 덕분에 기능을 재사용하기 쉽고, 프로젝트의 규모가 커졌을 때도 스킬과 상태를 비교적 일관된 방식으로 관리할 수 있습니다.

GAS의 핵심 구성 요소

GAS를 처음 접하면 낯선 용어가 많이 등장합니다. 하지만 기본적인 역할을 중심으로 보면 크게 어렵지 않습니다.

1. Gameplay Ability

Gameplay Ability는 캐릭터가 수행할 수 있는 행동을 의미합니다.

일반 공격, 화염구, 회피, 점프, 회복, 궁극기 등 캐릭터의 능력으로 볼 수 있는 대부분의 행동을 어빌리티로 구현할 수 있습니다.

어빌리티 안에서는 스킬을 사용할 수 있는지 확인하고, 애니메이션을 재생하거나 다른 대상에게 효과를 적용하는 등의 작업을 처리합니다.

즉, “캐릭터가 무엇을 하는가?”를 담당하는 부분이라고 볼 수 있습니다.

2. Attribute

Attribute는 캐릭터가 가지고 있는 수치형 데이터를 의미합니다.

대표적으로 다음과 같은 값들이 있습니다.

현재 체력과 최대 체력
현재 마나와 최대 마나
공격력
방어력
이동 속도
치명타 확률

이러한 값들은 보통 Attribute Set이라는 단위로 묶어서 관리합니다.

예를 들어 적에게 공격받으면 체력이 감소하고, 회복 스킬을 사용하면 체력이 증가합니다. 장비를 착용해 공격력이 올라가는 경우에도 Attribute가 변경됩니다.

3. Gameplay Effect

Gameplay Effect는 캐릭터의 Attribute에 변화를 주거나 특정 상태를 적용하는 역할을 합니다.

즉시 피해를 입히거나 체력을 회복하는 효과뿐만 아니라, 일정 시간 동안 공격력을 증가시키는 버프나 지속적으로 체력을 감소시키는 독 효과도 표현할 수 있습니다.

Gameplay Effect는 적용 시간에 따라 대략 다음과 같이 구분할 수 있습니다.

즉시 적용되는 피해 또는 회복
일정 시간 동안 유지되는 버프와 디버프
제거될 때까지 계속 유지되는 효과

“어떤 변화가 발생하는가?”를 담당하는 요소라고 이해하면 편합니다.

4. Gameplay Tag

Gameplay Tag는 캐릭터의 상태나 스킬의 분류를 표현하는 계층형 태그입니다.

예를 들면 다음과 같은 형태로 사용할 수 있습니다.

State.Stunned
State.Dead
State.Silenced
Ability.Attack
Ability.Skill.Fire
Effect.Buff.Speed

캐릭터에게 State.Stunned 태그가 있다면 공격이나 이동 능력을 사용할 수 없도록 설정할 수 있습니다. State.Dead 태그가 있다면 대부분의 스킬을 차단할 수도 있습니다.

문자열이나 여러 개의 불리언 변수로 상태를 관리하는 것보다 일관된 규칙을 만들기 쉽다는 장점이 있습니다.

5. Ability System Component

Ability System Component, 줄여서 ASC는 GAS의 주요 기능을 실제 액터와 연결하는 중심 컴포넌트입니다.

캐릭터가 보유한 어빌리티와 적용된 이펙트, 현재 활성화된 태그 등의 정보를 관리합니다. 플레이어 캐릭터뿐만 아니라 몬스터나 상호작용 가능한 오브젝트에도 필요에 따라 적용할 수 있습니다.

처음에는 ASC의 내부 동작까지 모두 이해하기보다, 캐릭터가 GAS의 기능을 사용하도록 연결해 주는 중심 관리자 정도로 알아두면 충분합니다.

GAS는 어떤 흐름으로 동작할까?

화염구 스킬을 GAS로 구현했다고 가정해 보겠습니다.

먼저 플레이어가 스킬 버튼을 누르면 화염구에 해당하는 Gameplay Ability의 실행을 요청합니다. 어빌리티는 마나가 충분한지, 쿨타임이 끝났는지, 캐릭터가 스킬을 사용할 수 있는 상태인지 확인합니다.

조건을 만족하면 어빌리티가 실행되고 마나를 소비합니다. 이후 화염구가 적에게 적중하면 피해를 담당하는 Gameplay Effect가 대상에게 적용됩니다. 대상의 방어력 등을 계산한 뒤 체력 Attribute가 감소합니다.

필요하다면 화상 효과를 추가하여 일정 시간 동안 지속 피해를 입힐 수도 있습니다.

언리얼 엔진 GAS의 Gameplay Ability, Gameplay Effect, Attribute, Gameplay Tag와 Ability System Component의 관계를 나타낸 구조도

GAS의 장점

GAS의 가장 큰 장점은 스킬과 상태를 일정한 방식으로 관리할 수 있다는 점입니다.

스킬마다 별도의 방식으로 쿨타임과 비용을 구현하지 않아도 되고, 피해나 회복 같은 효과도 재사용할 수 있습니다. Gameplay Tag를 이용하면 캐릭터의 상태와 스킬 사용 조건을 비교적 명확하게 표현할 수 있습니다.

또한 GAS는 네트워크 환경을 고려하여 설계되어 있습니다. 서버 권한 처리와 클라이언트 예측 같은 멀티플레이 기능을 지원하기 때문에, 온라인 액션 게임을 개발할 때 특히 유용합니다.

물론 GAS가 네트워크 문제를 자동으로 모두 해결해 주는 것은 아닙니다. 하지만 관련 기능을 처음부터 직접 만드는 것보다 훨씬 체계적인 기반 위에서 시작할 수 있습니다.

모든 프로젝트에 GAS가 필요할까?

GAS가 강력한 시스템인 것은 맞지만, 모든 프로젝트에서 반드시 사용해야 하는 것은 아닙니다.

스킬의 수가 적고 캐릭터의 상태도 단순한 게임이라면 직접 만든 시스템이 더 빠르고 이해하기 쉬울 수 있습니다. 반대로 다양한 캐릭터와 스킬, 능력치, 버프 및 디버프가 등장한다면 GAS를 사용하는 장점이 커집니다.

특히 다음과 같은 게임에서 활용하기 좋습니다.

다양한 스킬을 사용하는 액션 RPG
여러 영웅이 등장하는 MOBA
버프와 상태이상이 많은 게임
캐릭터 빌드와 장비 효과가 중요한 게임
멀티플레이 전투가 중심인 게임

마무리

GAS는 단순한 스킬 제작 기능이라기보다, 캐릭터의 행동과 능력치, 효과, 상태를 하나의 규칙 안에서 관리하기 위한 게임플레이 프레임워크입니다.

처음 접하면 Ability, Effect, Attribute, Tag처럼 알아야 할 개념이 많아 어렵게 느껴질 수 있습니다. 하지만 각 요소의 역할을 구분해서 살펴보면 기본 구조는 생각보다 단순합니다.

정리하면 Gameplay Ability는 캐릭터의 행동을 담당하고, Gameplay Effect는 그 행동으로 발생하는 변화를 담당합니다. Attribute는 실제 수치를 저장하며, Gameplay Tag는 상태와 조건을 표현합니다. 그리고 Ability System Component가 이 요소들을 종합적으로 관리합니다.

GAS의 세부 기능을 처음부터 모두 공부하기보다는 간단한 공격이나 회복 스킬을 하나 만들어 보면서 각 요소가 어떻게 연결되는지 확인하는 것이 좋은 시작 방법입니다.

[UE5] 장비 슬롯과 숫자 단축키를 데이터 기반 무기 교체 시스템으로 연결하기

write76465 — Thu, 16 Jul 2026 18:58:30 +0900

기존에는 숫자 키를 누르면 블루프린트에 직접 작성한 RowName으로 무기를 교체했다.

1번 키 → AK47
2번 키 → Bubble
3번 키 → Pistol

이 방식은 빠르게 기능을 확인하기에는 좋지만, 장비창의 내용이 바뀌어도 단축키가 계속 기존 무기를 장착한다는 문제가 있다.

플레이어가 장비 슬롯 1에 어떤 무기를 넣었는지와 관계없이 1번 키가 항상 AK47을 요청하기 때문이다.

이번 작업에서는 숫자 키에 특정 무기를 하드코딩하는 대신 다음과 같은 데이터 흐름을 만들었다.

숫자 키 입력
→ 대응하는 장비 슬롯 선택
→ 슬롯의 ItemRowName 확인
→ DT_Item에서 아이템 정보 조회
→ WeaponRowName 추출
→ 캐릭터에게 무기 교체 요청

이를 통해 장비창의 상태와 실제 캐릭터의 장착 무기를 연결했다.

1. 기존 구조의 문제

처음에는 캐릭터 블루프린트에 무기 RowName이 직접 작성돼 있었다.

1번 키 → EquipWeaponByRowName("AK47")
2번 키 → EquipWeaponByRowName("Bubble")
3번 키 → EquipWeaponByRowName("Pistol")

기존 블루프린트

이 구조에서는 UI 장비 슬롯과 실제 무기 교체가 서로 독립적으로 동작한다.

예를 들어 장비 슬롯 1의 무기를 AK47에서 다른 라이플로 교체해도 1번 키는 여전히 AK47을 장착한다.

장비 슬롯 1
→ 새로운 라이플

숫자 키 1
→ 여전히 AK47을 장착

즉, 화면에 표시되는 장비 상태와 캐릭터의 실제 장착 상태가 일치하지 않았다.

또한 무기가 추가될 때마다 캐릭터 블루프린트를 수정해야 했다.

신규 무기 추가
→ 데이터 테이블 Row 추가
→ 장비 UI 수정
→ 숫자 키 로직의 RowName 수정

데이터 테이블을 사용하고 있음에도 실제 선택 로직은 하드코딩에 의존하고 있었다.

2. 두 종류의 RowName 구분하기

현재 아이템 시스템에는 두 종류의 데이터 테이블이 존재한다.

아이템 데이터 테이블

DT_Item은 인벤토리와 UI에 필요한 정보를 관리한다.

Name
Description
Item Type
Mesh
Icon
Max Stack
Weapon Row Name
Price

무기 데이터 테이블

DT_Weapon은 실제 전투에 필요한 무기 데이터를 관리한다.

Weapon Type
Weapon Mesh
Damage
Magazine Size
Max Ammo
Fire Rate
Reload Time
Range
Recoil
Muzzle Flash
Tracer Effect

장비 슬롯에 저장된 값은 DT_Item의 RowName이다.

예를 들어:

장비 슬롯의 ItemRowName
→ AK47_Item

그러나 캐릭터의 EquipWeaponByRowName() 함수가 필요로 하는 값은 DT_Weapon의 RowName이다.

EquipWeaponByRowName에 필요한 값
→ AK47

따라서 슬롯의 RowName을 캐릭터에게 바로 넘기면 안 된다. 중간에 DT_Item을 조회해 Weapon Row Name을 추출해야 한다.

AK47_Item
→ DT_Item 조회
→ Weapon Row Name = AK47
→ DT_Weapon의 AK47 장착

이 관계를 명확히 분리하면 아이템 이름과 무기 데이터 이름이 반드시 같을 필요가 없다.

DT_Item RowName
→ Rifle_AK47_Item

DT_Item.WeaponRowName
→ Weapon_AK47

DT_Weapon RowName
→ Weapon_AK47

핵심 조건은 다음 하나다.

DT_Item.WeaponRowName
=
DT_Weapon.RowName

3. RowName 변경으로 발생할 수 있는 참조 문제

작업 중 권총의 RowName이 변경되면서 기본 무기가 정상적으로 생성되지 않는 문제도 확인했다.

기본 권총 장착 함수는 특정 문자열을 직접 사용하지 않고 WeaponDataMap의 Pistol 항목을 조회하고 있었다.

void APlayerCharacter::EquipDefaultWeapon()
{
    const FDataTableRowHandle DefaultWeaponData =
        GetWeaponDataRowByType(EWeaponType::Pistol);

    if (DefaultWeaponData.IsNull())
    {
        return;
    }

    EquipWeaponByRowName(DefaultWeaponData.RowName);
}

코드에 권총 이름이 하드코딩되어 있지 않더라도 블루프린트의 FDataTableRowHandle은 이전 RowName을 계속 참조할 수 있다.

DT_Weapon RowName 변경
→ 기존 DataTableRowHandle이 이전 이름을 참조
→ IsNull 또는 Row 조회 실패
→ 기본 권총 생성 실패

따라서 RowName을 변경할 때는 다음 참조를 함께 갱신해야 한다.

BP_PlayerCharacter
└─ WeaponDataMap
   └─ Pistol
      └─ RowName

DT_Item
└─ 권총 아이템
   └─ Weapon Row Name

이 문제를 통해 데이터 테이블의 RowName은 단순한 표시 이름이 아니라 시스템 사이를 연결하는 식별자라는 점을 확인했다.

RowName을 변경하는 작업은 사실상 데이터 키를 변경하는 작업이므로 모든 참조 지점을 함께 점검해야 한다.

4. 기존 장비 슬롯 구조 활용

WBP_Equipment에는 이미 네 개의 장비 슬롯 위젯이 존재했다.

WBP_EquipSlot_1
WBP_EquipSlot_2
WBP_EquipSlot_3
WBP_EquipSlot_소비

각 슬롯에는 생성 시점에 고유한 EquipSlotIndex가 설정돼 있었다.

WBP_EquipSlot_1 → Index 0
WBP_EquipSlot_2 → Index 1
WBP_EquipSlot_3 → Index 2
소비 슬롯       → Index 3

새로운 슬롯 배열을 추가하기보다 기존 슬롯 참조와 인덱스를 활용했다.

현재 요구사항은 다음과 같았다.

숫자 키 1
→ WBP_EquipSlot_1의 무기

숫자 키 2
→ WBP_EquipSlot_2의 무기

숫자 키 3
→ 고정 권총

따라서 키보드 번호와 내부 슬롯 인덱스를 다음처럼 매핑했다.

키보드 1 → Slot Index 0
키보드 2 → Slot Index 1

5. 슬롯 조회 함수를 별도로 만든 이유

숫자 키 이벤트마다 데이터 테이블 조회 로직을 작성하면 동일한 노드가 반복된다.

1번 키
→ Slot 1 ItemRowName
→ DT_Item 조회
→ WeaponRowName
→ 유효성 검사

2번 키
→ Slot 2 ItemRowName
→ DT_Item 조회
→ WeaponRowName
→ 유효성 검사

이 구조는 슬롯이 늘어날수록 중복이 증가한다.

따라서 WBP_Equipment 내부에 슬롯 번호를 받아 무기 RowName을 반환하는 함수를 만들었다.

GetWeaponRowNameBySlotIndex

입력:

Slot Index : Integer

출력:

Weapon Row Name : Name
Is Valid : Boolean

이 함수는 UI 내부 구조를 외부에 직접 노출하지 않고, 외부에서는 슬롯 인덱스만 전달하도록 만든다.

외부
→ 0번 슬롯의 무기 RowName을 요청

WBP_Equipment
→ 어떤 위젯이 0번인지 판단
→ DT_Item 조회
→ 최종 WeaponRowName 반환

캐릭터는 장비 슬롯 위젯의 내부 구조를 알 필요가 없다.

6. Switch on Int로 슬롯 선택

함수 입력으로 받은 Slot Index는 Switch on Int에 연결했다.

Slot Index
→ Switch on Int

분기는 다음처럼 구성했다.

0 → WBP_EquipSlot_1
1 → WBP_EquipSlot_2
Default → 유효하지 않은 요청

각 슬롯 위젯에서 Item Row Name을 가져온 뒤 공통 로컬 변수에 저장했다.

SelectedItemRowName

Switch 0
→ WBP_EquipSlot_1.ItemRowName
→ Set SelectedItemRowName

Switch 1
→ WBP_EquipSlot_2.ItemRowName
→ Set SelectedItemRowName

Switch On Int와 연결준비하는 모습

처음에는 슬롯마다 서로 다른 로컬 변수를 만들었지만, 그렇게 하면 이후 데이터 조회 로직을 공통으로 사용할 수 없다.

SelectedItemRowName
SelectedItemRowName01

두 분기가 같은 목적의 값을 선택하는 것이므로 하나의 로컬 변수로 합치는 것이 적절했다.

여러 입력 분기
→ 하나의 SelectedItemRowName
→ 공통 데이터 조회 로직

7. DT_Item에서 실제 WeaponRowName 추출

선택한 ItemRowName으로 DT_Item을 조회했다.

Get Data Table Row
Data Table = DT_Item
Row Name = SelectedItemRowName

조회에 성공하면 Break Item Data를 통해 Weapon Row Name을 추출한다.

SelectedItemRowName
→ Get Data Table Row(DT_Item)
→ Break Item Data
→ Weapon Row Name

이 과정이 필요한 이유는 장비 슬롯이 무기 데이터가 아니라 아이템 데이터를 보관하고 있기 때문이다.

장비 슬롯
→ 아이템의 정체성 및 UI 정보

DT_Item.WeaponRowName
→ 실제 무기 데이터로 이동하기 위한 참조

DT_Weapon
→ 전투 성능과 무기 Actor 생성 정보

즉, Weapon Row Name은 아이템 시스템과 무기 시스템 사이를 연결하는 외래 키와 비슷한 역할을 한다.

8. 성공과 실패를 명시적으로 반환

슬롯이 비어 있거나 데이터 테이블에서 Row를 찾지 못했을 때 무기 교체를 시도하면 안 된다.

따라서 함수 출력에 Is Valid를 추가했다.

성공 조건:

DT_Item Row Found
AND Weapon Row Name != None

성공 시:

Weapon Row Name = 조회된 WeaponRowName
Is Valid = true

실패 시:

Weapon Row Name = None
Is Valid = false

실패 경로는 다음 세 가지다.

지원하지 않는 Slot Index
DT_Item Row Not Found
Weapon Row Name이 None

연결완료된 최종함수

최종 함수 흐름은 다음과 같다.

Slot Index
→ Switch on Int
→ 해당 슬롯의 ItemRowName 선택
→ DT_Item 조회
→ WeaponRowName != None 검사
├─ 성공 → Return(WeaponRowName, true)
└─ 실패 → Return(None, false)

Is Valid를 별도로 반환함으로써 호출 측에서는 실패 원인을 다시 추론할 필요 없이 Branch 하나로 장착 가능 여부를 판단할 수 있다.

9. 숫자 키와 장비 슬롯 연결

캐릭터 블루프린트에는 인벤토리·장비 UI를 가리키는 InvenRef가 있었다.

이를 통해 WBP_Equipment에 접근한 뒤 새로 만든 함수를 호출했다.

숫자 1:

1 Pressed
→ InvenRef
→ WBP_Equipment
→ GetWeaponRowNameBySlotIndex(0)
→ Branch(Is Valid)
→ EquipWeaponByRowName

숫자 2:

2 Pressed
→ InvenRef
→ WBP_Equipment
→ GetWeaponRowNameBySlotIndex(1)
→ Branch(Is Valid)
→ EquipWeaponByRowName

숫자 3은 고정 권총이므로 기존처럼 권총 RowName을 전달했다.

3 Pressed
→ EquipWeaponByRowName(PistolRowName)

최종 블루프린트 노드

처음 연결했을 때 Branch의 Condition이 체크박스 true로 고정되어 있었다.

Branch Condition = true

이 상태에서는 빈 슬롯이거나 조회에 실패해도 무기 교체 함수가 실행된다.

이를 함수의 Is Valid 출력과 연결했다.

GetWeaponRowNameBySlotIndex.IsValid
→ Branch.Condition

이제 빈 슬롯을 선택하면 아무 작업도 수행하지 않는다.

10. 실제 무기 교체는 기존 서버 로직 활용

블루프린트에서는 최종적으로 EquipWeaponByRowName()만 호출한다.

void APlayerCharacter::EquipWeaponByRowName(
    FName WeaponRowName)
{
    if (WeaponRowName.IsNone())
    {
        return;
    }

    if (HasAuthority())
    {
        EquipWeaponByRowNameInternal(WeaponRowName);
    }
    else
    {
        ServerEquipWeaponByRowName(WeaponRowName);
    }
}

클라이언트에서 숫자 키를 눌렀다면 Server RPC를 통해 서버에 교체를 요청한다.

로컬 숫자 입력
→ 슬롯에서 WeaponRowName 추출
→ EquipWeaponByRowName
→ ServerEquipWeaponByRowName
→ 서버에서 무기 데이터 검증

내부에서는 전달받은 RowName이 실제 WeaponDataMap에 존재하는지도 다시 확인한다.

if (!FindWeaponByRowName(
    WeaponRowName,
    NewWeaponType,
    WeaponData))
{
    return;
}

따라서 UI가 반환한 RowName을 곧바로 신뢰하지 않고 서버가 보유한 데이터에서 다시 검증한다.

이후 무기 변경을 즉시 처리하지 않고 PendingWeaponRowName에 저장한다.

PendingWeaponRowName = WeaponRowName;
MulticastPlayEquipMontage(NewWeaponType);

무기 교체 몽타주의 ChangeWeapon 노티파이 시점에서 실제 무기를 교체한다.

숫자 키 입력
→ 서버에 RowName 전달
→ 무기 교체 몽타주 재생
→ ChangeWeapon Notify
→ CommitPendingWeaponChange
→ 기존 무기 제거
→ 새 무기 Actor 생성

이 구조 덕분에 손에 든 무기가 애니메이션 시작과 동시에 갑자기 바뀌지 않고, 몽타주에서 지정한 정확한 프레임에 교체된다.

11. 전체 데이터 흐름

최종 데이터 흐름은 다음과 같다.

숫자 키 1 입력
        │
        ▼
GetWeaponRowNameBySlotIndex(0)
        │
        ▼
WBP_EquipSlot_1.ItemRowName
        │
        ▼
DT_Item 조회
        │
        ▼
ItemData.WeaponRowName
        │
        ▼
EquipWeaponByRowName
        │
        ▼
Server RPC
        │
        ▼
DT_Weapon 및 WeaponDataMap 검증
        │
        ▼
PendingWeaponRowName
        │
        ▼
무기 교체 몽타주
        │
        ▼
ChangeWeapon Notify
        │
        ▼
새 무기 Actor 생성 및 장착

UI는 “어떤 아이템이 장비 슬롯에 들어 있는가”를 제공하고, 서버는 “해당 이름의 무기를 실제로 장착할 수 있는가”를 검증한다.

12. 구현하면서 어려웠던 점

ItemRowName과 WeaponRowName의 혼동

장비 슬롯에서 바로 얻을 수 있는 값은 DT_Item의 RowName이다. 이를 그대로 무기 장착 함수에 전달하면 DT_Weapon에서 Row를 찾지 못한다.

두 데이터 테이블의 역할과 식별자를 구분하는 것이 중요했다.

UI 상태와 실제 전투 상태의 연결

장비 UI에 아이콘이 표시되는 것과 캐릭터가 해당 무기를 장착하는 것은 별개의 시스템이다.

단순히 이미지가 슬롯에 들어갔다고 해서 캐릭터의 무기 Actor가 자동으로 변경되지는 않는다.

두 시스템 사이에 다음과 같은 명시적인 변환 과정이 필요했다.

UI 슬롯
→ 아이템 데이터
→ 무기 데이터 식별자
→ 서버 장착 요청

실패 경로 관리

정상적인 Row만 생각하면 장착 로직은 간단하다. 하지만 실제 플레이에서는 다음 상황이 발생할 수 있다.

빈 장비 슬롯
잘못된 슬롯 번호
변경된 RowName
삭제된 데이터 테이블 Row
WeaponRowName이 없는 일반 아이템

성공과 실패를 명시적으로 나눠 반환함으로써 잘못된 장착 요청을 차단했다.

애니메이션과 실제 Actor 교체 시점 분리

입력 즉시 무기를 교체하면 몽타주와 무기 메시 변경 시점이 맞지 않는다.

따라서 “교체 요청”과 “실제 교체”를 분리했다.

요청 시점
→ PendingWeaponRowName 기록

연출 시점
→ 교체 몽타주 재생

확정 시점
→ ChangeWeapon Notify에서 Actor 교체

13. 현재 구조의 한계와 개선 방향

현재 구현에서는 캐릭터가 InvenRef를 통해 장비 UI의 슬롯 값을 조회한다.

기능적으로는 동작하지만, UI 위젯이 장비 데이터의 실질적인 저장소 역할을 한다는 한계가 있다.

만약 장비창 위젯이 아직 생성되지 않았거나 제거된 상태라면 다음 오류가 발생할 수 있다.

Accessed None trying to read InvenRef

장기적으로는 장비 상태를 UI가 아닌 별도의 데이터 객체가 보유하는 것이 더 안정적이다.

권장 구조:

InventoryComponent 또는 EquipmentComponent
├─ EquippedSlot1ItemRowName
├─ EquippedSlot2ItemRowName
└─ FixedPistolRowName

WBP_Equipment
→ Component의 데이터를 표시

숫자 키 입력
→ Component의 데이터를 조회

이 구조에서는 UI를 열지 않았더라도 무기 교체가 가능하고, 서버 복제와 저장·불러오기도 쉬워진다.

현재 구조
Character → Widget → Slot Data

개선 구조
Character → EquipmentComponent
Widget    → EquipmentComponent

UI는 데이터를 소유하지 않고 표현만 담당하는 형태다.

이번 작업에서는 기존 구조의 변경 범위를 줄이기 위해 WBP_Equipment의 슬롯 데이터를 활용했지만, 시스템이 확장된다면 장비 상태를 Component 또는 PlayerState로 이동할 수 있다.

마무리

이번 작업은 숫자 키에 직접 작성된 무기 이름을 장비 슬롯 기반의 동적 선택 구조로 변경하는 작업이었다.

핵심은 단순히 1번과 2번 키를 연결하는 것이 아니라, 서로 다른 시스템 사이의 데이터 경계를 정리하는 것이었다.

장비 슬롯
→ ItemRowName 보유

DT_Item
→ WeaponRowName 제공

DT_Weapon
→ 실제 무기 성능 제공

Character
→ 서버에 장착 요청

Anim Notify
→ 실제 무기 변경 시점 확정

최종적으로 다음 효과를 얻었다.

숫자 키의 무기 RowName 하드코딩 제거
장비 슬롯 변경 내용이 단축키에 즉시 반영
빈 슬롯 및 잘못된 RowName 방어
아이템 데이터와 무기 데이터의 역할 분리
기존 서버 무기 장착 로직 재사용
몽타주 노티파이를 통한 자연스러운 교체 타이밍 유지

단순한 단축키 기능처럼 보이지만, UI·데이터 테이블·서버 RPC·Actor 생성·애니메이션 노티파이가 하나의 흐름으로 연결된 작업이었다.

[Unreal Engine 네트워크] HasAuthority()와 IsLocallyControlled()는 무엇이 다른가?

write76465 — Wed, 15 Jul 2026 20:52:11 +0900

Unreal Engine 멀티플레이를 처음 구현할 때 가장 혼동하기 쉬운 함수가 다음 두 가지다.

HasAuthority()
IsLocallyControlled()

두 함수 모두 “이 코드를 여기서 실행해도 되는가?”를 판단할 때 사용하지만, 확인하는 대상은 완전히 다르다.

HasAuthority()는 Actor의 상태를 결정할 권한을 확인한다.
IsLocallyControlled()는 Pawn을 현재 컴퓨터에서 직접 조종하는지 확인한다.

이 차이를 명확히 이해하지 못하면 다음과 같은 문제가 발생한다.

클라이언트에서만 Actor가 사라짐
호스트에서는 UI가 보이지만 원격 클라이언트에서는 보이지 않음
모든 플레이어 화면에 동일한 UI가 나타남
서버와 클라이언트의 Actor 상태가 달라짐
리슨 서버에서는 정상인데 전용 서버에서 동작하지 않음
RPC를 호출했지만 기대한 컴퓨터에서 실행되지 않음

이번 글에서는 두 함수의 정의뿐만 아니라 Authority, Ownership, Local Control이 각각 무엇을 의미하는지 근본적인 구조부터 정리한다.

1. 멀티플레이에서는 Actor가 하나만 존재하지 않는다

싱글플레이에서는 월드에 생성된 캐릭터가 하나의 프로그램 안에 하나만 존재한다.

하지만 네트워크 게임에서는 논리적으로 동일한 캐릭터가 서버와 각 클라이언트에 따로 존재한다.

플레이어 A와 B가 접속한 게임을 예로 들면 다음과 같다.

서버
├─ Player A 캐릭터
└─ Player B 캐릭터

클라이언트 A
├─ Player A 캐릭터 복제본
└─ Player B 캐릭터 복제본

클라이언트 B
├─ Player A 캐릭터 복제본
└─ Player B 캐릭터 복제본

코드상으로는 모두 APlayerCharacter일 수 있지만, 실제로는 서로 다른 프로세스 또는 월드에 존재하는 별개의 C++ 객체다.

따라서 아래 함수가 실행됐다는 사실만으로는 충분하지 않다.

void APlayerCharacter::Die()
{
}

네트워크 환경에서는 다음 질문이 추가로 필요하다.

어느 컴퓨터에서 실행됐는가?
서버의 Actor인가, 클라이언트의 복제본인가?
이 Actor의 권한은 누구에게 있는가?
현재 컴퓨터가 이 Pawn을 직접 조종하는가?

멀티플레이의 어려움은 같은 코드가 서로 다른 역할을 가진 여러 Actor 인스턴스에서 실행될 수 있다는 점에서 시작한다.

2. Authority란 무엇인가?

Authority는 특정 Actor의 최종 상태를 결정할 권한이다.

일반적인 서버 권한형 멀티플레이 게임에서는 서버에 존재하는 Actor가 Authority를 가진다.

if (HasAuthority())
{
    // 이 Actor의 권한을 가진 인스턴스에서 실행
}

HasAuthority()를 단순히 “현재 프로그램이 서버인가?”라고 이해할 수도 있지만, 더 정확한 질문은 다음과 같다.

현재 이 Actor 인스턴스가 이 Actor의 상태를 결정할 권한을 가지고 있는가?

Actor 기준으로 판단한다는 것이 중요하다.

일반적인 복제 Actor라면 다음과 같은 관계가 만들어진다.

서버의 Actor
→ Authority 보유

클라이언트의 Actor 복제본
→ Authority 없음

이를 코드로 확인하면 다음과 같다.

if (HasAuthority())
{
    UE_LOG(LogTemp, Warning, TEXT("Authority Actor"));
}
else
{
    UE_LOG(LogTemp, Warning, TEXT("Remote Actor Copy"));
}

3. 왜 서버가 Authority를 가져야 하는가?

멀티플레이 게임에서 모든 클라이언트가 상태를 마음대로 결정할 수 있다면 동일한 게임 상태를 유지할 수 없다.

예를 들어 클라이언트가 자신의 체력을 직접 수정할 수 있다고 가정해 보자.

CurrentHealth = 999999.f;

서버 검증 없이 이 값이 인정된다면 치팅에 매우 취약해진다. 또한 서로 다른 클라이언트가 각자 다른 값을 가지고 있을 수도 있다.

따라서 중요한 게임 상태는 서버가 결정한다.

대표적인 서버 권한 로직은 다음과 같다.

피해량 계산
체력 변경
사망 판정
탄약 소비
아이템 획득
점수 및 킬 카운트
Actor 생성과 제거
충돌 판정
리스폰
게임 승패 판정

void ACharacter::ApplyDamage(float Damage)
{
    if (!HasAuthority())
    {
        return;
    }

    CurrentHealth -= Damage;

    if (CurrentHealth <= 0.f)
    {
        Die();
    }
}

서버가 값을 확정한 뒤, 필요한 상태를 클라이언트에 복제한다.

클라이언트 입력
→ 서버에 요청
→ 서버가 유효성 검사
→ 서버가 상태 변경
→ 변경된 상태를 클라이언트에 복제

4. IsLocallyControlled()란 무엇인가?

IsLocallyControlled()는 Pawn 또는 Character가 현재 컴퓨터의 로컬 Controller에 의해 조종되고 있는지 확인한다.

if (IsLocallyControlled())
{
    // 이 컴퓨터에서 직접 조종하는 Pawn
}

클라이언트 A에는 자신의 캐릭터뿐만 아니라 다른 플레이어의 캐릭터 복제본도 존재한다.

클라이언트 A

Player A 캐릭터
→ 클라이언트 A가 직접 조종
→ IsLocallyControlled() == true

Player B 캐릭터
→ 네트워크를 통해 관찰하는 복제본
→ IsLocallyControlled() == false

따라서 Local Control은 서버 권한이 아니라 입력과 화면의 주체를 구분하기 위한 개념이다.

다음과 같은 로직에 주로 사용된다.

HUD 생성
개인 결과 UI
카메라 흔들림
크로스헤어 표시
로컬 입력 처리
마우스 커서 변경
카메라 FOV 변경
로컬 전용 사운드
1인칭 전용 메시 표시

if (IsLocallyControlled())
{
    ShowCrosshair();
    ApplyCameraRecoil();
}

다른 플레이어가 총을 발사했다고 내 화면의 카메라까지 흔들리면 안 되기 때문에 이러한 로컬 구분이 필요하다.

5. 두 함수는 반대 조건이 아니다

가장 흔한 오해는 다음과 같다.

HasAuthority() == 서버
IsLocallyControlled() == 클라이언트

이렇게 외우면 리슨 서버에서 문제가 생긴다.

HasAuthority()와 IsLocallyControlled()는 반대되는 개념이 아니다. 서로 다른 기준을 검사한다.

HasAuthority()
→ 상태를 결정할 권한이 있는가?

IsLocallyControlled()
→ 현재 컴퓨터에서 직접 조종하는가?

따라서 두 값이 동시에 참일 수도 있고 동시에 거짓일 수도 있다.

실행 환경대상 PawnHasAuthority()IsLocallyControlled()

리슨 서버	호스트의 Pawn	True	True
리슨 서버	원격 플레이어 Pawn	True	False
클라이언트 A	자신의 Pawn	False	True
클라이언트 A	다른 플레이어 Pawn	False	False
전용 서버	모든 플레이어 Pawn	True	False

이 표는 Unreal 네트워크 코드를 이해하는 데 매우 중요하다.

6. 리슨 서버에서 특히 혼동되는 이유

리슨 서버는 서버 역할을 수행하면서 동시에 로컬 플레이어도 가지고 있다.

따라서 호스트의 Pawn은 다음 조건을 모두 만족한다.

HasAuthority() == true
IsLocallyControlled() == true

이 때문에 잘못된 코드도 호스트에서는 정상처럼 보일 수 있다.

예를 들어 UI를 Authority 조건 안에서 생성했다고 가정해 보자.

if (HasAuthority())
{
    CreateResultWidget();
}

리슨 서버 호스트는 Authority를 가지면서 화면도 존재하므로 UI가 정상적으로 나타난다.

그러나 원격 클라이언트의 Pawn은 Authority가 없다.

리슨 서버 호스트
HasAuthority = true
→ UI 표시

원격 클라이언트
HasAuthority = false
→ UI 표시 안 됨

개발자가 호스트 화면만 확인하면 이 코드가 정상이라고 오해할 수 있다.

전용 서버에서는 화면 자체가 없으므로 Authority 조건 안에서 Widget을 생성해도 사용자에게 표시할 방법이 없다.

7. 전용 서버와 리슨 서버의 차이

리슨 서버

한 플레이어의 게임 프로세스가 서버와 클라이언트 역할을 동시에 수행한다.

리슨 서버 프로세스
├─ 서버 역할
└─ 호스트 플레이어의 로컬 화면과 입력

장점은 테스트와 소규모 멀티플레이 구성이 간단하다는 것이다. 단점은 Authority와 Local Control이 같은 프로세스에 존재하기 때문에 잘못된 실행 위치를 발견하기 어렵다는 것이다.

전용 서버

플레이어의 화면이나 입력 없이 서버 역할만 수행한다.

전용 서버
├─ 게임 규칙
├─ Actor 상태
├─ 판정
└─ 복제

화면 없음
로컬 플레이어 없음

전용 서버의 Pawn은 일반적으로 다음 상태다.

HasAuthority() == true
IsLocallyControlled() == false

따라서 UI와 카메라 코드는 전용 서버에서 실행할 필요가 없다.

8. Authority, Ownership, Local Control은 서로 다르다

Unreal 네트워크를 이해하기 어려운 가장 큰 이유는 비슷해 보이는 세 개념이 따로 존재하기 때문이다.

Authority

Actor의 최종 상태를 결정할 권한이다.

누가 상태를 변경할 수 있는가?

일반적으로 서버가 가진다.

Ownership

네트워크상에서 특정 Actor가 어느 Connection에 속하는지를 나타낸다.

이 Actor의 소유 클라이언트는 누구인가?

Ownership은 RPC 전달 방향과 연관된다. 특히 Client RPC와 Server RPC가 어느 연결을 통해 전달될지 결정할 때 중요하다.

Local Control

현재 컴퓨터에서 해당 Pawn을 직접 조종하는지를 나타낸다.

이 Pawn의 입력과 카메라가 현재 컴퓨터에 있는가?

이 세 개념을 한 문장으로 정리하면 다음과 같다.

Authority
→ 결정권

Ownership
→ 네트워크 연결의 소유 관계

Local Control
→ 현재 컴퓨터의 조작 관계

9. Authority와 Ownership이 다른 사례

서버는 모든 캐릭터에 대한 Authority를 가진다. 하지만 각각의 캐릭터는 서로 다른 클라이언트 Connection에 소유될 수 있다.

서버
├─ Player A Pawn — Authority 있음, Client A 소유
└─ Player B Pawn — Authority 있음, Client B 소유

따라서 서버가 Player A의 Controller에 Client RPC를 호출하면 Client A에 전달되고, Player B에게 호출하면 Client B에 전달된다.

UFUNCTION(Client, Reliable)
void Client_OpenResultUI();

PlayerAController->Client_OpenResultUI();

Authority는 서버에 있지만, RPC가 도착할 클라이언트는 Ownership으로 결정된다.

10. UI에는 왜 IsLocallyControlled()가 적합한가?

UI는 일반적으로 각 플레이어의 화면에만 존재해야 한다.

if (IsLocallyControlled())
{
    OpenInventoryUI();
}

클라이언트의 월드에는 여러 Pawn이 존재하더라도 현재 화면의 UI를 조작해야 하는 것은 로컬 Pawn뿐이다.

예를 들어 사망 UI를 아무 조건 없이 실행하면 다른 플레이어가 사망할 때도 내 화면에 결과 UI가 뜰 수 있다.

void ACharacter::OnDeath()
{
    OpenDeathUI(); // 모든 복제 Character에서 실행될 가능성
}

로컬 조건을 추가하면 자신의 Pawn에 대해서만 실행된다.

void ACharacter::OnDeath()
{
    if (IsLocallyControlled())
    {
        OpenDeathUI();
    }
}

다만 게임 설계에 따라 서버가 소유 PlayerController에 Client RPC를 보내 UI를 열도록 구성할 수도 있다.

if (HasAuthority())
{
    PlayerController->Client_OpenDeathUI();
}

두 방식 모두 가능하지만 책임을 섞지 않는 것이 중요하다.

11. Client RPC와 로컬 함수는 구분하는 것이 좋다

다음 함수가 있다고 가정해 보자.

UFUNCTION(Client, Reliable)
void Client_OpenResultUI();

Client RPC의 가장 명확한 사용 방식은 서버에서 소유 클라이언트를 대상으로 호출하는 것이다.

if (HasAuthority())
{
    PlayerController->Client_OpenResultUI();
}

실제 Widget 생성은 클라이언트의 _Implementation()에서 처리한다.

void AMyPlayerController::Client_OpenResultUI_Implementation()
{
    CreateResultWidget();
}

반면 이미 소유 클라이언트에서 실행 중이고 RPC가 필요 없다면 일반 로컬 함수를 분리하는 편이 의미가 명확하다.

void AMyPlayerController::OpenResultUILocal()
{
    CreateResultWidget();
}

if (IsLocallyControlled())
{
    PlayerController->OpenResultUILocal();
}

권장 구조는 다음처럼 역할을 분리하는 것이다.

UFUNCTION(Client, Reliable)
void Client_OpenResultUI();

void OpenResultUILocal();

void AMyPlayerController::Client_OpenResultUI_Implementation()
{
    OpenResultUILocal();
}

이렇게 하면 서버는 Client RPC를 호출하고, 클라이언트 내부에서는 로컬 함수를 재사용할 수 있다.

12. Actor 제거에는 왜 Authority가 필요한가?

복제 Actor를 클라이언트에서만 제거하면 서버에는 여전히 Actor가 존재할 수 있다.

if (IsLocallyControlled())
{
    Weapon->Destroy(); // 올바른 네트워크 생명주기가 아님
}

클라이언트에서는 무기가 사라진 것처럼 보이더라도 서버와 다른 클라이언트에는 계속 존재할 수 있다.

복제 Actor의 생성과 제거는 서버가 담당해야 한다.

if (HasAuthority() && IsValid(Weapon))
{
    Weapon->Destroy();
    Weapon = nullptr;
}

정상적인 Actor 생명주기는 다음과 같다.

서버가 Actor 생성
→ 클라이언트에 생성 복제
→ 서버가 Actor 제거
→ 클라이언트에 제거 복제

클라이언트가 시각적으로 먼저 감춰야 한다면 로컬 Hide와 서버 Destroy를 함께 사용할 수 있지만, 두 작업의 목적은 다르다.

Hide
→ 즉각적인 시각 처리

Destroy
→ 네트워크 Actor의 실제 생명주기 종료

13. SetVisibility()와 Destroy()의 차이

다음 두 코드는 의미가 완전히 다르다.

MeshComponent->SetVisibility(false);

Actor->Destroy();

SetVisibility(false)

Component가 화면에 렌더링되지 않도록 한다.
Actor는 여전히 월드에 존재한다.
Tick, Controller, 네트워크 참조 등이 유지될 수 있다.
충돌은 별도로 끄지 않으면 유지될 수 있다.

Destroy()

Actor의 생명주기를 종료한다.
서버에서 복제 Actor를 제거하면 클라이언트에도 제거가 전달된다.
기존 참조는 유효성을 다시 확인해야 한다.
Pawn을 제거하면 Controller의 Possess 관계에도 영향을 줄 수 있다.

따라서 사라져 보이게 하는 것과 실제로 제거하는 것은 별개의 설계 결정이다.

14. Replication은 함수를 자동으로 실행해 주는 시스템이 아니다

변수를 Replicated로 설정하면 서버의 값이 클라이언트에 전달된다.

UPROPERTY(ReplicatedUsing = OnRep_IsDead)
bool bIsDead;

void ACharacter::OnRep_IsDead()
{
    if (bIsDead)
    {
        PlayDeathAnimation();
    }
}

여기서 복제되는 것은 bIsDead라는 상태다. 서버에서 실행된 PlayDeathAnimation() 함수 자체가 자동으로 클라이언트에서 다시 실행되는 것은 아니다.

따라서 네트워크 코드는 보통 다음과 같이 구성한다.

서버가 상태 변경
→ 상태 복제
→ 클라이언트의 OnRep 함수 실행
→ 클라이언트가 상태에 맞는 연출 실행

이러한 상태 기반 구조는 RPC 한 번에 모든 것을 의존하는 것보다 뒤늦게 접속한 클라이언트나 네트워크 지연 상황에 대응하기 쉽다.

15. OnRep의 역할

OnRep 함수는 복제 변수가 클라이언트에서 변경됐을 때 후속 처리를 실행하기 위해 사용한다.

UPROPERTY(ReplicatedUsing = OnRep_Health)
float CurrentHealth;

UFUNCTION()
void OnRep_Health();

void ACharacter::OnRep_Health()
{
    UpdateHealthBar();
}

대표적인 사용 사례는 다음과 같다.

체력 UI 갱신
사망 애니메이션 재생
장착 무기 외형 변경
캐릭터 상태 이펙트 적용
문 개폐 상태 반영

서버는 실제 값을 결정하고 클라이언트는 복제된 값을 기반으로 시각적 결과를 구성한다.

16. RPC와 Replication의 차이

Replication

현재 상태를 전달한다.

현재 체력은 70이다.
현재 사망 상태는 true다.
현재 장착 무기는 Rifle이다.

상태가 중요한 경우에 적합하다.

RPC

특정 동작 또는 이벤트의 실행을 요청한다.

서버에 발사를 요청한다.
소유 클라이언트에게 UI를 열도록 요청한다.
모든 클라이언트에게 폭발 이펙트를 재생하도록 요청한다.

RPC 종류는 다음과 같다.

UFUNCTION(Server, Reliable)
void Server_Fire();

UFUNCTION(Client, Reliable)
void Client_OpenUI();

UFUNCTION(NetMulticast, Unreliable)
void Multicast_PlayFireEffect();

간단히 정리하면 다음과 같다.

방식의미

Replication	현재 상태 전달
Server RPC	클라이언트가 서버에 요청
Client RPC	서버가 특정 소유 클라이언트에 전달
Multicast RPC	서버가 관련 인스턴스 전체에 이벤트 전달

17. Reliable을 항상 사용하면 안 되는 이유

RPC에 Reliable을 붙이면 반드시 전달돼야 하는 메시지로 처리된다.

UFUNCTION(Server, Reliable)
void Server_ConfirmPurchase();

구매, 리스폰 요청, 중요한 상태 전환처럼 누락되면 안 되는 이벤트에 적합하다.

하지만 총알 트레이서나 반복 발소리처럼 빈번하게 발생하고 한두 번 누락돼도 게임 상태에 영향이 없는 이벤트에 Reliable을 남용하면 네트워크 큐에 부담이 생긴다.

UFUNCTION(NetMulticast, Unreliable)
void Multicast_PlayTracerEffect();

기준은 다음과 같다.

누락되면 게임 상태가 깨지는가?
→ Reliable 고려

누락돼도 다음 프레임이나 다음 효과로 복구되는가?
→ Unreliable 고려

18. 네트워크 디버깅이 어려운 근본적인 이유

멀티플레이 버그는 단일 실행 흐름으로 재현되지 않는다.

동일한 함수가 서버와 여러 클라이언트에서 각각 실행될 수 있으며, 로그도 서로 다른 프로세스에 출력될 수 있다.

따라서 단순히 아래 로그만 남기면 정보가 부족하다.

UE_LOG(LogTemp, Warning, TEXT("Function Called"));

다음 정보를 함께 출력하는 것이 좋다.

UE_LOG(
    LogTemp,
    Warning,
    TEXT(
        "Actor=%s | Authority=%d | Local=%d | LocalRole=%d | RemoteRole=%d"
    ),
    *GetName(),
    HasAuthority(),
    IsLocallyControlled(),
    static_cast<int32>(GetLocalRole()),
    static_cast<int32>(GetRemoteRole())
);

PlayerController나 네트워크 모드를 추가로 출력할 수도 있다.

UE_LOG(
    LogTemp,
    Warning,
    TEXT("NetMode=%d | Controller=%s"),
    static_cast<int32>(GetNetMode()),
    *GetNameSafe(GetController())
);

이렇게 해야 다음을 구분할 수 있다.

서버에서 실행된 로그
소유 클라이언트에서 실행된 로그
다른 플레이어의 복제본에서 실행된 로그
리슨 서버 호스트에서 실행된 로그

19. 자주 발생하는 실수

UI를 Authority 조건으로만 처리

if (HasAuthority())
{
    OpenUI();
}

리슨 서버 호스트에서는 보일 수 있지만 원격 클라이언트 화면에는 표시되지 않을 수 있다.

Actor 상태를 Local Control 조건으로 변경

if (IsLocallyControlled())
{
    CurrentHealth = 0.f;
}

클라이언트 로컬 값만 변경되고 서버의 권위 상태와 충돌할 수 있다.

Multicast RPC를 클라이언트에서 호출

Multicast_PlayEffect();

NetMulticast RPC는 일반적으로 서버에서 호출해야 관련 클라이언트로 전달된다. 클라이언트에서 호출하면 전체에 전파되지 않고 로컬 실행에 그칠 수 있다.

리슨 서버 호스트에서만 테스트

호스트 Pawn은 Authority와 Local Control을 동시에 가지므로 실행 위치가 잘못된 코드를 발견하기 어렵다.

모든 것을 Reliable RPC로 구현

빈번한 연출 이벤트까지 Reliable로 전송하면 패킷 지연과 RPC 큐 적체를 유발할 수 있다.

20. 네트워크 로직을 작성할 때 먼저 물어야 할 질문

코드부터 작성하기 전에 해당 기능의 책임을 정해야 한다.

첫 번째 질문

이 값이 게임 결과에 영향을 주는가?

그렇다면 서버 Authority가 결정해야 한다.

체력, 피해, 탄약, 아이템, 점수, 사망, 리스폰
→ 서버

두 번째 질문

특정 플레이어의 화면에만 필요한가?

그렇다면 Local Control 또는 소유 Client RPC가 적합하다.

HUD, 카메라, 입력 모드, 개인 결과 UI
→ 소유 클라이언트

세 번째 질문

다른 플레이어에게도 보여야 하는 연출인가?

복제 변수, OnRep 또는 서버 Multicast RPC를 고려한다.

사망 애니메이션, 발사 이펙트, 폭발, 피격 연출
→ 관련 클라이언트

네 번째 질문

현재 상태인가, 순간 이벤트인가?

상태
→ Replication

순간 이벤트
→ RPC 또는 복제 상태 변경에 대한 OnRep

21. 권장 책임 분리 예시

void ACharacter::Die()
{
    if (!HasAuthority())
    {
        return;
    }

    bIsDead = true;
    OnRep_IsDead();

    AMyPlayerController* MyController =
        Cast<AMyPlayerController>(GetController());

    if (IsValid(MyController))
    {
        MyController->Client_OpenDeathUI();
    }
}

void ACharacter::OnRep_IsDead()
{
    if (bIsDead)
    {
        PlayDeathAnimation();
    }
}

void AMyPlayerController::Client_OpenDeathUI_Implementation()
{
    OpenDeathUILocal();
}

이 구조에서는 책임이 분명하다.

서버
→ 사망 상태 결정

Replication과 OnRep
→ 모든 관련 화면에 사망 상태 반영

Client RPC
→ 소유 플레이어에게만 UI 표시

다만 사망 애니메이션이 끝난 뒤 UI를 열어야 한다면 서버 시간 기준으로 UI를 요청하거나, 소유 클라이언트가 복제 상태를 받은 뒤 로컬 연출 종료 시 UI를 표시하는 구조를 선택할 수 있다.

어느 방식이든 중요한 것은 실행 주체를 의도적으로 결정하는 것이다.

마무리

HasAuthority()와 IsLocallyControlled()는 모두 조건문에 사용되지만 해결하는 문제가 다르다.

HasAuthority()
→ 누가 게임 상태를 결정하는가?

IsLocallyControlled()
→ 누가 이 Pawn을 현재 컴퓨터에서 조종하는가?

그리고 여기에 Ownership까지 더해진다.

Ownership
→ 이 Actor가 어느 클라이언트 Connection에 속하는가?

멀티플레이 개발에서 어려운 점은 문법이 아니라 하나의 기능이 여러 컴퓨터에 걸쳐 실행된다는 사실이다. 같은 Actor 클래스와 같은 함수라도 실행 위치에 따라 역할과 결과가 달라진다.

따라서 네트워크 코드를 작성할 때는 항상 다음을 먼저 정해야 한다.

누가 결정하는가?
누구에게 보여야 하는가?
누가 입력하는가?
어느 인스턴스에서 실행되는가?
결과를 상태로 복제할 것인가, 이벤트로 전달할 것인가?

이 기준을 명확히 하면 Authority, Local Control, Ownership, RPC, Replication을 개별 문법이 아니라 하나의 네트워크 책임 모델로 이해할 수 있다.

[UE5] 애니메이션 문제처럼 보였던 이동 버그를 무기 충돌에서 찾아내기까지

write76465 — Wed, 15 Jul 2026 19:59:18 +0900

오늘은 캐릭터의 전투 디테일을 개선하면서 다음 기능을 정리했다.

권총과 라이플 재장전 애니메이션 분리
조준 중 달리기 상태 전환
무기 장착 위치 및 트레이서 이펙트 점검
이동 중 발생하던 캐릭터 위치 보정 현상 해결
애니메이션 노티파이를 이용한 발소리 구현
사망 몽타주 이후 캐릭터 숨김 및 결과 UI 연결
결과 UI 종료 후 기존 GameMode 리스폰 흐름 유지

단순히 기능을 추가하는 작업보다, 서로 다른 시스템이 영향을 주면서 발생한 문제의 원인을 추적하는 과정이 핵심이었다.

1. 아래를 조준하면 캐릭터가 뒤로 가속되는 현상

문제 상황

캐릭터가 아래를 조준한 상태에서 전진 입력을 하면 다음 현상이 발생했다.

전진 키를 눌렀는데 캐릭터가 뒤로 이동
일반적인 이동 속도보다 훨씬 빠르게 밀림
재장전 중 이동하면 원래 위치로 돌아가려는 듯한 보정 발생
클라이언트에서는 이동이 끊기는 현상까지 발생

처음에는 Aim Offset 또는 몽타주의 Root Motion 문제로 판단했다.

실제로 Aim Pitch 연결을 제거하면 증상이 사라졌기 때문에 애니메이션 그래프가 직접적인 원인처럼 보였다.

초기 가설

다음 항목을 차례대로 확인했다.

발사·재장전 몽타주의 Root Motion
Layered Blend per Bone의 하체 영향 여부
Aim Offset의 Pitch 범위
이동 방향 계산 코드
네트워크 Character Movement 보정
캐릭터 캡슐과 메시의 이동 여부

캐릭터 이동은 컨트롤러의 Yaw만 사용하고 있었다.

void APlayerCharacter::Move(const FInputActionValue& Value)
{
    const FVector2D MovementVector = Value.Get<FVector2D>();

    if (Controller != nullptr)
    {
        const FRotator Rotation = Controller->GetControlRotation();
        const FRotator YawRotation(0.f, Rotation.Yaw, 0.f);

        const FVector ForwardDirection =
            FRotationMatrix(YawRotation).GetUnitAxis(EAxis::X);

        const FVector RightDirection =
            FRotationMatrix(YawRotation).GetUnitAxis(EAxis::Y);

        AddMovementInput(ForwardDirection, MovementVector.X);
        AddMovementInput(RightDirection, MovementVector.Y);
    }
}

Pitch를 이동 방향에 사용하지 않으므로, 아래를 조준한다고 해서 이동 벡터 자체가 반대로 계산될 가능성은 낮았다.

또한 디버깅 결과, 시각적인 캐릭터 메시뿐 아니라 실제 CapsuleComponent까지 함께 끌려가고 있었다.

이 시점에서 문제를 단순 애니메이션 왜곡이 아닌, 실제 충돌에 의해 Character Movement가 영향을 받는 문제로 좁힐 수 있었다.

2. 실제 원인은 장착된 무기의 Collision이었다

원인 분석

캐릭터가 들고 있는 무기 메시가 충돌 가능한 상태로 유지되고 있었다.

무기는 캐릭터 메시의 소켓에 부착되어 Aim Offset과 몽타주에 따라 움직인다. 캐릭터가 아래를 조준하면 무기 메시 역시 아래쪽 또는 캐릭터 캡슐 내부로 크게 회전한다.

이때 무기 충돌이 다음 대상과 겹칠 수 있다.

캐릭터 자신의 CapsuleComponent
캐릭터 Skeletal Mesh
바닥 또는 벽
주변 월드 오브젝트

Character Movement는 충돌을 해결하기 위해 캡슐 위치를 보정한다. 따라서 겉으로는 Aim Offset이나 몽타주가 캐릭터를 이동시키는 것처럼 보였지만, 실제 흐름은 다음과 같았다.

Aim Pitch 변경
→ 손과 무기 위치 변경
→ 무기 Collision이 캡슐 또는 월드와 겹침
→ 충돌 해소를 위한 캐릭터 위치 보정
→ 캐릭터가 뒤로 밀리거나 순간 가속

네트워크 환경에서는 서버가 계산한 위치와 클라이언트가 예측한 위치가 달라지기 때문에 이 문제가 끊김과 되감기처럼 나타났다.

해결

장착 무기는 전투 판정을 담당하는 물리 객체가 아니므로 메시 충돌과 물리 시뮬레이션을 비활성화했다.

MeshComponent->SetCollisionEnabled(ECollisionEnabled::NoCollision);
MeshComponent->SetCollisionResponseToAllChannels(ECR_Ignore);
MeshComponent->SetGenerateOverlapEvents(false);
MeshComponent->SetSimulatePhysics(false);

이를 ApplyWeaponData()처럼 무기 메시가 확정되는 시점에 적용했다.

void AWeaponBase::ApplyWeaponData()
{
    if (WeaponDataRow.IsNull())
    {
        return;
    }

    const FWeaponData* WeaponData =
        WeaponDataRow.GetRow<FWeaponData>(TEXT("Weapon"));

    if (WeaponData == nullptr)
    {
        return;
    }

    CurrentWeaponData = *WeaponData;

    if (CurrentWeaponData.WeaponMesh)
    {
        MeshComponent->SetStaticMesh(CurrentWeaponData.WeaponMesh);
    }

    MeshComponent->SetCollisionEnabled(ECollisionEnabled::NoCollision);
    MeshComponent->SetCollisionResponseToAllChannels(ECR_Ignore);
    MeshComponent->SetGenerateOverlapEvents(false);
    MeshComponent->SetSimulatePhysics(false);

    MeshComponent->SetRelativeLocation(
        CurrentWeaponData.AttachLocationOffset);

    MeshComponent->SetRelativeRotation(
        CurrentWeaponData.AttachRotationOffset);

    MeshComponent->SetRelativeScale3D(
        CurrentWeaponData.AttachScale);

    CurrentMagazineAmmo = CurrentWeaponData.MagazineSize;
    CurrentReserveAmmo = CurrentWeaponData.MaxAmmo;
}

결과

이 변경으로 다음 문제가 동시에 해결됐다.

아래를 조준할 때 뒤로 빠르게 이동하던 문제
재장전 중 이동하면 원래 위치로 끌려가던 문제
클라이언트 이동이 끊겨 보이던 문제
무기가 주변 지형과 충돌하면서 위치가 흔들리던 문제

핵심 회고

증상이 애니메이션 입력에 따라 발생한다고 해서 원인도 반드시 애니메이션인 것은 아니다.

Aim Offset은 직접 캐릭터를 이동시키지 않았지만, 무기 충돌 상태를 변화시켜 간접적으로 Character Movement에 영향을 줬다. 원인을 찾을 때는 “어떤 기능을 실행했을 때 발생했는가”와 “어떤 시스템이 실제 위치를 변경했는가”를 분리해서 봐야 했다.

3. Skeletal Mesh와 Static Mesh 변경으로 발생한 장착 오차

문제 상황

에디터의 WeaponSocket에 배치한 무기와 실제 게임에서 생성된 무기의 위치가 서로 달랐다.

소켓 위치를 수정해도 런타임 결과가 예상대로 바뀌지 않았고, 무기의 피벗과 충돌도 기존과 다른 형태로 동작했다.

Weaponsocket 프리뷰

원인

기존 무기 구조는 Skeletal Mesh 기준이었지만, 병합 과정에서 무기가 Static Mesh 기반으로 변경되어 있었다.

두 메시 타입은 같은 무기 외형을 사용하더라도 다음 정보가 다를 수 있다.

에셋 원점과 피벗
기본 회전축
임포트 Transform
Collision 설정
소켓과 머즐 위치를 표현하는 방식

따라서 기존 Skeletal Mesh를 기준으로 조정한 소켓과 오프셋이 Static Mesh에 그대로 적용될 것이라고 가정하면 안 된다.

개선 방향

장착 Transform의 책임을 명확히 분리했다.

WeaponSocket: 캐릭터 손을 기준으로 한 공통 장착 기준점
데이터 테이블의 Offset: 무기별 피벗 차이 보정
Muzzle 위치: 실제 무기 메시 또는 전용 SceneComponent 기준
Collision: 장착 직후 강제로 비활성화

CurrentWeapon->AttachToComponent(
    GetMesh(),
    FAttachmentTransformRules::SnapToTargetNotIncludingScale,
    TEXT("WeaponSocket")
);

그 이후 각 무기 데이터의 상대 Transform을 적용한다.

MeshComponent->SetRelativeLocation(
    CurrentWeaponData.AttachLocationOffset);

MeshComponent->SetRelativeRotation(
    CurrentWeaponData.AttachRotationOffset);

MeshComponent->SetRelativeScale3D(
    CurrentWeaponData.AttachScale);

이 구조를 사용하면 공통 소켓을 유지하면서도 권총과 라이플의 피벗 차이를 데이터로 보정할 수 있다.

4. 조준 중에는 걷고, 조준 해제 후 다시 달리기

요구사항

달리기 키를 계속 누르고 있는 상태에서 조준했을 때:

조준 중에는 걷기 속도로 전환
달리기 입력 상태는 유지
조준을 해제하면 다시 자동으로 달리기

단순히 조준 시작 시 StopSprint()를 호출하면 달리기 입력 상태까지 제거되어, 조준을 해제한 뒤 달리기 키를 다시 눌러야 한다.

따라서 물리적인 입력 상태와 현재 적용 중인 이동 상태를 분리해야 한다.

bSprintInputHeld
    달리기 키를 현재 누르고 있는가?

bIsAiming
    현재 조준 상태인가?

실제 달리기
    bSprintInputHeld && !bIsAiming

조준 시작 시에는 달리기 요청을 지우지 않고 속도만 걷기로 바꾼다.

조준 종료 시 달리기 키가 여전히 눌려 있다면 다시 달리기 속도를 적용한다.

이 방식은 입력 의도와 캐릭터 상태를 분리하기 때문에 재장전, 피격, 스태미나 부족 등 새로운 상태가 추가돼도 확장하기 쉽다.

5. 애니메이션 노티파이를 이용한 발소리 처리

설계 목표

권총과 라이플뿐 아니라 전후좌우 애니메이션이 각각 존재했다. 각 애니메이션마다 별도 발소리 로직을 작성하면 중복이 급격하게 늘어난다.

대신 애니메이션에는 “발이 바닥에 닿은 시점”만 기록하고, 실제 사운드 재생은 AnimBP에서 공통 처리했다.

애니메이션 노티파이

각 이동 애니메이션에서 기존 L/R 발 접지 타이밍에 다음 Skeleton Notify를 추가했다.

Footstep_L
Footstep_R

발 접지 타이밍에 맞춘 노티파이

AnimBP에서는 각 노티파이 이벤트를 받아 발 소켓 위치를 구했다.

AnimNotify_Footstep_L
→ Get Owning Component
→ Get Socket Location("foot_l")
→ Spawn Sound at Location

AnimNotify_Footstep_R
→ Get Owning Component
→ Get Socket Location("foot_r")
→ Spawn Sound at Location

발 위치에서 재생하는 이유

캐릭터 Actor Location에서 사운드를 재생하면 양발의 위치 차이가 사라진다. 발 소켓 위치를 사용하면 다음 기능으로 확장하기 쉽다.

왼발과 오른발의 공간감 표현
지면 Physical Material 감지
바닥 재질별 사운드 변경
발자국 데칼 및 먼지 이펙트 생성
네트워크 원격 플레이어의 3D 발소리 처리

BlendSpace에서는 여러 애니메이션이 동시에 평가될 때 중복 노티파이가 발생할 수 있으므로 Notify Trigger Mode도 함께 확인해야 한다. 대표 애니메이션 하나의 노티파이만 사용하려면 Highest Weighted Animation이 적합하다.

6. 사망 몽타주와 결과 UI, 리스폰 흐름 정리

기존 흐름 분석

사망 상태는 PlayerState가 관리하고 있었다.

서버에서 피해 처리
→ 체력 0 확인
→ PlayerState의 bIsDead 변경
→ OnRep_bIsDead
→ OnPlayerbIsDeadChanged 델리게이트 Broadcast
→ Character의 OnbIsDeadChanged
→ Die()
→ 사망 몽타주 재생
→ OnDeathMontageEnded()

여기에는 두 종류의 델리게이트가 사용된다.

OnPlayerbIsDeadChanged: PlayerState 사망 상태 변경을 전달하는 Dynamic Multicast Delegate
FOnMontageEnded: 사망 몽타주 종료 시점을 전달하는 몽타주 델리게이트

결과 UI는 로컬 플레이어 화면에만 생성해야 하므로 기존 IsLocallyControlled() 조건을 유지했다.

if (IsLocallyControlled())
{
    AMyPlayerController* PlayerControllerES =
        Cast<AMyPlayerController>(GetController());

    if (IsValid(PlayerControllerES))
    {
        PlayerControllerES->Client_OpenResultUI();
    }
}

캐릭터를 즉시 Destroy하면 안 되는 이유

처음에는 사망 몽타주 종료 후 캐릭터를 즉시 제거하려고 했다.

하지만 기존 GameMode 리스폰 코드는 결과 UI 입력 이후 현재 Pawn을 가져와 제거하고 새 Pawn을 생성하는 구조였다.

APawn* OldPawn = TargetController->GetPawn();

if (!IsValid(OldPawn))
{
    return;
}

OldPawn->Destroy();

RestartPlayerAtTransform(
    TargetController,
    MovePoint
);

사망 몽타주 종료 시 캐릭터를 먼저 Destroy()하면, 나중에 GameMode가 GetPawn()을 호출했을 때 유효한 Pawn을 얻지 못해 리스폰 함수가 중단될 수 있다.

따라서 캐릭터는 제거하지 않고 시각적으로만 숨겼다.

void APlayerCharacter::OnDeathMontageEnded(
    UAnimMontage* Montage,
    bool bInterrupted)
{
    if (USkeletalMeshComponent* MeshComp = GetMesh())
    {
        MeshComp->SetVisibility(false, true);
    }

    if (HasAuthority() && IsValid(CurrentWeapon))
    {
        CurrentWeapon->Destroy();
        CurrentWeapon = nullptr;
    }

    if (IsLocallyControlled())
    {
        AMyPlayerController* PlayerControllerES =
            Cast<AMyPlayerController>(GetController());

        if (IsValid(PlayerControllerES))
        {
            PlayerControllerES->Client_OpenResultUI();
        }
    }
}

무기만 서버에서 제거하는 이유

무기는 별도의 복제 Actor이므로 서버에서 제거해야 한다.

if (HasAuthority() && IsValid(CurrentWeapon))
{
    CurrentWeapon->Destroy();
    CurrentWeapon = nullptr;
}

서버에서 Destroy()하면 제거 상태가 클라이언트에 복제되므로, 별도로 숨긴 뒤 제거하는 이중 처리는 필수적이지 않다.

캐릭터는 GameMode의 리스폰 로직이 사용할 수 있도록 유지하고, 무기는 남아 있을 이유가 없으므로 서버에서 제거한다.

최종 사망·리스폰 흐름

사망 상태 복제
→ 사망 몽타주 재생
→ 몽타주 종료
→ 캐릭터 메시 숨김
→ 서버에서 장착 무기 제거
→ 로컬 플레이어에게 결과 UI 표시
→ 결과 UI 입력
→ GameMode가 기존 Pawn 제거
→ RestartPlayerAtTransform으로 새 Pawn 생성
→ 새 Pawn은 기본 Visibility로 정상 표시

마무리

오늘 작업에서 가장 큰 교훈은 애니메이션, 충돌, 네트워크 이동 보정이 서로 독립된 문제가 아니라는 점이었다.

특히 아래를 조준할 때 발생한 비정상 이동은 겉으로 보면 Aim Offset 또는 Root Motion 문제처럼 보였다. 하지만 캡슐까지 실제로 움직이는지 확인하고, 입력 벡터와 네트워크 이동 코드를 배제한 뒤 무기 충돌까지 추적하면서 실제 원인을 찾을 수 있었다.

또한 사망 처리에서는 단순히 “사라지게 만들기”보다 기존 리스폰 시스템이 어떤 Pawn 생명주기를 전제로 하는지 먼저 파악해야 했다. 즉시 제거 대신 가시성만 변경함으로써 기존 GameMode 구조를 깨지 않고 요구사항을 만족시켰다.

오늘 작업을 통해 다음 기준을 정리했다.

장착 무기는 기본적으로 Collision을 사용하지 않는다.
메시 타입이 바뀌면 피벗, 충돌, 소켓 기준을 다시 검증한다.
입력 유지 여부와 실제 이동 상태를 분리한다.
애니메이션은 이벤트 시점만 제공하고 기능은 공통 로직에서 처리한다.
로컬 UI와 서버 Actor 수명 관리를 명확히 분리한다.
기존 리스폰 흐름을 분석하기 전에는 Pawn을 조기에 제거하지 않는다.

단순한 기능 구현을 넘어, 여러 시스템 사이의 책임과 실행 순서를 정리한 작업이었다.

UE5 멀티플레이 캐릭터 전투 애니메이션과 무기 전환 타이밍 개선

write76465 — Tue, 14 Jul 2026 17:25:57 +0900

오늘은 이미 구현된 데이터 테이블 기반 무기 시스템 위에 캐릭터 전투 애니메이션을 연결하고, 캐릭터 상태와 실제 게임 로직이 불일치하는 문제를 개선했다.

주요 작업은 다음과 같다.

Rifle/Pistol 무기 타입별 발사 몽타주 분리
조준 상태에서 발사 반동이 사라지는 AnimGraph 문제 해결
달리기 중 발사를 서버에서 차단
달리기 중 조준 시 걷기 상태로 전환
무기 교체 시점을 몽타주 노티파이와 동기화
Aim Offset의 극단적인 Pitch로 인한 팔 관절 왜곡 방지

1. 무기 타입별 발사 몽타주 분리

기존 무기 시스템은 FWeaponData의 EWeaponType을 통해 현재 무기가 Rifle인지 Pistol인지 구분할 수 있었다.

따라서 무기 클래스에 애니메이션 정보를 중복으로 넣지 않고, 캐릭터가 무기 타입에 맞는 몽타주를 선택하도록 구성했다.

void APlayerCharacter::PlayAttackMontage(
    EWeaponType WeaponType)
{
    if (!GetMesh())
    {
        return;
    }

    UAnimInstance* AnimInstance =
        GetMesh()->GetAnimInstance();

    if (!AnimInstance)
    {
        return;
    }

    UAnimMontage* MontageToPlay = nullptr;

    switch (WeaponType)
    {
    case EWeaponType::Rifle:
        MontageToPlay = RifleAttackMontage;
        break;

    case EWeaponType::Pistol:
        MontageToPlay = PistolAttackMontage;
        break;

    default:
        break;
    }

    if (MontageToPlay)
    {
        AnimInstance->Montage_Play(MontageToPlay);
    }
}

무기의 Multicast 발사 이펙트에서 해당 함수를 호출해 모든 클라이언트가 발사 모션을 볼 수 있도록 했다.

PlayerCharacter->PlayAttackMontage(
    CurrentWeaponData.WeaponType
);

이 구조에서는 무기가 발사 사실과 무기 타입만 전달하고, 실제 캐릭터 애니메이션 선택은 캐릭터가 담당한다.

2. 조준 상태에서 발사 몽타주가 사라지는 문제

문제 상황

일반 상태에서는 발사 몽타주와 반동이 정상적으로 재생되었지만, 조준 상태로 전환하면 동일한 몽타주가 전혀 보이지 않았다.

처음에는 Rifle 몽타주나 무기 타입 판별 문제로 의심했지만, 실제 원인은 AnimGraph의 분기 구조였다.

기존 구조에서는 IsAiming으로 두 포즈를 나눈 뒤, UpperBody Slot이 비조준 분기에만 배치되어 있었다.

비조준 포즈 → UpperBody Slot
조준 포즈   → UpperBody Slot 우회
             ↓
       Blend Poses by Bool

따라서 조준 상태에서는 몽타주가 정상적으로 재생되더라도 최종 출력 포즈에 반영되지 않았다.

해결 방향

조준 여부에 따른 포즈 결정을 먼저 끝낸 뒤, 최종 포즈에 UpperBody Slot을 공통 적용하도록 구조를 변경했다.

Aim False Pose ─┐
                ├→ Blend Poses by Bool
Aim True Pose ──┘
                     ↓
             Layered Blend Per Bone
                     ↑
              Slot "UpperBody"

Layered Blend Per Bone은 하체 이동 애니메이션을 유지하면서 척추 위쪽에만 발사 몽타주가 적용되도록 설정했다.

권장 설정은 다음과 같다.

Branch Bone: spine_01 또는 spine_02
Blend Depth: 3~5
Mesh Space Rotation Blend: 활성화

이번 문제를 통해 몽타주가 “재생되지 않는 것”과 “재생되지만 최종 포즈에서 제거되는 것”은 구분해서 디버깅해야 한다는 점을 확인했다.

UpperBody가 False부분만 우회하는 상황

true부분도 추가한 모습

3. 달리기 애니메이션과 실제 발사 상태의 불일치

문제 상황

달리기 애니메이션에서는 캐릭터가 총을 아래로 내리고 있었지만, 실제 무기 로직에서는 여전히 발사가 가능했다.

이 문제는 애니메이션 상태를 곧바로 게임플레이 규칙으로 취급했기 때문에 발생했다.

총을 내리는 포즈는 시각적 표현일 뿐이며, 서버의 Fire() 함수에는 아무런 영향을 주지 않는다.

따라서 발사 가능 여부는 무기 로직에서 명시적으로 검사해야 한다.

bool AWeaponBase::CanFire() const
{
    if (OwnerCharacter &&
        OwnerCharacter->IsSprinting())
    {
        return false;
    }

    if (CurrentMagazineAmmo <= 0)
    {
        return false;
    }

    if (bIsReloading)
    {
        return false;
    }

    // 발사 간격 검사 생략

    return true;
}

캐릭터 내부 상태에 직접 접근하지 않고 Getter를 통해 확인하도록 했다.

bool APlayerCharacter::IsSprinting() const
{
    return bIsSprinting;
}

연사 타이머 문제

Fire() 내부에서만 CanFire()를 검사하면 달리는 동안 탄환은 발사되지 않더라도 연사 타이머가 계속 생성될 수 있다.

이 경우 달리기가 끝나는 순간, 버튼을 다시 누르지 않았는데도 타이머에 의해 발사가 재개될 가능성이 있다.

이를 막기 위해 StartFire() 진입 시점에도 검사를 추가했다.

void AWeaponBase::StartFire()
{
    if (!CanFire())
    {
        return;
    }

    switch (CurrentWeaponData.FireMode)
    {
    case EFireMode::Single:
        Fire();
        break;

    case EFireMode::Auto:
        Fire();

        GetWorld()->GetTimerManager().SetTimer(
            FireTimerHandle,
            this,
            &AWeaponBase::Fire,
            CurrentWeaponData.FireRate,
            true
        );
        break;

    case EFireMode::Burst:
        BurstCount = 0;
        BurstFire();
        break;
    }
}

달리기 시작 시 기존 연사와 점사 타이머도 종료했다.

void AWeaponBase::StopFire()
{
    if (!GetWorld())
    {
        return;
    }

    GetWorld()->GetTimerManager().ClearTimer(
        FireTimerHandle
    );

    GetWorld()->GetTimerManager().ClearTimer(
        BurstTimerHandle
    );

    BurstCount = 0;
}

즉, 발사 제한은 단순히 탄환 생성을 막는 데서 끝나지 않고, 발사 상태 머신과 타이머까지 함께 정리해야 했다.

4. 달리기 중 조준 입력 처리

초기 설계에서는 달리기와 조준을 동시에 유지하는 방향을 고려했지만, 최종적으로 다음 규칙을 적용했다.

달리기 중 조준 입력
→ 달리기 상태 종료
→ 이동 속도를 걷기로 변경
→ 조준 상태 진입
→ 발사 가능

StartAim()에서 로컬 캐릭터와 서버의 달리기 상태를 함께 종료했다.

void APlayerCharacter::StartAim()
{
    bIsAiming = true;
    bIsSprinting = false;

    if (UCharacterMovementComponent* MovementComp =
        GetCharacterMovement())
    {
        MovementComp->MaxWalkSpeed = WalkSpeed;
    }

    if (IsLocallyControlled())
    {
        ServerStopSprint();
    }

    SetActorTickEnabled(true);

    if (AimCameraCurve)
    {
        AimCameraTimeline.Play();
    }
    else
    {
        UpdateAimCamera(1.0f);
        SetActorTickEnabled(false);
    }
}

로컬에서 먼저 속도를 변경한 이유는 서버 응답을 기다리지 않고 즉각적인 조작감을 제공하기 위해서다.

서버에서는 최종적으로 bIsSprinting과 MaxWalkSpeed를 확정한다.

void APlayerCharacter::ServerStopSprint_Implementation()
{
    bIsSprinting = false;

    if (UCharacterMovementComponent* MovementComp =
        GetCharacterMovement())
    {
        MovementComp->MaxWalkSpeed = WalkSpeed;
    }
}

반대로 조준 중 달리기 입력은 무시하도록 처리했다.

void APlayerCharacter::StartSprint(
    const FInputActionValue& Value)
{
    if (bIsAiming)
    {
        return;
    }

    StopFire();

    bIsSprinting = true;

    if (UCharacterMovementComponent* MovementComp =
        GetCharacterMovement())
    {
        MovementComp->MaxWalkSpeed = 600.0f;
    }

    if (IsLocallyControlled())
    {
        ServerStartSprint();
    }
}

이렇게 애니메이션, 이동 속도, 발사 가능 여부가 하나의 상태 규칙을 공유하도록 맞췄다.

에임을 하면 걷는속도로 돌아가는 모습

5. 무기 교체 타이밍을 AnimNotify로 동기화

문제 상황

기존 무기 교체 코드는 다음 순서로 실행됐다.

기존 무기 제거 및 새 무기 생성
→ 캐릭터 소켓에 Attach
→ 장착 몽타주 재생

이 구조에서는 캐릭터가 기존 총을 내리기도 전에 새 무기로 변경되기 때문에 애니메이션과 실제 무기 Actor의 교체 타이밍이 어긋났다.

단순히 몽타주 재생 시간을 코드에 하드코딩할 수도 있지만, 애니메이션 길이나 재생 속도가 변경되면 다시 수정해야 한다.

따라서 몽타주에 ChangeWeapon 노티파이를 배치하고, 해당 시점을 실제 무기 교체의 커밋 지점으로 사용했다.

ChangeWeapon 노티파이

요청과 적용 단계 분리

무기 변경 요청이 들어왔을 때 바로 생성하지 않고, 변경할 RowName만 임시 저장한다.

UPROPERTY()
FName PendingWeaponRowName = NAME_None;

void APlayerCharacter::EquipWeaponByRowNameInternal(
    FName WeaponRowName)
{
    if (!HasAuthority() || WeaponRowName.IsNone())
    {
        return;
    }

    if (CurrentWeaponRowName == WeaponRowName &&
        IsValid(CurrentWeapon))
    {
        return;
    }

    EWeaponType NewWeaponType;
    FDataTableRowHandle WeaponData;

    if (!FindWeaponByRowName(
        WeaponRowName,
        NewWeaponType,
        WeaponData))
    {
        return;
    }

    if (bIsAiming)
    {
        CancelAimInstant();
    }

    PendingWeaponRowName = WeaponRowName;

    MulticastPlayEquipMontage(NewWeaponType);
}

이 시점에서는 몽타주만 재생되고 실제 무기는 변경되지 않는다.

ChangeWeapon 노티파이가 호출되면 Pending 데이터를 커밋한다.

void APlayerCharacter::CommitPendingWeaponChange()
{
    if (!HasAuthority() ||
        PendingWeaponRowName.IsNone())
    {
        return;
    }

    const FName WeaponRowName =
        PendingWeaponRowName;

    EWeaponType NewWeaponType;
    FDataTableRowHandle WeaponData;

    if (!FindWeaponByRowName(
        WeaponRowName,
        NewWeaponType,
        WeaponData))
    {
        PendingWeaponRowName = NAME_None;
        return;
    }

    if (!EquipWeaponActorFromRow(WeaponData))
    {
        PendingWeaponRowName = NAME_None;
        return;
    }

    CurrentWeaponType = NewWeaponType;
    CurrentWeaponRowName = WeaponRowName;

    PendingWeaponRowName = NAME_None;

    if (IsLocallyControlled())
    {
        BP_OnWeaponChanged(WeaponData);
    }
}

AnimBP에서는 다음 흐름으로 캐릭터 함수를 호출한다.

AnimNotify_ChangeWeapon
→ Try Get Pawn Owner
→ Cast To BP_PlayerCharacter
→ HandleChangeWeaponNotify

서버와 클라이언트에서 노티파이가 중복 실행될 가능성이 있기 때문에, 실제 변경은 서버에서만 수행하고 Pending 값을 커밋 직후 제거했다.

void APlayerCharacter::HandleChangeWeaponNotify()
{
    if (HasAuthority())
    {
        CommitPendingWeaponChange();
        return;
    }

    if (IsLocallyControlled())
    {
        ServerHandleChangeWeaponNotify();
    }
}

이 구조는 데이터 변경을 즉시 적용하지 않고, 실제로 적용 가능한 시점까지 보류했다가 커밋한다는 점에서 간단한 트랜잭션과 유사하다.

트러블슈팅 정리

오늘 해결한 문제들은 모두 애니메이션 자체보다 시스템 간 상태 동기화에서 발생했다.

문제직접적인 원인해결

조준 중 발사 몽타주 미출력	조준 분기가 UpperBody Slot을 우회	조준 포즈 결합 후 Slot 공통 적용
달리기 중 발사 가능	총을 내리는 애니메이션만 존재	서버 CanFire()에서 Sprint 검사
달리기 종료 후 연사 재개	발사 타이머가 계속 실행	StartFire() 선행 검사 및 타이머 제거
조준과 달리기 상태 충돌	시각 상태와 이동 속도가 별도 관리	조준 시 로컬·서버 달리기 동시 해제
무기 교체 타이밍 불일치	Actor 교체 후 몽타주 재생	Pending Row + AnimNotify Commit

마무리

이번 작업에서 가장 중요했던 부분은 애니메이션을 단순한 시각 효과가 아니라 게임플레이 상태 전환의 표현으로 정리한 것이다.

다만 최종 권한은 여전히 서버가 가진다.

발사 가능 여부는 서버가 판정한다.
달리기 상태는 서버가 확정한다.
무기 Actor의 생성과 교체는 서버가 수행한다.
몽타주 노티파이는 실제 변경 시점을 제공한다.
클라이언트는 카메라와 애니메이션을 즉시 반영해 반응성을 확보한다.

결과적으로 데이터 테이블 기반 무기 시스템을 유지하면서도 발사, 이동, 조준, 몽타주, 실제 무기 Actor가 서로 같은 상태 전환 시점을 공유하도록 개선할 수 있었다.

Hitscan 판정은 즉시, 총알은 보이게: UE5 Niagara 기반 네트워크 트레이서 구현기

write76465 — Tue, 14 Jul 2026 00:31:05 +0900

1. 문제 정의

기존 무기 시스템에는 이미 다음 기능이 구현돼 있었다.

카메라 기준 라인트레이스
총구 기준 보정 트레이스
서버 권한 데미지 처리
연사 및 재장전
데이터테이블 기반 무기 설정

하지만 발사 판정만 존재하고 시각적인 탄환 이동이 없어, 총을 쏘면 대상이 즉시 피격되는 느낌만 났다.

단순 Projectile Actor를 추가하면 구현은 직관적이지만, 기존 Hitscan 판정 구조를 다시 설계해야 하고 네트워크에서 Projectile 위치까지 복제해야 한다. 따라서 판정과 연출을 분리했다.

서버: Hitscan으로 즉시 판정 및 데미지 처리
클라이언트: Niagara로 총알이 이동하는 시각적 트레이서 재생

이 구조의 핵심은 Niagara가 실제 판정을 담당하지 않는다는 점이다. 시각적 탄환이 아직 날아가는 중이어도 서버 판정은 이미 끝났으며, 트레이서는 그 결과를 시각적으로 재현한다.

이미 팀원이 짜놓은 라인트레이싱 코드이다.

2. 데이터테이블 기반 이펙트 확장

무기별로 다른 트레이서 이펙트를 사용할 수 있도록 FWeaponData에 Niagara System 참조를 추가했다.

UPROPERTY(
    EditAnywhere,
    BlueprintReadWrite,
    Category = "Effects"
)
TObjectPtr<UNiagaraSystem> TracerEffect = nullptr;

이렇게 하면 무기 클래스에 AK47 전용 이펙트를 하드코딩하지 않고 데이터테이블에서 무기별 효과를 교체할 수 있다.

AK47 → NS_BulletTracer
Pistol → NS_PistolTracer
Sniper → NS_SniperTracer

무기의 데미지, 사거리, 연사 속도뿐 아니라 표현 리소스까지 데이터로 관리하는 구조가 된다.

무기 데이터테이블에 추가된 모습

3. 판정 좌표만 전송하고 이펙트는 각 클라이언트가 생성한다

트레이서를 네트워크로 동기화할 때 Niagara Component 자체를 복제하지 않았다. 서버가 확정한 시작점과 끝점만 전달하고, 각 클라이언트가 동일한 Niagara System을 로컬에서 생성한다.

UFUNCTION(NetMulticast, Unreliable)
void MulticastPlayFireEffects(
    FVector_NetQuantize MuzzleLocation,
    FVector_NetQuantize TracerEndLocation
);

여기서 Unreliable을 선택한 이유는 총구 화염과 트레이서가 일시적인 표현이기 때문이다. 한 번의 이펙트 패킷이 유실되더라도 게임 상태가 깨지지 않으며, 연사 중 Reliable RPC가 누적되는 문제를 피할 수 있다.

또한 FVector_NetQuantize로 좌표를 전달해 일반 FVector보다 네트워크 전송 비용을 줄였다.

if (HasAuthority())
{
    MulticastPlayFireEffects(
        MuzzleLocation,
        TracerEndLocation
    );
}

서버는 충돌 결과를 확정하고 좌표만 Multicast한다. 데미지 처리와 이펙트 재생의 책임이 명확하게 분리된다.

4. 첫 프레임 오염을 막기 위한 Niagara 활성화 순서

Niagara System을 생성하자마자 자동 실행하면, User Parameter를 넣기 전에 기본값 (0, 0, 0)으로 첫 프레임이 계산될 수 있다.

이를 막기 위해 bAutoActivate를 false로 설정했다.

UNiagaraComponent* TracerComponent =
    UNiagaraFunctionLibrary::SpawnSystemAtLocation(
        GetWorld(),
        CurrentWeaponData.TracerEffect,
        FVector(MuzzleLocation),
        FRotator::ZeroRotator,
        FVector::OneVector,
        true,                   // Auto Destroy
        false,                  // Auto Activate
        ENCPoolMethod::None,
        true
    );

그다음 좌표를 넣고 수동 활성화한다.

if (TracerComponent)
{
    TracerComponent->SetVariablePosition(
        TEXT("User.BeamStart"),
        FVector(MuzzleLocation)
    );

    TracerComponent->SetVariablePosition(
        TEXT("User.BeamEnd"),
        FVector(TracerEndLocation)
    );

    TracerComponent->Activate(true);
}

실행 순서는 다음과 같다.

Niagara 생성
→ User Parameter 설정
→ Activate
→ 첫 Simulation Tick

이 순서를 지키면 원점에서 빔이 번쩍이거나 잘못된 방향으로 한 프레임 표시되는 현상을 방지할 수 있다.

BeamStart와 BeamEnd는 단순 Vector가 아니라 Niagara의 Position 타입으로 생성했기 때문에 C++에서도 SetVariableVec3()가 아닌 SetVariablePosition()을 사용했다.

5. 단순 Beam이 레이저처럼 보였던 이유

초기 구현에서는 User.BeamStart와 User.BeamEnd를 Beam Emitter Setup에 직접 연결했다.

Beam Start = User.BeamStart
Beam End   = User.BeamEnd

결과는 총구부터 충돌 지점까지 한 번에 생성되는 긴 직선이었다. 판정 표현에는 문제가 없지만, 총알이 이동하는 것이 아니라 레이저가 순간적으로 나타나는 것처럼 보였다.

해결 방법은 빔의 시작점과 끝점을 시간에 따라 함께 이동시키는 것이었다.

Head = Lerp(Muzzle, HitPoint, t)

Tail = Lerp(
    Muzzle,
    HitPoint,
    Clamp(t - TrailLength, 0, 1)
)

여기서 t는 Emitter.NormalizedLoopAge다.

t = 현재 이미터 시간 / Loop Duration

따라서 t는 이미터 시작 시 0, 종료 시 1이 된다.

빔 앞부분은 현재 시간으로 이동시키고, 뒷부분은 조금 늦은 시간으로 이동시킨다. 그 차이만큼 짧은 빔 조각이 만들어진다.

6. Scratch Dynamic Input으로 위치 보간 구현

동일한 보간 로직을 재사용하기 위해 세 개의 입력을 갖는 Scratch Dynamic Input을 구성했다.

StartPosition : Position
EndPosition   : Position
Alpha         : Float

내부 계산은 단순하다.

Lerp(
    A = StartPosition,
    B = EndPosition,
    Alpha
)

Beam End에는 현재 진행도를 그대로 전달했다.

Alpha = Emitter.NormalizedLoopAge

Beam Start에는 지연값을 적용했다.

Alpha = Clamp(
    Emitter.NormalizedLoopAge - 0.08,
    0,
    1
)

최종 구조는 다음과 같다.

Beam End Alpha
= NormalizedLoopAge

Beam Start Alpha
= Clamp(NormalizedLoopAge - 0.08, 0, 1)

0.08은 시간이 아니라 전체 경로에 대한 비율이다. 값을 키우면 빔이 길어지고, 줄이면 짧아진다.

트러블슈팅

1. User Parameter가 Scratch Pad에서 검색되지 않았다

증상

Scratch Dynamic Input 내부의 Map Get에서 다음 파라미터를 검색했지만 나타나지 않았다.

User.BeamStart
User.BeamEnd
Emitter.NormalizedLoopAge

잘못된 접근

완성되지 않은 Scratch Dynamic Input에서 Active Overview를 열어 시스템 파라미터를 직접 가져오려고 했다.

그 결과 Niagara Editor 내부에서 다음 Ensure가 발생했다.

Encountered '0' parameter map history
when collecting parameters for system parameter panel view mode

원인 분석

Scratch Dynamic Input은 당시 아직 출력까지 연결되지 않은 독립 스크립트였다. 그런데 Active Overview는 완성된 System 또는 Emitter의 Parameter Map History를 요구한다.

로그와 재현 조건을 통해 다음 조합이 Ensure의 직접적인 트리거임을 확인했다.

미완성 Dynamic Input
+ System Parameter Panel View
+ 유효한 Parameter Map History 없음

Visual Studio에 표시된 NiagaraEditor.pdb 포함 안 됨은 원인이 아니었다. 엔진 내부 Ensure 위치의 소스를 표시할 디버그 심볼이 없다는 부가 메시지였다.

해결

Scratch 내부에서 System User Parameter를 직접 찾지 않고, Scratch 자체가 필요한 값을 입력으로 받도록 변경했다.

Scratch Input
├ StartPosition
├ EndPosition
└ Alpha

바깥 Beam Emitter Setup에서 실제 값을 연결했다.

StartPosition → User.BeamStart
EndPosition   → User.BeamEnd
Alpha         → Emitter.NormalizedLoopAge

이렇게 구성하면 Scratch Script가 특정 Niagara System에 강하게 의존하지 않으며 다른 Beam에도 재사용할 수 있다.

2. 입력을 만들었는데 바깥 Stack에 표시되지 않았다

증상

Scratch 그래프에는 StartPosition, EndPosition, Alpha 노드가 존재했지만 Beam Emitter Setup에서는 입력칸이 나타나지 않았다.

Expose Input도 활성화된 상태였다.

원인

입력을 일반 Parameter 노드로 만들었기 때문에 그래프에는 존재했지만 실제 Module Input으로 등록되지 않았다.

Edit Input Hierarchy를 확인했을 때 다음 항목만 표시됐다.

INPUT Default

즉, 새로 만든 세 값은 Stack이 인식하는 입력 계층에 포함되지 않은 상태였다.

해결

일반 Input Parameter 생성 메뉴가 아니라 Parameters 패널의 Module Inputs에서 다시 생성했다.

INPUT StartPosition
INPUT EndPosition
INPUT Alpha

그 후 Map Get으로 값을 꺼내 Lerp에 연결했다.

이 문제를 통해 “그래프에 입력 노드가 존재한다”와 “외부 Stack에서 호출 가능한 Module Input으로 등록됐다”는 서로 다른 상태임을 확인했다.

3. Loop Duration, Lifetime, Trail Length를 하나의 값처럼 조정하면 안 됐다

트레이서를 튜닝하면서 세 값의 역할을 분리해야 했다.

파라미터역할

Loop Duration	총구에서 목표까지 이동하는 시간
Particle Lifetime	파티클이 살아 있는 시간
Alpha 지연값	빔 조각의 길이
Beam Width	트레이서 굵기

초기에는 Lifetime이 Loop Duration보다 길어 목표 지점에 도착한 빔이 잠시 남는 현상이 발생했다.

최종적으로 다음과 같이 기준을 잡았다.

Loop Duration = 0.06~0.08
Lifetime      = Loop Duration와 같거나 약간 길게
Trail Offset  = 0.06~0.10

또한 연사 간격보다 Loop Duration이 길면 여러 트레이서가 동시에 존재한다.

FireRate = 0.1초
Loop Duration = 1.0초

→ 최대 10개의 트레이서가 겹쳐 보일 수 있음

따라서 AK47처럼 연사 간격이 0.1초라면 트레이서 이동 시간은 0.08초 이하로 두는 것이 자연스러웠다.

4. API 버전 차이와 활성화 순서 문제

UE 버전에 따라 SpawnSystemAtLocation() 시그니처가 달라 기존 예제를 그대로 사용할 수 없었다.

현재 프로젝트에서 요구하는 전체 인자를 확인하고 다음 순서로 호출했다.

SpawnSystemAtLocation(
    WorldContext,
    System,
    Location,
    Rotation,
    Scale,
    bAutoDestroy,
    bAutoActivate,
    PoolingMethod,
    bPreCullCheck
);

단순히 컴파일 에러를 맞추는 데서 끝내지 않고 bAutoActivate = false를 의도적으로 사용했다. 파라미터를 넣기 전에 실행되는 첫 프레임을 제거하기 위해서다.

이는 API 오버로드 문제를 해결하면서 Niagara 초기화 순서까지 함께 정리한 사례였다.

7. 현재 발사 흐름

최종 발사 흐름은 다음과 같다.

클라이언트 발사 입력
→ ServerFire RPC
→ 서버 FireTrace
→ 카메라 기준 조준 지점 계산
→ 총구 기준 2차 트레이스
→ 서버 데미지 적용
→ MuzzleLocation, TracerEndLocation Multicast
→ 각 클라이언트가 Niagara 생성
→ User Parameter 설정
→ Niagara 활성화
→ 짧은 Beam Segment가 목표까지 이동

이 구조에서는 다음 책임이 분리된다.

서버: 명중 판정과 데미지
데이터테이블: 무기 수치와 표현 리소스
Niagara: 총알 이동 연출
Multicast RPC: 연출에 필요한 최소 좌표 전달

8. 추가 검증 예정

상하 조준 시 트레이서 방향이 어색하게 보이는 현상이 남아 있다.

코드상 트레이서는 다음 데이터테이블 소켓에서 시작한다.

MeshComponent->GetSocketLocation(
    CurrentWeaponData.MuzzleSocketName
);

다만 현재 코드에는 카메라 트레이스와 총구 트레이스를 2초간 표시하는 DrawDebugLine()이 남아 있다.

DrawDebugLine(..., FColor::Red, false, 2.f);
DrawDebugLine(..., FColor::Yellow, false, 2.f);

위아래로 조준하면 카메라와 총구의 시차 때문에 두 디버그 선이 서로 다른 각도를 형성한다. 연사 시 이 선들이 2초간 누적돼 실제 Niagara 방향 문제처럼 보일 가능성이 있다.

다음 작업에서는 디버그 렌더링을 제거한 뒤 아래 항목을 분리해서 검증할 예정이다.

총구 소켓 위치
카메라–총구 시차
Niagara Local Space 설정
Absolute Beam Start/End
실제 트레이서와 디버그 라인의 시각적 구분

마무리

이번 구현에서 핵심은 “총알을 보이게 만들었다”가 아니다.

기존 Hitscan 구조를 유지하면서 판정과 표현을 분리하고, 네트워크에는 결과 좌표만 전달하며, Niagara에서는 정규화된 시간으로 빔의 앞뒤를 독립적으로 보간했다.

특히 Scratch Dynamic Input 문제를 해결하는 과정에서 다음 차이를 확인할 수 있었다.

일반 Parameter ≠ Module Input
그래프에 존재함 ≠ 외부 Stack에서 호출 가능함
Vector ≠ Niagara Position
Emitter Duration ≠ Particle Lifetime
실제 트레이서 ≠ 디버그 시각화

결과적으로 무기 로직을 대대적으로 수정하지 않고 데이터 기반·네트워크 친화적인 트레이서 시스템을 추가할 수 있었다.