4-1. MassAI 아키텍처 | UE5 Mass Entity Deep Dive

01

MassAI 플러그인 구조

전통적 AI와 Mass AI의 차이점과 구성 요소

전통적인 UE5 AI 시스템(Behavior Tree + AIController)은 Actor 단위로 동작하여 대규모 AI에 부적합합니다. MassAI는 수천~수만 AI 에이전트를 ECS 방식으로 처리합니다.

비교	전통 AI	MassAI
AI 제어	AIController + BT	StateTree + Processor
데이터 저장	Blackboard	Fragment
경로 탐색	NavMesh + MoveTo	MassNavigation + ZoneGraph
충돌 회피	RVO / DetourCrowd	MassAvoidance (Force-based)
상호작용	직접 참조	SmartObject + Signal
확장성	~100 AI	10,000+ AI

                    MassAI 모듈 구성
                    // MassAI 플러그인이 포함하는 주요 모듈
// ┌─────────────────────────────────────────────┐
// │  MassAI Plugin                                │
// │                                               │
// │  ┌─── 행동 결정 ──────────────────────────┐  │
// │  │  MassAI (Core)                          │  │
// │  │  - StateTree 통합                       │  │
// │  │  - UMassStateTreeSubsystem              │  │
// │  └────────────────────────────────────────┘  │
// │                                               │
// │  ┌─── 이동 ───────────────────────────────┐  │
// │  │  MassNavigation                         │  │
// │  │  - 경로 탐색, ZoneGraph                 │  │
// │  │  - FMassNavigationFragment              │  │
// │  └────────────────────────────────────────┘  │
// │                                               │
// │  ┌─── 충돌 회피 ──────────────────────────┐  │
// │  │  MassAvoidance                          │  │
// │  │  - Force 기반 충돌 회피                  │  │
// │  └────────────────────────────────────────┘  │
// │                                               │
// │  ┌─── 상호작용 ───────────────────────────┐  │
// │  │  MassSmartObjects                       │  │
// │  │  - SmartObject 쿼리 및 사용              │  │
// │  └────────────────────────────────────────┘  │
// └─────────────────────────────────────────────┘
                

02

AI 관련 Fragment

MassAI에서 사용되는 주요 데이터 Fragment

Fragment	역할	모듈
`FMassStateTreeInstanceFragment`	StateTree 인스턴스 데이터	MassAI
`FMassMoveTargetFragment`	이동 목표 위치 및 속도	MassNavigation
`FMassNavigationFragment`	내비게이션 상태	MassNavigation
`FMassAvoidanceFragment`	회피 벡터, 힘 데이터	MassAvoidance
`FMassSmartObjectUserFragment`	SmartObject 사용 상태	MassSmartObjects
`FMassLookAtFragment`	시선 방향 목표	MassAI

Pulling 패턴

MassAI는 Pulling 패턴을 사용합니다. StateTree가 직접 이동을 실행하지 않고, Fragment에 목표 데이터를 설정(Set)하면 Movement Processor가 그 데이터를 읽어서(Pull) 실제 이동을 수행합니다.

03

SmartObject 통합

Mass Entity에서 SmartObject와 상호작용하는 방법

SmartObject는 월드의 특정 위치에서 AI가 수행할 수 있는 행동을 정의합니다. 벤치에 앉기, 커피숍에서 주문하기, 교통 신호 대기 등이 SmartObject로 구현됩니다.

                    MassAI + SmartObject 흐름
                    // SmartObject 상호작용 흐름
//
// 1. StateTree에서 SmartObject 검색 태스크 실행
//    → FMassSmartObjectUserFragment에 검색 결과 저장
//
// 2. 가장 적합한 SmartObject 선택 및 예약(Claim)
//    → SmartObjectSubsystem을 통해 슬롯 예약
//
// 3. SmartObject 위치로 이동
//    → FMassMoveTargetFragment에 목표 설정
//    → MassNavigation Processor가 경로 탐색
//
// 4. 도착 후 SmartObject 행동 실행
//    → StateTree의 SmartObject Task가 행동 수행
//    → 벤치에 앉기, 물건 줍기 등
//
// 5. 행동 완료 후 SmartObject 해제(Release)
//    → 슬롯을 다른 에이전트가 사용 가능
                

City Sample에서의 SmartObject

City Sample은 수천 개의 SmartObject를 사용합니다. 보행자가 벤치에 앉거나, 가게 앞에서 멈추거나, 횡단보도를 건너는 행동이 모두 SmartObject를 통해 구현되어 있습니다.

04

Mass Signal 시스템

엔티티 간 이벤트 전달 메커니즘

Mass Entity는 기본적으로 Pulling 패턴이지만, 때로는 이벤트를 푸시해야 합니다. MassSignalSubsystem이 이 역할을 합니다.

                    C++ - Mass Signal 사용
                    // 시그널 정의 (이름 기반)
namespace MySignals
{
    const FName OnDamaged = TEXT("OnDamaged");
    const FName OnTargetReached = TEXT("OnTargetReached");
    const FName OnAlerted = TEXT("OnAlerted");
}

// 시그널 전송 (Processor에서)
UMassSignalSubsystem& SignalSubsystem =
    Ctx.GetMutableSubsystemChecked<UMassSignalSubsystem>();

// 특정 엔티티에 시그널 전송
SignalSubsystem.SignalEntity(
    MySignals::OnDamaged, TargetEntity);

// 여러 엔티티에 시그널 전송
SignalSubsystem.SignalEntities(
    MySignals::OnAlerted, NearbyEntities);

// StateTree에서 시그널을 받아 상태 전환에 사용
// → 시그널이 도착하면 StateTree가 해당 상태를 재평가
                

SUMMARY

핵심 요약

MassAI는 StateTree, Navigation, Avoidance, SmartObject를 통합하여 대규모 AI를 구현한다
전통 AI(BT+AIController)와 달리 ECS 방식으로 10,000+ AI 에이전트를 처리할 수 있다
Pulling 패턴: StateTree가 Fragment에 데이터를 설정하면, Processor가 읽어서 실행한다
SmartObject를 통해 AI와 월드 환경 간의 상호작용을 구현한다
MassSignalSubsystem으로 엔티티 간 이벤트를 전달하며, StateTree의 상태 전환을 트리거한다
각 기능은 별도의 Fragment/Processor로 분리되어 있어 필요한 것만 조합 가능하다

PRACTICE

도전 과제

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

실습 1: MassAI 플러그인 설정

MassAI 플러그인을 활성화하고 .Build.cs에 MassAI, MassNavigation 의존성을 추가하세요. MassEntityConfig에 MassAI 관련 Trait(StateTree, Navigation)을 추가하여 AI 엔티티의 기본 구성을 만드세요.

실습 2: Smart Object와 Mass Entity 연동

레벨에 Smart Object(벤치, 교차로 등)를 배치하고, Mass Entity가 Smart Object를 감지하여 상호작용하는 기본 플로우를 구현하세요. SmartObject Data Interface를 활용하세요.

심화 과제: MassAI 처리 단계 분석

MassAI의 내부 Processor 체인(StateTree Evaluation -> Navigation -> Avoidance -> Movement)을 로그로 추적하세요. 각 단계의 실행 순서와 데이터 의존성을 다이어그램으로 문서화하세요.