본문으로 건너뛰기

안동민 개발노트

본문 시작

구조체와 열거형의 기본 이해

구조체로 관련 데이터를 하나의 값으로 묶고 열거형으로 유한한 상태를 정의해 변수와 분기 로직을 명확히 만듭니다.

지금까지는 변수, 함수, 이벤트, 흐름 제어, 통신 기법 등 게임의 행동을 정의하는 요소를 학습했습니다.

다음 단계에서는 데이터를 체계적으로 관리하는 방법이 중요해집니다.

이번 장에서는 블루프린트에서 데이터를 구조화하고 분류할 때 사용하는 구조체(Struct)와 열거형(Enum)을 다룹니다.

Struct는 함께 이동하는 속성, Enum은 하나만 고르는 상태다

블루프린트 데이터 설계는 먼저 값의 성격을 나눈다. 여러 속성이 한 덩어리로 이동하면 구조체, 제한된 선택지 중 하나라면 열거형이 그래프를 덜 흔들리게 만든다.

  1. 먼저 요구사항을 값의 모양으로 읽는다

    캐릭터 능력치 이름, 체력, 공격력이 항상 같은 캐릭터 정보로 움직인다. 게임 진행 상태 현재 값은 메뉴, 플레이, 일시정지, 종료 중 하나만 가능하다.

  2. 관련 속성은 하나의 구조체로 묶는다

    F_CharacterStats CharacterName 출력과 저장에서 같은 식별자를 공유 Health 전투, UI, 저장 데이터가 같은 값을 참조 AttackDamage 능력치 묶음 안에서 함께 복사·전달 Make 노드는 필드를 합치고, Break 노드는 필요한 필드만 꺼내 블루프린트 선을 짧게 만든다.

  3. 배타적 선택지는 열거형으로 잠근다

    E_GameState MainMenu 대기 Playing 진행 Paused 정지 GameOver 종료 문자열 대신 명명된 값만 허용하면 오타가 사라지고 분기 의도가 그래프에 직접 남는다.

구조체와 열거형의 기본 이해

게임 데이터는 단순히 개별적인 변수들의 나열이 아닙니다.

캐릭터의 능력치, 아이템의 속성, 퀘스트 정보 등은 서로 연관된 여러 개의 데이터 조각들로 구성됩니다.

구조체와 열거형은 이러한 연관된 데이터를 묶거나, 특정 값을 명확하게 분류하는 데 사용되어 블루프린트의 가독성과 유지보수성을 크게 향상시킵니다.

구조체 (Structure, Struct)

Struct는 함께 움직이는 필드를 하나의 값으로 묶는다

아이템, 스탯, 좌표처럼 한 행으로 읽어야 하는 데이터를 Struct로 만들면 핀과 변수 수가 줄어든다.

  1. F_ItemData

    Name, Icon, Count, Type을 한 값으로 이동

  2. Make Struct

    필드를 채워 하나의 값 생성

  3. Break Struct

    필요한 필드만 꺼내 표시

  4. Array of Struct

    인벤토리 목록처럼 반복 데이터 보관

구분설명
좋은 필드항상 같이 저장되고 같이 전달되는 값
나쁜 필드수명이 다르거나 자주 따로 바뀌는 참조

구조체는 서로 다른 유형의 여러 변수들을 하나의 논리적인 묶음으로 정의할 수 있는 사용자 정의 데이터 타입입니다.

마치 사람을 나타낼 때 이름, 나이, 성별, 키 등 여러 정보를 묶어서 사람 정보라는 하나의 단위로 다루는 것과 같습니다.

구조체가 필요한 이유
  • 데이터의 논리적 그룹화: 관련된 데이터를 하나의 변수처럼 관리할 수 있어 코드가 깔끔해집니다.
  • 가독성 향상: 어떤 데이터가 서로 연관되어 있는지 명확하게 알 수 있습니다.
  • 재사용성: 한 번 정의된 구조체는 여러 블루프린트에서 동일한 형태로 재사용할 수 있습니다.
  • 오류 감소: 각 데이터를 개별적으로 관리할 때 발생할 수 있는 휴먼 에러를 줄일 수 있습니다.
구조체 생성 및 정의

콘텐츠 브라우저에서 마우스 오른쪽 버튼을 클릭합니다.

블루프린트(Blueprints) > 구조체(Structure)를 선택합니다.

이름을 지정합니다. (예: F_CharacterStats - 일반적으로 구조체 이름에는 F 접두사를 사용합니다.)

생성된 구조체 에셋을 더블클릭하여 구조체 에디터를 엽니다.

+ 새 변수(+ New Variable) 버튼을 클릭하여 구조체에 포함될 멤버 변수들을 추가합니다.

각 변수의 이름과 유형을 지정합니다.

  • 예시: Health (Float), AttackDamage (Float), Defense (Float), CharacterName (Text)

저장 버튼을 클릭하여 구조체 정의를 저장합니다.

구조체 활용

이제 정의된 구조체를 일반 변수처럼 사용할 수 있습니다.

블루프린트에서 구조체 변수 생성
  • 액터 블루프린트(예: BP_PlayerCharacter)를 엽니다.
  • 변수 패널에서 새 변수를 추가합니다.
  • 변수 유형을 검색창에 여러분이 만든 구조체 이름(예: F_CharacterStats)을 입력하여 선택합니다.
  • 변수 이름을 MyStats와 같이 지정합니다.
구조체 변수 값 설정 및 가져오기
  • MyStats 변수(Get 노드)를 이벤트 그래프에 가져옵니다.
  • MyStats 출력 핀에서 드래그하여 Break F_CharacterStats 노드를 검색하고 선택합니다. 이 노드는 구조체를 구성하는 개별 멤버 변수들로 분리해줍니다. 이제 각 멤버 변수 값을 개별적으로 가져와 사용할 수 있습니다.
  • Make F_CharacterStats 노드를 사용하여 개별 값을 합쳐 하나의 구조체 변수를 만들 수도 있습니다. 이 노드의 입력 핀에 각 멤버 변수 값을 연결하고, 출력 핀을 Set MyStats 노드의 입력 핀에 연결합니다.
  • 예시: Event BeginPlay에서 MyStats 변수에 Make F_CharacterStats를 연결하여 Health를 100, AttackDamage를 20 등으로 초기화합니다. 이후 Print String 노드에서 Break F_CharacterStats를 통해 CharacterName과 Health를 가져와 출력할 수 있습니다.

열거형 (Enumeration, Enum)

열거형은 명확하게 정의된 여러 개의 명명된 정수 값 목록을 나타내는 사용자 정의 데이터 타입입니다.

제한된 선택지 중에서 하나를 선택해야 할 때 유용하며, 코드의 가독성을 높이고 오타로 인한 오류를 방지하는 데 도움을 줍니다.

마치 요일을 월, 화, 수, 목, 금, 토, 일로 명확하게 정의하는 것과 같습니다.

열거형이 필요한 이유
  • 의미 부여: 정수 값에 의미 있는 이름을 부여하여 코드의 가독성을 높입니다. (예: 0 대신 E_GameState_MainMenu)
  • 오류 방지: 허용되지 않는 값을 할당하는 것을 컴파일 시점에서 방지합니다.
  • 제한된 선택지 표현: 특정 변수가 가질 수 있는 값을 제한할 때 사용합니다.
  • 스위치 노드와의 연동: Switch on Enum 노드와 함께 사용하여 실행 흐름을 명확하게 분기할 수 있습니다.
열거형 생성 및 정의

콘텐츠 브라우저에서 마우스 오른쪽 버튼을 클릭합니다.

블루프린트(Blueprints) > 열거형(Enumeration)을 선택합니다.

이름을 지정합니다. (예: E_GameState - 일반적으로 열거형 이름에는 E_ 접두사를 사용합니다.)

생성된 열거형 에셋을 더블클릭하여 열거형 에디터를 엽니다.

+ 새 이넘 추가(+ New Enum) 버튼을 클릭하여 열거형의 멤버들을 추가합니다.

각 멤버에 의미 있는 이름을 부여합니다.

  • 예시: MainMenu, Playing, Paused, GameOver

저장 버튼을 클릭하여 열거형 정의를 저장합니다.

열거형 활용

정의된 열거형은 상태를 표현하는 변수에 특히 유용합니다.

블루프린트에서 열거형 변수 생성
  • BP_GameManager 블루프린트(또는 다른 적절한 블루프린트)를 엽니다.
  • 변수 패널에서 새 변수를 추가합니다.
  • 변수 유형을 여러분이 만든 열거형 이름(예: E_GameState)을 입력하여 선택합니다.
  • 변수 이름을 CurrentGameState와 같이 지정합니다.
  • 디테일 패널에서 기본값을 설정할 수 있습니다. (예: MainMenu)
열거형 값 설정 및 스위치 노드 활용
  • Event BeginPlay에서 Set CurrentGameState 노드를 사용하여 게임 상태를 MainMenu로 설정합니다.
  • Get CurrentGameState 변수 노드를 이벤트 그래프에 가져옵니다.
  • CurrentGameState 출력 핀에서 드래그하여 Switch on E_GameState 노드를 검색하고 선택합니다. 이 노드는 열거형 변수의 현재 값에 따라 다른 실행 핀을 활성화합니다.
  • 각 열거형 멤버(MainMenu, Playing 등)에 해당하는 실행 핀 뒤에 해당 상태일 때 수행될 로직을 연결합니다.
  • 예시: MainMenu 핀에는 메인 메뉴 화면 출력 로직을, Playing 핀에는 게임 플레이 시작 로직을 연결할 수 있습니다.

구조체와 열거형은 블루프린트 로직의 복잡성을 줄이고, 데이터를 보다 체계적으로 관리하여 개발 효율성을 높이는 데 필수적인 도구입니다.

특히 복잡한 게임 시스템을 설계할 때 이들을 적절히 활용하면, 블루프린트 그래프가 훨씬 간결해지고 유지보수가 용이해질 것입니다.

아래 다이어그램은 열거형을 현재 상태 변수와 Switch on Enum 분기 노드로 연결해 게임 흐름을 안전하게 나누는 방식을 정리한 것입니다.

Enum은 가능한 상태를 이름 붙이고 Switch로 분기한다

문자열이나 숫자로 상태를 비교하지 않고, 허용된 이름만 고르게 만들어 분기 실수를 줄인다.

  1. MainMenu

    메뉴 UI 표시

  2. Playing

    입력과 전투 허용

  3. Paused

    시간 정지와 메뉴

  4. GameOver

    결과 화면 전환

검수의미
Enum 장점오타가 줄고 가능한 상태 목록이 한눈에 보인다.
Switch 기준모든 상태의 처리 경로와 기본 경로를 확인한다.

마지막으로 구조체와 열거형을 함께 사용할 때 데이터와 상태 책임을 어떻게 나누는지 정리해 보겠습니다.

구조체는 묶고, 열거형은 고른다

서로 관련된 값은 구조체로 관리하고, 제한된 상태나 종류는 열거형으로 표현하면 그래프가 읽기 쉬워집니다.

  1. Struct

    bundle Health, MaxHealth처럼 함께 움직이는 숫자 Name, Weight, Mesh를 하나의 행처럼 취급

  2. 체력

    Health, MaxHealth처럼 함께 움직이는 숫자

  3. 아이템

    Name, Weight, Mesh를 하나의 행처럼 취급

  4. Enum

    선택 MainMenu, Playing, Paused처럼 하나만 선택 Switch on Enum으로 실행 흐름을 명확히 분리

  5. 상태

    MainMenu, Playing, Paused처럼 하나만 선택

  6. 분기

    Switch on Enum으로 실행 흐름을 명확히 분리

실습에서는 구조체와 열거형을 따로 외우기보다, 아래처럼 데이터 묶음과 선택지를 먼저 나누어 설계하면 좋습니다.

데이터 묶음과 선택지를 먼저 나눈다

구조체는 함께 움직이는 값을 한 덩어리로 만들고, 열거형은 허용되는 상태 목록을 고정합니다.

  1. Struct로 묶을 값

    F_CharacterStats Health 현재 체력과 최대 체력 Attack 공격력, 방어력, 이동 속도 Name 표시 이름과 설명 텍스트

  2. Enum으로 고를 값

    E_GameState MainMenu 메뉴 화면에서 대기 Playing 플레이 입력과 규칙 실행 Paused 입력 제한과 UI 표시

  3. 함께 쓰는 형태

    Together ItemData 이름, 무게, 메시를 구조체로 관리 ItemType Weapon, Armor, Potion을 열거형으로 제한 Switch 타입에 따라 장착, 사용, 버리기 로직 분기

이번 절에서는 블루프린트에서 데이터를 체계적으로 관리하는 데 사용되는 구조체와 열거형의 기본 개념과 활용법에 대해 알아보았습니다.

이들은 단순한 변수들의 나열을 넘어, 데이터에 의미와 구조를 부여하는 중요한 역할을 합니다.

구조체는 묶고 열거형은 고릅니다

아이템, 능력치, 퀘스트처럼 관련 값은 구조체로 묶고, 상태나 종류처럼 제한된 선택지는 열거형으로 분류합니다.

  1. Group vs Choice

    Data Shape Struct는 여러 필드를 하나의 데이터 단위로, Enum은 가능한 값 목록을 명확한 이름으로 만듭니다. Struct Health, Attack, Defense처럼 함께 움직이는 값을 하나의 타입으로 관리합니다. Break Break Struct로 필요한 멤버만 읽고 UI나 계산 로직에 연결합니다. Enum Idle, Attack, Dead처럼 가능한 상태를 정해 분기 실수를 줄입니다. Switch Switch on Enum으로 상태마다 다른 로직을 깔끔하게 나눕니다.

  2. Group vs Choice

    Data Shape Struct는 여러 필드를 하나의 데이터 단위로, Enum은 가능한 값 목록을 명확한 이름으로 만듭니다.

  3. 관련 변수 묶기

    Struct Health, Attack, Defense처럼 함께 움직이는 값을 하나의 타입으로 관리합니다.

  4. 필드별로 꺼내기

    Break Break Struct로 필요한 멤버만 읽고 UI나 계산 로직에 연결합니다.

  5. 상태 이름 제한

    Enum Idle, Attack, Dead처럼 가능한 상태를 정해 분기 실수를 줄입니다.

  6. 상태별 실행

    Switch Switch on Enum으로 상태마다 다른 로직을 깔끔하게 나눕니다.

구조체와 열거형을 실제 데이터 모델로 선택하는 기준을 추가합니다.

Struct는 데이터 묶음, Enum은 선택지를 담당한다

Struct 안에 Enum 필드를 두면 한 항목의 값과 상태를 같은 모델 안에서 관리할 수 있다.

  1. Struct가 담당

    필드 묶음 Name, Damage, Icon, Type 전달 단위 함수 입력, DataTable Row, SaveGame 값 배열 요소 인벤토리, 퀘스트 목록

  2. Enum이 담당

    상태 이름 Weapon, Potion, QuestItem 분기 기준 Switch on ItemType 허용 목록 문자열 오타를 제거

검수의미
모델링 순서먼저 필드를 묶고, 반복되는 분기 값만 Enum으로 뺀다.
검수Struct는 “무엇을 담는가”, Enum은 “어느 경우인가”로 읽혀야 한다.

구조체와 열거형은 데이터를 묶는 도구와 상태를 제한하는 도구이므로, 새 데이터를 만들 때 먼저 성격을 구분합니다.

Struct와 Enum은 한 행의 값과 분기 기준을 함께 만든다

Data Table, SaveGame, UI 표시에서 같은 구조를 쓰면 데이터 전달과 상태 분기가 일관된다.

  1. F_ItemData

    Name, Icon, Count, ItemType(Enum)

  2. Data Table Row

    한 아이템의 기본값

  3. Inventory Array

    F_ItemData[]로 보관

  4. Switch on Type

    무기, 소비품, 퀘스트 아이템 분기

구분설명
핵심Struct가 값을 담고 Enum이 처리 경로를 고른다.
위험타입을 문자열로 저장하면 오타와 누락 분기가 생긴다.

레벨 블루프린트와의 상호작용

이전 페이지

데이터 테이블과 블루프린트 연동

다음 페이지

이 페이지의 목차

구조체와 열거형의 기본 이해구조체 (Structure, Struct)열거형 (Enumeration, Enum)