개발 문서

프리뷰와 실제 플레이

Controller Preview는 게임 없이 컨트롤러 입력을 확인하는 화면입니다. Integration Preview는 업로드된 웹게임을 실제 스마트폰으로 제어하는 실행 화면입니다.

컨트롤러 프리뷰

1. 프리뷰 또는 프로젝트의 컨트롤러 메뉴를 엽니다.
2. JSON의 컴포넌트 위치, 크기, 이름, 이벤트를 수정합니다.
3. 프리뷰 반영을 눌러 화면과 입력 이벤트를 확인합니다.
4. 프로젝트 안에서 수정한 경우 컨트롤러 저장으로 반영합니다.

독립 프리뷰의 수정은 현재 브라우저 상태에서만 사용합니다. 새로고침하면 저장하지 않은 변경이 사라집니다. 프로젝트 저장은 다음 플레이 세션부터 적용됩니다. 게임 실행이 없으므로 독립 프리뷰는 Plays에 포함하지 않습니다.

통합 프리뷰

1. CLI로 웹게임 빌드를 배포합니다.
2. PC에서 프로젝트의 통합 프리뷰를 엽니다.
3. 플레이를 준비하면 표시되는 QR을 스마트폰으로 스캔합니다.
4. 스마트폰에서 컨트롤러 연결을 누릅니다.
5. 연결이 확인되면 PC에서 게임이 자동 시작됩니다.
6. 실제 입력과 게임 동작을 확인한 뒤 종료합니다.

QR 생성만으로는 Play가 차감되지 않습니다. 실제 게임 시작이 승인되면 1 Play가 차감되며 개발자 본인에게도 동일합니다. 새로 실행하려면 새로운 세션으로 시작합니다.

기기와 연결

• 하나의 PC 화면에 스마트폰 한 대가 연결됩니다.
• 게임 입력은 WebRTC DataChannel로 직접 전달됩니다.
• 연결용 정보만 서버를 거치며 연속적인 센서 입력을 MongoDB에 기록하지 않습니다.
• 센서는 스마트폰의 권한 허용 버튼을 직접 눌러야 합니다.
• QR 초대는 15분, 플레이 세션은 최대 2시간 동안 유효합니다.
• 브라우저를 닫거나 연결이 종료되면 새 QR로 다시 시작합니다.

회사망·모바일 데이터 등에서 직접 연결이 불가능할 수 있습니다. 운영자는 연결 설정에 따라 TURN 서비스를 준비할 수 있습니다. PC 한 대·스마트폰 한 대 제한은 네트워크가 같다는 의미가 아닙니다.

입력이 없다면

컨트롤러의 event와 SDK on() 이벤트 이름이 일치하는지 확인합니다. 폰에서 입력이 발생하는지, SDK가 신뢰하는 플랫폼 origin이 맞는지, 게임이 연결 종료 상태를 처리하는지 순서대로 확인하세요.

기본 SDK는 https://immercy.eturnalove.com을 신뢰합니다. 별도 Preview에서는 createImmercy({ parentOrigin: 'https://your-preview.example' })로 고정 주소를 명시합니다. 모든 origin을 신뢰하도록 바꾸지 않습니다.

지원하는 웹 빌드

스크립트, 스타일, 이미지 경로는 현재 파일 기준의 상대 경로를 사용하세요. Vite는 base: './'로 빌드합니다. 게임은 계정과 분리된 sandbox iframe에서 실행하므로 쿠키, localStorage, Service Worker, 임의 외부 API 호출을 사용할 수 있다고 가정하지 않습니다.

정적 검토는 실제 스마트폰 권한, 통신망, 입력 감각을 검증하지 않습니다. 공개 전에 위 실행 흐름을 실제 기기로 확인해야 합니다.