[UE5] SCENE_QUERY_STAT() 매크로

SCENE_QUERY_STAT()은 언리얼에서 C++로 충돌 처리를 감지할 때마다 사용하는 매크로 중 하나이다.

특히 아래와 같이 FCollisionQueryParams를 만들 때 가장 많이 사용된다.

FCollisionQueryParams CollisionQueryParam(SCENE_QUERY_STAT(GateTrigger), false, this);

 

SCENE_QUERY_STAT()은 프로파일링이나 디버깅 등을 추적하기 위한 태그를 반환하는 것으로 보인다.

해당 매크로는 특히 FCollisionQueryParams의 첫 번째 인자로 주로 사용되는데, 게임 로직 자체에는 영향을 주지 않고, 프로파일링 / 스탯 집계용으로 이름을 식별할 때 쓰인다.

예를 들어 가장 많이 사용되는 FCollisionQueryParams의 정의를 보자.

FCollisionQueryParams(FName InTraceTag, 
    bool bInTraceComplex=false, 
    const AActor* InIgnoreActor=NULL)

FCollisionQueryParams의 첫 파라미터에는 FName TraceTag가 필요한데, SCENE_QUERY_STAT 이 FName을 만들어준다. 이때 이 SCENE_QUERY_STAT 매크로의 파라미터에는 꼭 클래스 이름 같은 것만 쓸 수 있는 건 아니고, 아무 이름이나 쓰면 된다. 일종의 스탯 집계용 고유 이름이라 보면 되겠다.

진짜 아무 이름(ex: USomeClass)으로 지어도 컴파일된다. 컴파일하면 위와 같이 매크로 코드를 만든다.이

이렇게 UE5에서 라인트레이스, 스윕, 오버랩 등에서 씬 쿼리(SCENE_QUERY_STAT )를 쓰면 통계시스템에 차곡차곡 저장되는데 이는 다른 시스템에서 읽어올 수 있다. 특히나, 앞에서 지은 이름(예시: USomeClass)으로 통계에 기록되어 검색도 가능하니, 어떤 종류의 쿼리에서 성능 문제가 발생하였는지 파악할 수도 있다.

예를 들어 카오스 비주얼 디버거(Chaos Visual Debugger)에서 씬 쿼리 인스펙터(Scene Query Inspector)를 활용하면 씬 내에서 이뤄지는 모든 물리 쿼리들을 읽어올 수 있는 것으로 보인다. 물리 충돌 쿼리를 시각적으로 볼 수 있어 굉장히 유용하니 참고하자.

오른쪽 인스펙터에 나와 있는 것처럼 SCENE_QUERY로 수집한 물리 충돌들을 디버거로 볼 수 있는 듯하다.

이에 대한 내용은 아래 링크에 더 잘 설명되어 있으니 시간이 난다면 한 번 읽어보자. 특히 영상도 제공하고 있으니 읽어보길 추천.

https://dev.epicgames.com/community/learning/tutorials/bZPZ/unreal-engine-chaos-visual-debugger-user-guide-ue-5-5#scenequerybrowser

Chaos Visual Debugger - User Guide for UE 5.5 | Tutorial

 

이렇듯, SCENE_QUERY_STAT()을 이용하면 어떤 물리 처리에서 병목이 생기는지 파악할 수 있는 중요한 단서를 수집해 주기 때문에, 조금이라도 성능 병목이 될 만한 부분이라면 해당 매크로를 사용해 주는 것이 좋다고 한다.

 

참고

https://forums.unrealengine.com/t/what-does-scene-query-stat-do/618084

What does "SCENE_QUERY_STAT" do?

https://dev.epicgames.com/community/learning/tutorials/bZPZ/unreal-engine-chaos-visual-debugger-user-guide-ue-5-5#scenequerybrowser

Chaos Visual Debugger - User Guide for UE 5.5 | Tutorial