@hatiolab/scene-monitor

Things Scene 보드의 성능 모니터링과 컴포넌트 인스펙션을 위한 Chrome DevTools 확장 프로그램입니다.

설치

방법 1: npm (권장)

프로젝트 루트에서 설치합니다:

npm install @hatiolab/scene-monitor

설치 후 확장 프로그램 파일이 다음 경로에 위치합니다:

node_modules/@hatiolab/scene-monitor/

방법 2: 직접 다운로드

GitHub 저장소에서 monitor-extension 폴더를 다운로드합니다:

git clone https://github.com/user/things-scene.git
cd things-scene/monitor-extension

Chrome에 등록

확장 프로그램은 Chrome Web Store를 거치지 않고 직접 로드합니다.

Step 1: 확장 프로그램 페이지 열기

Chrome 주소창에 입력합니다:

chrome://extensions

Step 2: 개발자 모드 활성화

페이지 우측 상단의 개발자 모드 토글을 켭니다.

Step 3: 확장 프로그램 로드

압축해제된 확장 프로그램을 로드합니다 버튼을 클릭하고, 폴더를 선택합니다:

• npm 설치한 경우:

  {프로젝트 루트}/node_modules/@hatiolab/scene-monitor

• 직접 다운로드한 경우:

  {다운로드 경로}/things-scene/monitor-extension

Step 4: 확인

등록이 완료되면:

• chrome://extensions 목록에 Scene Monitor가 나타납니다
• Chrome 툴바에 Scene Monitor 아이콘이 추가됩니다
• DevTools (F12)에 Scene Monitor 탭이 생깁니다

사용법

DevTools 패널 열기

1. Things Scene 보드가 포함된 페이지를 엽니다
2. F12 (Mac: Cmd+Option+I)로 DevTools를 엽니다
3. 상단 탭 목록에서 Scene Monitor를 선택합니다

Scene Monitor 탭이 보이지 않으면 탭 목록 끝의 >> 화살표를 클릭하세요.

Monitor 탭

실시간 성능 지표를 차트로 확인합니다.

| 지표 | 설명 | |------|------| | FPS | 초당 프레임 수 (높을수록 좋음) | | Draw (ms) | 프레임당 렌더링 소요 시간 (낮을수록 좋음) | | Events | 수집 간격 내 이벤트 트리거 횟수 | | Components | 현재 씬의 총 컴포넌트 수 |

컨트롤:

• Interval 슬라이더: 데이터 수집 간격 조절 (1초 ~ 30초)
• Pause: 수집 일시정지
• Resume: 수집 재개
• Clear: 차트 데이터 초기화

Inspector 탭

씬의 컴포넌트 구조를 탐색하고 상태를 확인합니다.

• 좌측 패널: 컴포넌트 트리. 클릭하여 선택합니다.
• 우측 패널: 선택된 컴포넌트의 state(상태값)를 JSON으로 표시합니다.
• 보드 연동: 보드에서 컴포넌트를 클릭하면 Inspector 트리에서 해당 컴포넌트가 자동 선택됩니다.
• 씬 전환 감지: 새 보드가 열리거나 닫히면 트리가 자동 갱신됩니다.

팝업 (툴바 아이콘)

Chrome 툴바의 Scene Monitor 아이콘을 클릭하면 간단한 모니터링 팝업이 열립니다. DevTools를 열지 않고도 FPS 등 기본 지표를 확인할 수 있습니다.

업데이트

npm

npm update @hatiolab/scene-monitor

직접 다운로드

새 버전의 monitor-extension 폴더를 다운로드합니다.

Chrome 반영

npm 업데이트 또는 파일 교체 후, Chrome에서 확장 프로그램을 새로고침해야 합니다:

1. chrome://extensions 열기
2. Scene Monitor 카드의 새로고침 버튼(↻) 클릭

새로고침 없이는 이전 버전이 계속 실행됩니다.

트러블슈팅

Scene Monitor 탭이 보이지 않음

• chrome://extensions에서 개발자 모드가 활성화되어 있는지 확인
• Scene Monitor가 목록에 있고 활성화(토글 ON) 상태인지 확인
• DevTools를 닫았다가 다시 열기 (F12 두 번)

데이터가 수집되지 않음 (차트가 비어있음)

• 보드 페이지가 완전히 로드되었는지 확인
• Pause 상태가 아닌지 확인
• Things Scene v10 이상이 필요합니다 (v9 이하는 scene.metrics API 미지원)
• 페이지를 새로고침(F5)한 후 DevTools를 다시 열어보세요

Inspector에서 "Scene not available"

• 보드가 아직 로딩 중일 수 있습니다. 잠시 후 다시 시도하세요.
• 확장 프로그램이 업데이트된 경우, chrome://extensions에서 새로고침 필요

확장 프로그램이 갑자기 동작하지 않음

Chrome 확장 프로그램이 업데이트되면 기존 연결이 끊어집니다:

1. chrome://extensions에서 Scene Monitor 새로고침(↻)
2. 모니터링 중이던 페이지를 새로고침(F5)
3. DevTools를 닫았다가 다시 열기

요구사항

• Chrome 88 이상 (Manifest V3 지원)
• Things Scene v10 이상 (scene.metrics API 필요)

연결 방식

확장 프로그램은 페이지의 globalThis.scene 또는 window.scene 객체를 감지합니다. Things Scene v10은 씬 생성 시 자동으로 globalThis.scene을 설정하므로 별도 설정이 필요 없습니다.

씬이 비동기로 초기화되는 경우에도 최대 30초간 자동 재시도하여 감지합니다.