6-2. EQS BP 활용 | UE5 블루프린트 마스터

01

EQS 개념과 구조

환경 쿼리 시스템의 3대 구성요소

EQS(Environment Query System)는 AI가 환경을 분석하여 "어디로 이동할까", "어디에 숨을까", "어디서 공격할까" 등의 결정을 내리는 시스템입니다.

                    EQS Components
                    Environment Query
  │
  ├─ Generator        // 후보 위치(Item)를 생성
  │   ├─ Points: Grid     // 그리드 형태로 점 생성
  │   ├─ Points: Circle   // 원형으로 점 생성
  │   ├─ Points: Donut    // 도넛 형태 점 생성
  │   ├─ Actors of Class  // 특정 클래스 Actor들
  │   └─ Current Location // 현재 위치
  │
  ├─ Context          // 기준점 (Querier, Target 등)
  │   ├─ Querier          // 쿼리를 실행하는 AI
  │   ├─ EnvQueryContext_Item // 각 후보 위치
  │   └─ Custom Context    // 블루프린트로 커스텀 정의
  │
  └─ Test             // 각 Item을 점수로 평가
      ├─ Distance         // 기준점과의 거리
      ├─ Trace            // 시야선(Line of Sight) 확인
      ├─ PathFinding      // NavMesh 경로 존재 여부
      ├─ Dot              // 방향 내적 (앞/뒤 판단)
      └─ GameplayTag      // 태그 기반 필터링
                

Generator
후보 위치 생성

→

Test 1~N
각 위치 점수화

→

최고 점수
위치 선택

→

Blackboard
결과 저장

02

EQS 에디터 사용법

Environment Query 에셋 생성과 설정

콘텐츠 브라우저에서 우클릭 > Artificial Intelligence > Environment Query를 선택합니다.

EQS 활성화 (UE 5.0~5.1)

UE5 초기 버전에서는 Project Settings > AI > Environment Querying System을 활성화해야 했습니다. UE 5.2+에서는 기본 활성화되어 있습니다.

엄폐 위치 찾기 예제

                    EQ_FindCoverPosition
                    EQ_FindCoverPosition
  │
  ├─ Generator: Points - Grid
  │   ├─ Grid Size: 1000 (cm)
  │   ├─ Space Between: 200 (cm)
  │   ├─ Generate Around: Querier
  │   └─ Project Down: NavMesh (NavMesh 위의 점만 유효)
  │
  ├─ Test 1: PathFinding
  │   ├─ Test Purpose: Filter Only
  │   ├─ Context: Querier
  │   └─ → 도달 불가능한 위치 제거
  │
  ├─ Test 2: Trace (Line of Sight to Target)
  │   ├─ Test Purpose: Score Only
  │   ├─ Context: Target (플레이어)
  │   ├─ Score: 시야 차단 = 높은 점수
  │   └─ → 적에게 안 보이는 곳이 높은 점수
  │
  ├─ Test 3: Distance to Querier
  │   ├─ Test Purpose: Score Only
  │   ├─ Scoring Factor: 0.3 (가중치)
  │   └─ → 가까운 곳 선호 (이동 최소화)
  │
  └─ Test 4: Distance to Target
      ├─ Test Purpose: Score Only
      ├─ Scoring Factor: 0.5
      └─ → 적에게서 적당히 먼 곳 선호
                

03

BT에서 EQS 사용

Behavior Tree에서 EQS 쿼리를 실행하고 결과 활용

                    BT with EQS Integration
                    // Behavior Tree에서 "Run EQS Query" Task 사용

Sequence "Find Cover and Move"
  ├─ Task: Run EQS Query
  │   ├─ Query Template: EQ_FindCoverPosition
  │   ├─ Blackboard Key: CoverLocation (Vector)
  │   └─ → 최고 점수 위치가 CoverLocation에 저장됨
  │
  ├─ Task: Move To
  │   └─ Blackboard Key: CoverLocation
  │
  └─ Task: Wait (2.0s) // 엄폐 유지
                

블루프린트에서 직접 EQS 실행

                    EQS in Blueprint (AIController)
                    // AIController에서 EQS 직접 실행
[Run EQS Query]
  ├─ Query Template: EQ_FindCoverPosition
  ├─ Querier: Self
  └─ (비동기 - 결과 콜백)

[On Query Finished (Delegate)]
  ├─ Query Result: EQSQueryResult
  │   └──> [Get Result as Location] (Index: 0)
  │          └──> Best Location (Vector)
  └──> [Set Blackboard Value as Vector]
         └─ Key: CoverLocation, Value: Best Location
                

비동기 쿼리 주의

EQS 쿼리는 비동기로 실행됩니다. 결과를 즉시 사용할 수 없으며, OnQueryFinished 델리게이트에서 결과를 받아야 합니다. BT의 "Run EQS Query" Task는 이를 자동으로 처리합니다.

04

EQS 디버깅과 활용 패턴

EQS Testing Pawn과 실전 쿼리 패턴

EQS Testing Pawn

레벨에 EQS Testing Pawn을 배치하면 에디터에서 EQS 결과를 시각적으로 미리보기할 수 있습니다. 각 후보 위치가 점수에 따라 색상(파랑=높음, 빨강=낮음)으로 표시됩니다.

실전 EQS 패턴

                    Common EQS Patterns
                    // 패턴 1: 순찰 포인트 (랜덤 탐색)
EQ_FindPatrolPoint
  Generator: Points: Donut (Inner: 500, Outer: 2000)
  Test: PathFinding (Filter)
  Test: Distance to Querier (Score, 역비례)

// 패턴 2: 사격 위치 (공격 가능한 최적 위치)
EQ_FindShootPosition
  Generator: Points: Circle (Radius: 800, Around: Target)
  Test: Trace to Target (Score, 시야 확보 = 높은 점수)
  Test: Distance to Target (Score, 300~600 범위 선호)
  Test: PathFinding (Filter)

// 패턴 3: 도주 위치 (위협에서 멀리)
EQ_FindFleePosition
  Generator: Points: Grid (2000, Around: Querier)
  Test: Distance to Target (Score, 정비례 - 멀수록 높음)
  Test: Trace to Target (Score, 시야 차단 선호)
  Test: PathFinding (Filter)
                

Test Scoring 이해

Filter Only: 조건 미충족 시 해당 위치 완전 제거
Score Only: 점수를 매겨 순위 결정 (최종 가중 합산)
Filter and Score: 필터링 후 점수 매기기
Scoring Factor: 해당 Test의 가중치 (0.0~1.0)

SUMMARY

핵심 요약

EQS는 Generator(후보 생성) + Test(점수화) + Context(기준점)로 구성된다
Generator로 그리드/원형/도넛 형태의 후보 위치를 생성한다
Test의 Filter는 부적합 위치를 제거하고, Score는 점수를 매겨 최적 위치를 선택한다
BT에서 Run EQS Query Task로 결과를 Blackboard에 자동 저장할 수 있다
EQS 쿼리는 비동기로 실행되므로 콜백에서 결과를 처리해야 한다
EQS Testing Pawn으로 에디터에서 쿼리 결과를 시각적으로 디버깅한다

PRACTICE

도전 과제

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

실습 1: 엄폐 위치 찾기 EQS

Environment Query를 생성하고, SimpleGrid Generator(반경 1000, 간격 200)로 후보 포인트를 생성하세요. Distance Test(플레이어로부터 멀리), Trace Test(플레이어 시야에서 차단됨) 두 가지 테스트를 추가하여 최적의 엄폐 위치를 찾으세요.

실습 2: BT에서 EQS 연동

Run EQS Query Task를 BehaviorTree에 추가하고, 쿼리 결과를 Blackboard의 CoverLocation 키에 저장하세요. 이후 Move To로 해당 위치로 이동하는 전체 플로우를 완성하고, EQS Testing Pawn으로 시각적 디버깅을 수행하세요.

심화 과제

커스텀 EQS Context(아군 위치), 커스텀 Generator(NavMesh 기반 포인트)를 블루프린트로 구현하세요. 아군과의 적정 거리를 유지하면서 적을 공격할 수 있는 위치를 선정하는 전술적 AI 포지셔닝 시스템을 만드세요.