1-2. 변수와 데이터타입 | UE5 블루프린트 마스터

01

기본 데이터 타입

블루프린트에서 사용하는 핵심 데이터 타입

블루프린트의 변수는 My Blueprint 패널에서 Variables 섹션의 + 버튼으로 생성합니다. 각 변수는 고유한 핀 색상으로 구분됩니다.

타입	핀 색상	C++ 대응	값 범위 / 설명
Boolean	빨강	bool	True / False
Byte	짙은 녹색	uint8	0 ~ 255
Integer	청록	int32	-2,147,483,648 ~ 2,147,483,647
Integer64	청록 (밝은)	int64	64비트 정수 (UE 5.0+)
Float	밝은 녹색	float (UE5: double)	부동소수점. UE5에서 내부적으로 double 정밀도 사용
Name	연보라	FName	대소문자 무시 비교, 빠른 검색용
String	분홍	FString	일반 문자열, 가변 길이
Text	분홍 (밝은)	FText	지역화(Localization) 지원 문자열, UI 표시용

UE5의 Float 변경사항

UE5부터 블루프린트의 Float 타입은 내부적으로 double(64비트)을 사용합니다. 이전 UE4에서는 float(32비트)였습니다. 이 변경으로 대규모 월드에서의 정밀도 문제가 해결되었으며, Large World Coordinates (LWC) 시스템의 기반이 됩니다.

문자열 타입 비교: FName vs FString vs FText

FName

용도: 에셋 이름, 테이블 키, 빠른 비교
특징: 대소문자 무시, 해시 테이블 기반으로 비교가 매우 빠름. 변경 불가(immutable).

FString

용도: 일반 문자열 조작, 로그 출력
특징: 검색, 수정, 연결 등 모든 문자열 연산 가능. 가장 유연하지만 메모리 비용이 큼.

FText

용도: UI 표시 텍스트, 현지화
특징: 지역화(L10N) 지원. UI에 표시할 텍스트는 반드시 FText를 사용.

02

구조체(Struct)와 열거형(Enum)

복합 데이터 타입으로 정보를 체계적으로 관리합니다

내장 구조체

UE5에는 게임 개발에 자주 사용되는 구조체가 내장되어 있습니다.

구조체	핀 색상	구성	용도
Vector	노랑	X, Y, Z (double)	위치, 방향, 크기
Rotator	연보라	Pitch, Yaw, Roll (double)	회전값
Transform	주황	Location + Rotation + Scale	위치+회전+크기 통합
Color (LinearColor)	노랑	R, G, B, A (float)	색상값
Vector2D	녹색	X, Y (double)	2D 좌표, UV

사용자 정의 구조체 생성

콘텐츠 브라우저에서 우클릭 > Blueprints > Structure로 생성합니다.

                    Custom Struct Example
                    // S_ItemData 구조체 예시
Structure: S_ItemData
  ├─ Name        : FName         // 아이템 식별자
  ├─ DisplayName : FText         // 화면 표시 이름
  ├─ Icon        : Texture2D    // 아이콘 텍스처
  ├─ MaxStack    : Integer       // 최대 스택 수
  ├─ Weight      : Float         // 무게
  └─ bIsConsumable: Boolean      // 소비 아이템 여부
                

열거형(Enum) 생성

콘텐츠 브라우저에서 우클릭 > Blueprints > Enumeration으로 생성합니다.

                    Custom Enum Example
                    // E_ItemRarity 열거형 예시
Enumeration: E_ItemRarity
  ├─ [0] Common     // 일반
  ├─ [1] Uncommon   // 고급
  ├─ [2] Rare       // 희귀
  ├─ [3] Epic       // 영웅
  └─ [4] Legendary  // 전설

// Switch on E_ItemRarity 노드로 분기 처리 가능
                

구조체 분해(Break) 및 생성(Make)

구조체 핀을 드래그하면 Break [구조체명] 노드를 생성하여 개별 멤버에 접근할 수 있습니다. 반대로 Make [구조체명] 노드로 개별 값에서 구조체를 만들 수 있습니다. 핀에서 우클릭 후 Split Struct Pin을 선택하면 인라인으로 분해할 수도 있습니다.

03

컨테이너 타입

Array, Set, Map을 활용한 데이터 컬렉션 관리

Array (배열)

동일 타입의 값을 순서대로 저장하는 가장 기본적인 컬렉션입니다. 변수 생성 후 Details 패널에서 타입 옆의 아이콘을 클릭하여 배열로 전환합니다.

                    Array Operations
                    // 주요 Array 노드
Add           : 배열 끝에 요소 추가
Insert        : 특정 인덱스에 삽입
Remove Index  : 인덱스로 제거
Remove Item   : 값으로 제거 (첫 번째 일치 항목)
Find          : 값의 인덱스 반환 (-1이면 없음)
Contains      : 값 존재 여부 (Boolean)
Length        : 배열 크기
Get (a copy)   : 인덱스로 값 복사본 가져오기
Get (a ref)    : 인덱스로 참조 가져오기 (수정 가능)
Sort          : 정렬 (Predicate 노드 필요)
Shuffle       : 무작위 섞기
IsEmpty       : 비었는지 확인
                

Set (집합)

중복 없는 고유 값의 컬렉션입니다. 순서가 보장되지 않으며, 포함 여부 검사가 Array보다 빠릅니다.

                    Set Operations
                    // 주요 Set 노드
Add            : 값 추가 (이미 존재하면 무시)
Remove         : 값 제거
Contains       : 포함 여부 확인
Length         : 집합 크기
To Array       : Array로 변환
Union          : 합집합
Intersection   : 교집합
Difference     : 차집합
                

Map (맵 / 딕셔너리)

키-값 쌍으로 데이터를 저장합니다. 키는 고유해야 합니다. 인벤토리(아이템ID -> 수량), 설정(키 -> 값) 등에 활용됩니다.

                    Map Operations
                    // 주요 Map 노드
Add        : 키-값 쌍 추가 (키 존재 시 덮어쓰기)
Remove     : 키로 항목 제거
Find       : 키로 값 검색 (Boolean 반환: 성공 여부)
Contains   : 키 존재 확인
Keys       : 모든 키를 Array로 반환
Values     : 모든 값을 Array로 반환
Length     : 맵 크기

// 사용 예: 인벤토리 시스템
Map<FName, Integer> Inventory
  Key: "Sword"   -> Value: 1
  Key: "Potion"  -> Value: 5
  Key: "Arrow"   -> Value: 99
                

컨테이너 선택 가이드

Array: 순서가 중요하거나 인덱스 접근이 필요할 때 (인벤토리 슬롯, 순차 실행)
Set: 중복 없이 고유 값만 관리할 때 (태그, 방문한 레벨 목록)
Map: 키로 빠르게 값을 찾아야 할 때 (ID->데이터 매핑, 설정 저장)

04

변수 속성과 관리

변수의 접근 제어, 기본값, 복제 설정을 학습합니다

변수 접근 제어

변수를 선택하고 Details 패널에서 접근 제어를 설정합니다.

속성	위치	설명
Instance Editable	Details > 눈 아이콘	인스턴스별로 다른 값 설정 가능 (Level에서 편집 가능)
Blueprint Read Only	Details 패널	블루프린트 그래프에서 Set 불가 (Get만 가능)
Private	Details 패널	자식 블루프린트에서 접근 불가
Expose on Spawn	Details 패널	SpawnActor 노드에서 핀으로 노출
Category	Details 패널	변수를 카테고리별로 그룹화 (파이프로 하위 카테고리: "Stats\|Health")

기본값 설정

변수의 기본값은 반드시 컴파일 후에 설정할 수 있습니다. 블루프린트를 F7로 컴파일한 뒤, 클래스 디폴트(Class Defaults)에서 설정합니다.

                    Variable Defaults
                    // 변수 기본값 설정 순서
1. My Blueprint 패널에서 변수 생성
2. Details 패널에서 타입 지정
3. Compile (F7) 클릭
4. Details 패널의 Default Value 섹션에서 값 입력

// 또는 Construction Script에서 동적으로 설정
[Construction Script] ──> [Set Health] (Value: 100.0)
                

변수 Get & Set

변수를 그래프에 드래그하면 Get(읽기)과 Set(쓰기) 중 선택할 수 있습니다. 단축키: Ctrl + 드래그 = Get, Alt + 드래그 = Set.

로컬 변수

함수 내부에서만 사용되는 변수입니다. 함수를 열고 My Blueprint > Local Variables에서 추가합니다. 함수가 끝나면 로컬 변수는 소멸됩니다. 이벤트 그래프에서는 로컬 변수를 사용할 수 없습니다.

Promote to Variable

아무 데이터 핀을 우클릭하고 Promote to Variable을 선택하면, 해당 타입의 새 변수가 자동 생성되고 Set 노드가 연결됩니다. 함수 안에서는 Promote to Local Variable도 선택할 수 있습니다. 자주 사용되는 중간 계산 결과를 저장할 때 유용합니다.

SUMMARY

핵심 요약

기본 타입: Boolean, Byte, Integer, Integer64, Float(UE5에서 double), Name, String, Text 8가지가 있다
FName은 빠른 비교용, FString은 일반 문자열 조작, FText는 UI 표시/지역화에 사용한다
UE5에서 Float은 내부적으로 double 정밀도를 사용하여 Large World Coordinates를 지원한다
구조체(Struct)로 관련 데이터를 묶고, 열거형(Enum)으로 상태값을 정의한다
Array(순서 있는 목록), Set(고유 값 집합), Map(키-값 쌍) 3가지 컨테이너를 지원한다
Instance Editable, Expose on Spawn 등의 속성으로 변수의 접근 범위와 편집 가능성을 제어한다

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: 캐릭터 스탯 변수 시스템 구축

Actor Blueprint에 Integer(HP, MP), Float(MoveSpeed), Boolean(IsAlive), String(CharacterName), Vector(SpawnLocation) 변수를 각각 생성하세요. 각 변수에 기본값을 설정하고, BeginPlay에서 Print String으로 모든 값을 출력해보세요.

실습 2: 컨테이너 타입 활용

Array(String 배열)로 인벤토리 아이템 목록을 만들고, ForEachLoop로 모든 아이템 이름을 출력하세요. Map(String → Integer)으로 아이템-수량 매핑을 구현하고, Find 노드로 특정 아이템의 수량을 조회해보세요.

심화 과제

구조체(Struct)로 FCharacterStat(Name, HP, Attack, Defense)을 정의하고, 이 구조체 배열을 사용하여 파티 멤버 시스템을 구현하세요. Break Struct와 Make Struct 노드를 활용하여 데이터를 조작해보세요.