게임 에디터에서 3D 히트맵으로 이벤트 분포 확인하기

Framedash의 에디터 내 3D 히트맵은 기록된 이벤트의 분포를 실제 레벨 위에 겹쳐 보여 줍니다. Unity, Unreal Engine 5, Godot (C#)에서 반투명 상자를 통해 계단, 출입구, 위아래로 겹친 층 주변의 이벤트를 확인할 수 있습니다. 평면 지도만 보고 레벨 안의 위치를 짐작할 필요가 줄어듭니다.

먼저 색의 의미를 짚고 넘어가야 합니다. 현재 에디터 오버레이는 이벤트 수에 따라 색을 표시합니다. 대시보드에는 별도의 성능 지표 뷰가 있지만, SDK의 에디터 컨트롤에서는 FPS, 프레임 타임, GPU 시간, 메모리를 색상 기준으로 선택할 수 없습니다. 빨간 복셀은 가져온 데이터 안에서 이벤트가 많이 기록된 셀을 뜻합니다. 그 위치에 성능 문제가 있다는 의미는 아닙니다.

복셀 하나가 나타내는 것

복셀은 집계된 격자 셀 하나를 표현하는 작은 상자입니다. 에디터는 API에 XYZ 집계를 요청한 뒤 각 셀을 해당 격자 좌표에 그립니다. 개별 이벤트의 정확한 위치나 세션 재생이 아니라 이벤트 분포를 보여 주는 방식입니다.

세 축으로 나누어 집계하면 평면 뷰에서 겹치는 공간을 구분하는 데 도움이 됩니다. 예를 들어 셀 크기가 충분히 작으면 발코니와 그 아래 아트리움의 이벤트가 서로 다른 셀에 들어갑니다. 격자가 크면 두 공간이 여전히 한 셀로 합쳐질 수 있습니다. z가 없는 이전 API 응답은 설정된 맵 기준면에 평면 셀로 표시됩니다.

파랑에서 빨강으로 이어지는 5단계 색상은 응답 안의 최대 weight를 기준으로 정해집니다. 현재 에디터 엔드포인트에서 이 가중치는 이벤트 수입니다. Unity와 Godot은 범례 옆에 셀 수와 최대 가중치도 표시합니다. 스크린샷을 비교할 때는 이 숫자부터 확인하세요. 서로 다른 요청에서 같은 빨강으로 보이는 셀이라도 이벤트 수는 다를 수 있습니다.

한 번에 반환되는 셀은 가중치가 큰 순서대로 최대 10,000개입니다. 상한에 도달하면 이벤트가 적은 일부 셀이 빠질 수 있습니다. 기간을 줄이거나 이벤트 이름으로 필터링해 보세요. 셀 크기를 늘려 다시 가져오는 방법도 있습니다. 조건에 맞는 이벤트를 기록하지 않은 영역에도 셀은 나타나지 않습니다. 빈 공간이라고 해서 성능이 좋다는 뜻은 아닙니다.

데이터와 읽기 권한 준비하기

오버레이에는 비어 있지 않은 map_id와 의미 있는 월드 좌표를 가진 이벤트, 그리고 Framedash에 등록된 해당 맵이 필요합니다. 맵의 월드 좌표 범위도 확인하세요. 범위 밖의 이벤트는 격자에 포함되지 않습니다. 이미 이 조건을 만족하는 이벤트를 보내고 있다면 기존 데이터를 사용할 수 있습니다. 자동 perf_heartbeat에는 위치가 없고 map_id도 비어 있으므로, 하트비트만으로는 이 공간 격자를 채울 수 없습니다.

에디터에는 analytics:read 범위의 Read API Key와 해당 프로젝트 ID를 설정합니다. 게임에서 이벤트를 전송하는 쓰기 전용 수집 키와는 별개입니다. 읽기 키를 에디터 설정에 저장하고 싶지 않다면, 에디터를 실행하기 전에 FRAMEDASH_ANALYTICS_API_KEY를 설정하고 키 입력란을 비워 두세요. 세 SDK 모두 이 방식을 지원하며, 입력란에 키를 지정하면 그 값을 우선 사용합니다.

읽기 전용이어도 키는 인증 정보입니다. 소스 관리, 내보낸 게임, 로그, 스크린샷에 포함되지 않도록 하세요. API 기본 URL은 실제로 데이터를 저장한 배포 환경에 맞춰 지정합니다.

엔진별 히트맵 열기

아래에서 설명하는 조작 방식은 2026년 7월 24일 SDK 업데이트인 Unity 0.1.7, UE5 0.1.13, Godot 0.1.8에 추가됐습니다. 이 번호는 해당 기능이 도입된 버전이며, 각 SDK의 최신 버전 목록은 아닙니다.

Unity SceneView

1. Window > Framedash Heatmap을 열고 읽기 키, 프로젝트 ID, API 기본 URL을 설정합니다.
2. 맵 목록을 새로 고쳐 맵을 선택한 뒤 기간, 셀 크기, 필요한 경우 이벤트 이름 필터를 지정합니다. Play 모드 밖에서 Fetch를 누릅니다.
3. SceneView의 Framedash Heatmap 오버레이에서 Show는 표시 전환, Frame은 전체 데이터가 보이도록 시점 이동, Controls는 설정 창 다시 열기입니다.

설정 창을 닫아도 오버레이는 계속 사용할 수 있습니다. 선택한 맵과 표시 설정은 프로젝트별로 저장되며, Play 모드에서는 오버레이가 숨겨집니다.

Unity에서 기록한 Vector3의 각 성분은 SceneView의 X/Y/Z에 그대로 대응합니다. 지면에 맞추기 위한 축 교환은 하지 않습니다. Z Offset은 표시 위치만 옮기는 설정이며, 저장된 좌표를 수정하지 않습니다.

Unreal Engine 5 레벨 뷰포트

Project Settings > Plugins > Framedash Heatmap에서 API URL, 프로젝트 ID, 읽기 키, 표시 설정을 지정합니다. Window > Framedash > Framedash Heatmap을 열어 맵과 조회 조건을 선택하고 Play In Editor(PIE) 밖에서 데이터를 가져옵니다.

오버레이를 보고 싶은 각 레벨 뷰포트에서 Show > Framedash Heatmap을 켜세요. 기본값은 꺼짐이고 뷰포트마다 독립적이므로, 한쪽은 히트맵 없이 편집용으로 둘 수 있습니다. 데이터 패널을 닫아도 이미 불러온 오버레이는 사라지지 않습니다.

일반 F9 스크린샷과 고해상도 뷰포트 스크린샷에 모두 히트맵이 포함됩니다. 이슈에 이미지를 첨부할 때는 맵, 기간, 셀 크기, 이벤트 필터를 함께 적어 두세요. 다른 개발자도 색을 해석할 수 있습니다. PIE 중에는 표시가 중단되고, 종료 후 이전 뷰포트 선택으로 돌아옵니다.

Godot (C#) 3D 에디터

C# 애드온을 빌드하고 활성화한 뒤 Framedash Heatmap 독을 엽니다. 읽기 키, 프로젝트 ID, API 기본 URL을 입력하고 기간과 셀 크기를 선택합니다. Refresh Maps로 목록을 새로 고쳐 맵을 선택한 다음 Fetch Heatmap을 누릅니다. Show를 켜고 Frame Heatmap으로 3D 에디터 카메라를 불러온 셀 전체에 맞춥니다.

독에는 이벤트 이름 필터, 불투명도, Z 오프셋 설정도 있습니다. 셀은 캐시된 반투명 메시로 그리며, 게임 실행 중에는 오버레이를 숨깁니다. 설정은 프로젝트별 에디터 메타데이터인 .godot/editor/editor_layout.cfg에 저장되므로 .godot/은 버전 관리에서 제외하세요. 히트맵 코드는 에디터 전용입니다.

성능 조사에 함께 사용하기

대시보드와 에디터의 조회 범위는 서로 다를 수 있습니다. 현재 에디터에서 지정할 수 있는 조건은 맵, 기간, 셀 크기, 이벤트 이름입니다. 대시보드에서 선택한 빌드, 플랫폼, 성능 지표는 에디터에 전달되지 않습니다.

성능을 조사할 때는 다음 순서로 사용하세요.

1. 대시보드에서 맵, 빌드, 대상 플랫폼, 기간을 선택하고 성능 지표와 수치를 확인합니다. 히트맵은 한 번에 한 빌드를 보여 줍니다. 기준 빌드와 후보 빌드의 수치 비교는 Regression 페이지에서 합니다.
2. 해당 레벨을 열고 에디터 이벤트 뷰를 가져와, 계측한 활동이 어디에 분포하는지 확인합니다. 선택한 기간에 여러 빌드나 플랫폼이 섞여 있다면 그 복셀을 대시보드에서 선택한 빌드만의 결과로 해석해서는 안 됩니다.
3. 적절한 측정용 빌드에서 의심되는 경로나 장면을 재현하고 엔진 프로파일러로 캡처합니다. 캡처 결과를 바탕으로 렌더링 작업, 스크립트, 메모리 할당을 조사합니다. 복셀이 에셋 가까이에 있다는 이유만으로 그 에셋의 비용을 특정할 수는 없습니다.
4. 수정 후에는 장치, 설정, 경로, 측정 구간을 일정하게 유지해 다시 측정하고 수치를 비교합니다. 에디터 색이 차가운 색으로 바뀌는 것은 이벤트 수가 줄었거나 상대적인 최댓값이 달라졌기 때문일 수도 있습니다. 색 변화만으로 수정 효과를 검증할 수는 없습니다.

이벤트 밀도는 어디에서 얼마나 자주 기록하는지에도 영향을 받습니다. 사망 이벤트 히트맵은 기록된 사망의 분포를, 일정 간격의 위치 이벤트는 샘플링된 활동의 분포를 나타냅니다. 어느 쪽도 자동으로 체류 시간 지도가 되지는 않습니다. 샘플링 비율을 바꾸면 비교에 사용할 수 있는 데이터도 달라집니다.

보이지 않거나 위치가 어긋날 때

먼저 프로젝트 ID와 키 범위를 확인한 뒤 등록된 맵 ID, 기간, 이벤트 이름 필터를 점검하세요. 이벤트가 의도한 좌표로 도착했고 맵 범위 안에 있는지도 확인합니다. Frame 또는 Frame Heatmap으로 불러온 데이터를 찾고, 플레이를 멈춘 상태에서 표시 토글이 켜져 있는지 확인하세요.

오버레이가 어긋나 있다면 표시 오프셋을 조정하기 전에 레벨과 기록 데이터의 좌표계를 비교하세요. 이벤트 기록 이후 레벨 구조를 옮겼다면, 이전 배치에는 맞는 셀도 현재 장면에서는 어긋나 보일 수 있습니다.

처음에는 맵 하나와 발생 위치를 아는 이벤트 한 종류로 확인하세요. 예상한 위치에 표시되면 조회 범위를 넓히면 됩니다.

• 대시보드 지표와 필터는 성능 히트맵을 참고하세요.
• SDK 설치와 설정은 Unity, Unreal, Godot 가이드에 있습니다.