3-2. MassEntityConfig | UE5 Mass Entity Deep Dive

01

MassEntityConfigAsset

에디터에서 엔티티 구성을 정의하는 데이터 에셋

UMassEntityConfigAsset은 Trait들의 조합을 저장하는 Data Asset입니다. Content Browser에서 생성하여 에디터에서 편리하게 편집할 수 있습니다.

                    MassEntityConfigAsset 생성 방법
                    // Content Browser에서 생성:
// Right Click → Miscellaneous → Data Asset
// → UMassEntityConfigAsset 선택
//
// 에셋 편집:
// ┌─────────────────────────────────────────┐
// │  MassEntityConfigAsset: DA_Zombie        │
// │                                           │
// │  Config:                                  │
// │   Parent: (None 또는 다른 Config)          │
// │                                           │
// │   Traits:                                 │
// │    [0] UMassVisualizationTrait            │
// │        StaticMesh: SM_Zombie              │
// │    [1] UMassMovementTrait                 │
// │        MaxSpeed: 400.0                    │
// │    [2] UHealthTrait                       │
// │        DefaultHealth: 50.0                │
// │    [3] UZombieTrait                       │
// │    [4] UMassNavigationTrait               │
// └─────────────────────────────────────────┘
                

Config = 엔티티의 Blueprint

MassEntityConfig는 Actor로 치면 Blueprint Class와 유사합니다. 어떤 Component(Fragment)를 포함할지, 기본값은 무엇인지를 정의합니다. 다만 ECS 방식이므로 Trait를 통해 Fragment를 조합합니다.

02

Entity Template Registry

Config에서 Template로의 변환 과정

MassEntityConfig는 런타임에서 Entity Template으로 변환됩니다. Template Registry가 Config의 Trait들을 순회하며 최종 Archetype 구성을 결정합니다.

                    Template 빌드 과정
                    // Config → Template 변환 흐름
//
// 1. MassEntityConfigAsset 로드
//    ↓
// 2. Parent Config가 있으면 먼저 빌드
//    ↓
// 3. 각 Trait의 BuildTemplate() 호출
//    - Fragment 추가
//    - Tag 추가
//    - SharedFragment 설정
//    - 초기화 콜백 등록
//    ↓
// 4. Trait 의존성 검증 (ValidateTemplate)
//    ↓
// 5. FMassEntityTemplate 생성 완료
//    ↓
// 6. Template Registry에 캐싱
//    → 같은 Config로 생성되는 엔티티는 Template 재사용
                

                    C++ - 코드에서 Template 사용
                    // Config Asset 참조
UPROPERTY(EditAnywhere)
TSoftObjectPtr<UMassEntityConfigAsset> EntityConfig;

// Template 조회
void SpawnFromConfig(UWorld* World)
{
    if (UMassEntityConfigAsset* Config =
            EntityConfig.LoadSynchronous())
    {
        const FMassEntityTemplate& Template =
            Config->GetOrCreateEntityTemplate(*World);

        // Template에서 Archetype 정보 획득
        const FMassArchetypeHandle Archetype =
            Template.GetArchetype();

        // 이 Archetype으로 엔티티 생성
        FMassEntityManager& EM = UMassEntitySubsystem::
            GetEntityManager(World);
        FMassEntityHandle Entity =
            EM.CreateEntity(Archetype);

        // 초기화 콜백 실행
        Template.InitializeEntity(EM, Entity);
    }
}
                

03

Config 상속

Parent Config를 통한 계층적 엔티티 구성

MassEntityConfig는 Parent 설정을 통해 다른 Config를 상속할 수 있습니다. 공통 Trait를 부모에 두고, 자식에서 추가 Trait를 더하는 패턴입니다.

                    Config 상속 구조 예시
                    // DA_BaseEnemy (부모)
// ├── UMassVisualizationTrait
// ├── UMassMovementTrait
// ├── UHealthTrait (Health: 100)
// └── UMassNavigationTrait
//
// DA_Zombie (자식, Parent = DA_BaseEnemy)
// ├── [상속] UMassVisualizationTrait
// ├── [상속] UMassMovementTrait
// ├── [상속] UHealthTrait
// ├── [상속] UMassNavigationTrait
// ├── [추가] UZombieTrait        ← 좀비 전용 Tag
// └── [추가] UCombatantTrait     ← 근접 전투
//
// DA_FastZombie (자식, Parent = DA_Zombie)
// ├── [상속] 모든 Zombie Trait들
// └── [오버라이드] UMassMovementTrait (MaxSpeed: 800)
                

상속 시 주의사항

자식 Config에서 부모와 같은 타입의 Trait를 추가하면 오버라이드됩니다. 의도하지 않은 Trait 중복이나 누락을 방지하려면 상속 계층을 단순하게 유지하세요.

04

실전 Config 구성 전략

프로젝트에서 효과적으로 Config를 조직하는 방법

계층 구조

DA_BaseEntity
  DA_BaseCivilian
    DA_Pedestrian
    DA_Driver
  DA_BaseEnemy
    DA_Zombie
    DA_Skeleton
  DA_BaseVehicle
    DA_Car
    DA_Truck

설계 원칙

상속 깊이는 3단계 이하로 유지
공통 기능은 최상위 부모에 배치
특수 기능은 Trait 추가로 해결
Archetype 파편화를 최소화
비슷한 엔티티는 같은 Config 공유

Archetype 수 관리

서로 다른 Config는 서로 다른 Archetype을 생성합니다. Archetype이 너무 많으면 배치 처리 효율이 떨어집니다. 가능하면 같은 Fragment/Tag 구성을 공유하도록 Config를 설계하세요. SharedFragment의 값만 달라도 같은 Archetype으로 분류됩니다.

SUMMARY

핵심 요약

MassEntityConfigAsset은 Trait 조합을 저장하는 Data Asset으로, 에디터에서 엔티티 구성을 정의한다
Config는 런타임에 Entity Template으로 변환되며, Template Registry에 캐싱된다
Parent 설정을 통해 Config를 상속할 수 있으며, 공통 Trait를 부모에 두는 패턴이 유효하다
Config 상속 깊이는 3단계 이하로 유지하여 관리 복잡성을 줄인다
동일한 Fragment/Tag 구성을 공유하도록 Config를 설계하면 Archetype 파편화를 방지한다
SharedFragment 값만 달라지는 경우 같은 Archetype에 속하므로 배치 처리 효율이 유지된다

PRACTICE

도전 과제

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

실습 1: MassEntityConfig 에셋 생성

콘텐츠 브라우저에서 MassEntityConfig Data Asset을 생성하고, Trait 목록에 Transform, Visualization, 커스텀 Trait을 추가하세요. Validate 버튼으로 설정 오류를 확인하세요.

실습 2: MassSpawner로 배치

레벨에 AMassSpawner 액터를 배치하고, MassEntityConfig를 할당하세요. Count와 SpawnShape(Box, Circle)를 설정하여 특정 영역에 엔티티를 분포시키고, PIE에서 스폰을 확인하세요.

심화 과제: 다중 Config 구성

보행자용, 차량용, 환경 오브젝트용 MassEntityConfig를 각각 만들고, 하나의 레벨에 여러 MassSpawner를 배치하여 다양한 엔티티가 공존하는 시뮬레이션을 구성하세요.