본문으로 건너뛰기

안동민 개발노트

본문 시작

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

구조체 기반 데이터 테이블을 만들고 행 조회·반복 노드로 아이템 같은 정형 데이터를 블루프린트에 연결합니다.

게임 개발 시 플레이어의 능력치, 아이템 정보, 퀘스트 내용, 몬스터 스탯 등 수많은 데이터를 관리해야 합니다.

이런 데이터를 하드코딩(블루프린트나 코드 내에 직접 값 입력)하거나 일일이 변수로 만드는 것은 비효율적이며, 데이터 변경 시마다 블루프린트를 수정하고 재컴파일해야 하는 번거로움이 있습니다.

또한, 기획자가 직접 데이터를 수정하기 어렵다는 문제도 있습니다.

이러한 문제들을 해결하기 위해 언리얼 엔진은 데이터 테이블(Data Table)이라는 강력한 기능을 제공합니다.

데이터 테이블은 스프레드시트(Excel, Google Sheets 등)와 유사한 형태로 데이터를 중앙 집중식으로 관리하고, 블루프린트에서 쉽게 접근하여 활용할 수 있게 해줍니다.

Data Table 구조체 행

아이템, 몬스터, 퀘스트 값을 블루프린트 안에 직접 넣으면 수정 비용이 커집니다. 구조체와 데이터 테이블을 쓰면 데이터와 로직을 분리할 수 있습니다.

  1. 중앙 관리

    여러 블루프린트에 흩어진 값을 하나의 테이블에서 관리해 수정 범위를 줄입니다.

  2. 기획자 친화

    행과 열 형태라 스프레드시트처럼 값을 확인하고 조정하기 쉽습니다.

  3. Found Row

    행을 찾았을 때 구조체 데이터가 나오며, 필요한 필드를 분해해 사용할 수 있습니다.

  4. Not Found

    Row Name 오타나 누락에 대비해 실패 분기에서 기본값이나 오류 처리를 둡니다.

데이터 테이블이란 무엇인가?

데이터 테이블은 게임 데이터를 행(Row)과 열(Column)의 형태로 정리하여 저장하는 언리얼 엔진의 에셋입니다.

각 행(Row)은 하나의 데이터 항목(예: 특정 아이템)을 나타내고, 각 열(Column)은 그 항목의 특정 속성(예: 아이템 이름, 공격력, 무게)을 나타냅니다.

데이터 테이블의 가장 큰 장점은 다음과 같습니다.

  • 중앙 집중식 관리: 모든 관련 데이터를 한곳에 모아 관리할 수 있습니다.
  • 쉬운 편집: 테이블 형태로 되어 있어 기획자나 디자이너가 블루프린트나 코드를 수정하지 않고도 데이터를 쉽게 추가, 수정, 삭제할 수 있습니다.
  • 블루프린트 연동: 블루프린트에서 특정 행의 데이터를 쉽게 검색하고 가져와 사용할 수 있습니다.
  • 확장성: 새로운 데이터 항목이나 속성을 추가하기 용이합니다.

데이터 테이블을 사용하려면, 먼저 해당 데이터의 구조를 정의하는 구조체(Struct)가 필요합니다.

1절에서 다루었던 구조체가 바로 데이터 테이블의 각 행이 가질 데이터 타입을 정의하는 역할을 합니다.

데이터 테이블 생성 및 설정

데이터 테이블을 생성하고 블루프린트와 연동하는 단계는 다음과 같습니다.

데이터 구조체 정의 (1절 복습)

  • 먼저 데이터 테이블에 들어갈 데이터의 형식을 정의하는 구조체를 생성합니다.
  • 콘텐츠 브라우저에서 우클릭 > 블루프린트(Blueprints) > 구조체(Structure)를 선택합니다.
  • 이름을 F_ItemData (예시: 아이템 정보를 저장할 구조체)로 지정합니다.
  • 구조체 에디터를 열고 아이템이 가질 속성들을 변수로 추가합니다.
    • ItemName (Text)
    • Description (Text)
    • AttackPower (Integer)
    • Weight (Float)
    • ItemMesh (Static Mesh Reference)
  • 저장 버튼을 클릭합니다.
데이터 테이블 생성
  • 콘텐츠 브라우저에서 우클릭 > 기타(Miscellaneous) > 데이터 테이블(Data Table)을 선택합니다.
  • 팝업되는 창에서 Row Structure를 여러분이 방금 만든 구조체(F_ItemData)로 선택합니다.
  • 이름을 DT_Items와 같이 지정합니다. (일반적으로 DT_ 접두사를 사용합니다.)
  • 저장 버튼을 클릭합니다.
데이터 테이블에 데이터 입력
  • 생성된 DT_Items 데이터 테이블 에셋을 더블클릭하여 데이터 테이블 에디터를 엽니다.
  • + 추가(+ Add) 버튼을 클릭하여 새 행을 추가합니다.
  • 각 행의 Row Name을 고유하게 지정합니다. 이 이름이 나중에 블루프린트에서 데이터를 검색할 때 사용될 키(Key)가 됩니다. (예: Sword_Basic, Shield_Wooden, Potion_Health)
  • 각 열(구조체 멤버)에 맞는 데이터를 입력합니다.
    • Sword_Basic
      • ItemName: 기본 검
      • Description: 평범한 검입니다.
      • AttackPower: 10
      • Weight: 2.5
      • ItemMesh: Shape_Cylinder (예시)
    • Potion_Health
      • ItemName: 체력 회복 물약
      • Description: 체력을 회복시켜줍니다.
      • AttackPower: 0
      • Weight: 0.1
      • ItemMesh: Shape_Sphere (예시)
  • 모든 데이터 입력 후 저장 버튼을 클릭합니다.

블루프린트에서 데이터 테이블 연동 및 활용

Data Table Row 조회 파이프라인

데이터 테이블은 구조체가 행 모양을 정하고 Row Name이 조회 키가 됩니다. 성공과 실패 분기를 함께 설계해야 블루프린트가 안전하게 데이터를 소비합니다.

  1. 1
    행 구조 고정

    구조체 멤버가 테이블 열이 되므로 타입을 먼저 정합니다.

  2. 2
    테이블 작성

    행 이름을 중복 없이 만들고 기획 데이터와 맞춥니다.

  3. 3
    Row 조회

    Get Data Table Row에서 테이블과 Row Name을 연결합니다.

  4. 4
    실패 분기

    Not Found에서 기본값이나 오류 로그로 흐름을 닫습니다.

  5. 5
    값 적용

    Out Row를 UI, 스탯, 아이템 생성 로직에 전달합니다.

실제로 블루프린트에서 데이터를 꺼낼 때는 구조체로 정의된 행 형식, 데이터 테이블 에셋, Row Name, 그리고 Get Data Table Row의 성공/실패 분기를 순서대로 이해하면 연결이 훨씬 명확해집니다.

Row Structure에서 게임 적용까지

데이터 테이블 조회는 구조체로 형식을 고정하고, Row Name으로 한 행을 찾아 Found 또는 Not Found 흐름으로 나누는 과정이다.

  1. 1
    Row Structure

    행이 가질 변수와 타입을 구조체로 정의한다.

  2. 2
    Data Table

    같은 구조체를 선택해 여러 행의 데이터를 저장한다.

  3. 3
    Row Name

    Sword_Basic처럼 고유한 이름으로 원하는 행을 지정한다.

  4. 4
    Get Data Table Row

    테이블과 행 이름을 넣어 구조체 데이터를 요청한다.

  5. 5
    Game Apply

    찾은 값을 UI, 스탯, 아이템 생성 로직에 반영한다.

  6. Found Row
    성공하면 구조체를 분해한다

    Found Row Out Row를 Break 노드로 풀어 ItemName, AttackPower 같은 필드를 실제 게임 값으로 연결한다.

  7. Not Found
    실패하면 기본 처리로 보낸다

    Not Found Row Name 오타나 누락에 대비해 기본 아이템, 경고 출력, 스폰 취소 같은 실패 흐름을 둔다.

데이터 테이블에 데이터가 준비되었다면, 이제 블루프린트에서 이 데이터를 가져와 사용할 수 있습니다.

블루프린트 열기: 데이터를 활용할 액터 블루프린트(예: BP_PlayerCharacter)를 엽니다.

Get Data Table Row 노드 사용
  • 이벤트 그래프의 빈 공간에서 마우스 오른쪽 버튼을 클릭합니다.
  • Get Data Table Row를 검색하여 노드를 추가합니다.
  • Data Table 핀에 여러분이 만든 DT_Items 데이터 테이블 에셋을 지정합니다. (드롭다운에서 선택)
  • Row Name 핀에 가져오고 싶은 데이터의 행 이름을 Text 형태로 입력합니다. (예: "Sword_Basic") 또는 Make Literal Text 노드를 연결하여 텍스트를 입력합니다.
  • Get Data Table Row 노드에는 두 개의 실행 출력 핀이 있습니다.
    • Found Row: 지정된 Row Name의 데이터를 성공적으로 찾았을 때 실행됩니다.
    • Not Found: 지정된 Row Name의 데이터를 찾지 못했을 때 실행됩니다. (오타나 존재하지 않는 이름 입력 시)
  • Row Name 입력 핀은 텍스트(Text) 타입이므로, 만약 String 타입의 변수나 입력이 있다면 ToString이나 ToText 컨버터 노드를 사용해야 합니다.
가져온 데이터 사용
  • Get Data Table Row 노드의 Out Row 출력 핀은 여러분이 지정한 F_ItemData 구조체 타입의 데이터를 반환합니다.
  • 이 Out Row 핀에서 드래그하여 Break F_ItemData 노드를 검색하고 선택합니다.
  • 이제 F_ItemData 구조체 내의 개별 멤버 변수들(ItemName, AttackPower 등)에 접근하여 사용할 수 있습니다.
  • 예시: Found Row 실행 핀 뒤에 Print String 노드를 연결하고, Break F_ItemData에서 ItemName을 가져와 Print String의 In String 핀에 연결합니다. 또한, AttackPower를 가져와 플레이어 캐릭터의 공격력 변수에 Set할 수 있습니다.
활용 시나리오
  • 아이템 생성: 게임 시작 시 DT_Items에서 Row Name을 통해 특정 아이템 데이터를 가져와 해당 아이템 액터의 속성을 설정할 수 있습니다.
  • NPC 대화: DT_Dialogue와 같은 데이터 테이블에 NPC의 대화 내용을 저장하고, 퀘스트 진행 상황에 따라 해당 대화 데이터를 가져와 출력합니다.
  • 레벨 디자인: 특정 오브젝트의 배치나 속성을 데이터 테이블에 저장하여, 디자이너가 블루프린트 수정 없이 레벨의 다양한 요소를 조정할 수 있게 합니다.

데이터 테이블은 게임 데이터를 효율적으로 관리하고, 기획자와 프로그래머 간의 협업을 원활하게 하며, 게임의 확장성과 유지보수성을 크게 높여주는 매우 중요한 기능입니다.

데이터가 늘어날수록 Row 구조와 참조 규칙을 명확히 정해야 합니다.

아래 다이어그램은 데이터 테이블을 수정 가능한 원본 데이터로 두고 블루프린트가 안전하게 소비하는 흐름을 요약한 것입니다.

원본 데이터와 소비 로직 분리

데이터 테이블은 행 단위 원본을 보관하고, 블루프린트는 Row Name으로 필요한 행을 찾아 성공 여부에 따라 처리합니다.

  1. Struct

    행이 가질 열과 타입을 먼저 정의합니다.

  2. Data Table

    구조체를 기준으로 행 데이터를 입력합니다.

  3. Row Name

    져올 행을 키 이름으로 지정합니다.

  4. Out Row

    찾은 구조체 데이터를 Break해서 사용합니다.

  5. Found Row

    아이템 이름, 공격력, 메시 같은 값을 적용합니다.

  6. Not Found

    오타나 누락을 로그로 남기고 기본값을 사용합니다.

데이터 테이블을 안정적으로 쓰려면 행 이름을 블루프린트와 데이터 사이의 약속으로 관리해야 합니다.

행 이름: 데이터와 그래프 사이의 약속

데이터 테이블 조회는 Row Name이 맞아야 성공하므로, 키 이름을 임시 문자열이 아니라 관리 대상 값으로 다룹니다.

  1. 원본 데이터

    DT_Items Sword_Basic 기본 검의 이름, 공격력, 메시 Potion_Health 회복 물약의 설명과 효과량

  2. 블루프린트 조회

    Get Row Row Name 변수 인벤토리 슬롯이나 상호작용 결과에서 키를 전달합니다. Out Row 찾은 행은 F_ItemData 구조체로 받아 Break합니다.

  3. 실패 대응

    Branch Found Row 아이템 이름, 공격력, 메시를 액터에 적용합니다. Not Found 오타를 로그로 남기고 기본 아이템이나 빈 슬롯을 사용합니다.

이번 절에서는 데이터 테이블의 개념, 생성 및 설정 방법, 그리고 블루프린트에서 데이터를 연동하고 활용하는 방법에 대해 자세히 알아보았습니다.

데이터 테이블은 대규모 게임 프로젝트에서 필수적인 데이터 관리 도구입니다.

마지막으로 데이터 테이블 조회를 안전하게 배치하기 위한 행 이름 계약과 실패 분기 기준을 정리합니다.

Data Table 행 조회 안전 루틴

DT_Items를 블루프린트에서 읽을 때 Row Structure, Row Name, 실패 분기를 하나의 계약으로 다룹니다.

  1. Row Name은 데이터와 그래프의 키

    행 이름은 문자열 장식이 아니라 DT_Items와 BP_PlayerCharacter 사이의 약속입니다. 오타와 누락은 Not Found에서 처리합니다. 01 Data Table을 만들기 전에 F_ItemData의 Text, Integer, Static Mesh Reference 같은 열 타입을 먼저 확정합니다. 02 Get Data Table Row의 Found Row 뒤에서 Break F_ItemData를 사용하고, Not Found에는 기본 아이템이나 경고 로그를 둡니다. 03 아이템 생성, UI 표시, 능력치 적용 중 어디에서 Out Row를 쓰는지 정해 같은 Row Name 조회를 반복하지 않습니다.

  2. Row Name은 데이터와 그래프의 키

    행 이름은 문자열 장식이 아니라 DT_Items와 BP_PlayerCharacter 사이의 약속입니다. 오타와 누락은 Not Found에서 처리합니다.

  3. 구조체 고정

    Data Table을 만들기 전에 F_ItemData의 Text, Integer, Static Mesh Reference 같은 열 타입을 먼저 확정합니다.

  4. 조회 분기

    Get Data Table Row의 Found Row 뒤에서 Break F_ItemData를 사용하고, Not Found에는 기본 아이템이나 경고 로그를 둡니다.

  5. 소비 위치

    아이템 생성, UI 표시, 능력치 적용 중 어디에서 Out Row를 쓰는지 정해 같은 Row Name 조회를 반복하지 않습니다.

데이터 테이블과 블루프린트 연동을 검수하는 기준을 추가합니다.

Data Table은 Row Struct와 Row Name이 맞아야 읽힌다

테이블이 보이더라도 구조체 타입과 행 이름이 틀리면 Get Data Table Row 결과가 비어 있다.

  1. Row Struct

    F_ItemData 필드 정의

  2. Data Table Asset

    같은 Struct로 테이블 생성

  3. Row Name

    Item_Sword 같은 행 키 선택

  4. Get Row

    Found 여부 확인

  5. Break Struct

    아이콘, 수량, 설명으로 사용

점검기준
먼저 볼 것Data Table의 Row Struct가 기대한 구조체인지 확인한다.
실패 신호Row Name 오타, 빈 행, Struct 변경 후 테이블 미갱신

데이터 테이블은 구조체로 행 모양을 고정하고 Row Name으로 조회하므로, 테이블 생성 전 데이터 형태와 키 이름을 먼저 정리합니다.

Data Table Row 읽기는 키 확인과 실패 경로를 포함한다

Row Name을 넣고 바로 쓰지 말고, 행 발견 여부를 Branch로 나누어 기본값이나 오류 메시지를 둔다.

  1. Row Name 입력

    UI 선택, 드롭다운, 저장 값

  2. Get Data Table Row

    테이블과 키로 행 조회

  3. Row Found?

    성공/실패 분기

  4. Break Row Struct

    필드별 값 추출

  5. Apply

    UI, 스폰, 인벤토리에 반영

점검기준
좋은 경로행이 없을 때도 안전한 기본값 또는 로그를 남긴다.
검수키, 테이블, 구조체 타입이 한 화면에서 대응되어야 한다.

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

이전 페이지

저장 및 로드 기본 구현

다음 페이지

이 페이지의 목차

데이터 테이블이란 무엇인가?데이터 테이블 생성 및 설정블루프린트에서 데이터 테이블 연동 및 활용