내일배움캠프 54일차 TIL 2026/07/08

[TIL] Unreal Engine: 데이터 테이블(Data Table) 활용하기

1. 데이터 테이블(Data Table)이란?

언리얼 엔진에서 엑셀(Excel)이나 CSV, JSON 형태의 외부 데이터 시트를 가져와 게임 내에서 쉽게 구조화하고 관리할 수 있도록 지원하는 기능입니다.

게임 내 아이템 능력치, 몬스터 스탯, 퀘스트 목록, 대사 텍스트 등 대량의 고정 데이터(정적 데이터)를 관리할 때 필수적으로 사용됩니다.

2. 왜 사용하는가? (장점)

• 데이터와 로직의 분리: 기획자나 밸런서가 소스 코드나 블루프린트를 수정하지 않고도 외부 시트(Excel 등)만 편집해 게임 데이터를 쉽게 변경할 수 있습니다.
• 효율적인 데이터 관리: 수백 개의 아이템을 개별 블루프린트 에셋으로 만드는 대신, 하나의 데이터 테이블과 하나의 마스터 블루프린트만으로 깔끔하게 처리할 수 있습니다.
• 직관적인 유지보수: 테이블 형태로 데이터를 한눈에 파악하기 좋습니다.

3. 핵심 구현 프로세스

데이터 테이블을 생성하고 게임에 적용하는 전체적인 흐름은 다음과 같습니다.

단계 1: 데이터 구조체(FTableRowBase) 정의

데이터 테이블의 '열(Column)'이 될 항목들을 먼저 정의해야 합니다. 언리얼 엔진은 이 구조체를 기반으로 테이블을 생성합니다.

• C++로 구현 시: FTableRowBase를 상속받아 구조체를 선언해야 합니다.
• C++

   

  #include "CoreMinimal.h"
  #include "Engine/DataTable.h"
  #include "FMyItemData.generated.h"
  
  USTRUCT(BlueprintType)
  struct FMyItemData : public FTableRowBase
  {
      GENERATED_BODY()
  
  public:
      UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
      FString ItemName;
  
      UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
      int32 Damage;
  
      UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Item")
      UTexture2D* ItemIcon;
  };
  

• 블루프린트로 구현 시: 콘텐츠 브라우저 -> 우클릭 -> 블루프린트 -> 구조체(Structure) 생성 후 원하는 변수들 추가.

단계 2: 데이터 테이블 에셋 생성

1. 언리얼 에디터의 콘텐츠 브라우저 우클릭 -> 기타(Miscellaneous) -> 데이터 테이블(Data Table) 선택.
2. 이전에 만든 구조체(Structure)를 선택하여 행의 규격을 지정 후 생성.

단계 3: 데이터 입력 및 외부 연동

• 에디터에서 직접 입력: 데이터 테이블을 더블 클릭하여 + 버튼(행 추가)을 눌러 직접 데이터를 채워 넣습니다.
• 엑셀/CSV 임포트: * 엑셀에서 첫 번째 열의 이름을 Name으로 지정합니다. (이 Name 열이 데이터 테이블의 행 이름(Row Name) 즉, Key 값이 됩니다.)
  • .csv 파일로 저장한 후, 언리얼 콘텐츠 브라우저로 드래그 앤 드롭하여 임포트합니다.

4. 블루프린트에서 데이터 가져오기

주로 사용되는 핵심 노드는 GetDataTableRow입니다.

• Data Table: 접근할 데이터 테이블 에셋을 지정합니다.
• Row Name: 가져오고 싶은 특정 행의 Key 이름(예: "Item_001")을 입력합니다.
• 반환 값 (Out Row): 알맞은 구조체 타입으로 데이터가 출력되며, Break [구조체이름] 노드를 통해 세부 멤버 변수들을 분리해 사용할 수 있습니다.
• 분기(Row Found / Row Not Found): 데이터가 존재하면 Row Found로 흐름이 이어지고, 이름이 잘못되어 찾지 못하면 Row Not Found로 안전하게 예외 처리가 가능합니다.

5. 실무 사용 팁 및 주의사항 (⚠️)

• Key 값(Name)의 고유성: 엑셀에서 데이터를 작성할 때 Name 열의 값은 중복되지 않는 고유한 값(ID 형태)이어야 합니다. 중복되면 임포트 시 데이터가 덮어씌워집니다.
• 런타임 수정 불가 (Read-Only): 데이터 테이블은 게임 실행 중에 데이터를 실시간으로 수정하고 '저장'하는 용도가 아닙니다. 게임 플레이 중 변하는 동적 데이터(예: 플레이어의 현재 체력, 현재 골드 등)는 데이터 테이블이 아닌 GameInstance나 PlayerState 같은 컴포넌트/클래스에서 관리해야 합니다.
• 에셋 참조 최적화: 구조체 내부에 무거운 텍스처나 스켈레탈 메쉬 등의 에셋을 직접 참조(UTexture2D*)하면, 데이터 테이블을 로드할 때 모든 에셋이 한 번에 메모리에 올라갈 수 있습니다. 대규모 프로젝트에서는 소프트 오브젝트 레퍼런스(TSoftObjectPtr)를 활용하는 것이 메모리 관리에 유리합니다.

💡 오늘의 한 줄 요약

데이터 테이블은 기획 데이터를 코드와 분리하여 효율적으로 관리할 수 있게 해주는 구조체 기반의 '읽기 전용' 데이터베이스다.