# 플레이와 HTTPS 호스팅

## PC에서 먼저 확인

프로젝트의 `start.cmd`를 실행합니다. 브라우저가 자동으로 `http://localhost:4218/`을 엽니다. **PC로 플레이**를 누르면 3인칭 자유 조준의 일반 게임이 시작됩니다. 적·보스의 공격과 체력·체크포인트·사망·클리어가 실제로 동작합니다. V로 1인칭 전환, M으로 음소거, R로 재시작, Esc로 쉬고 계속하기로 복귀합니다. 포인터 잠금이 거절되면 오른쪽 마우스 드래그로 조준할 수 있습니다. 자동 조준은 없습니다. 원작 음악과 SFX도 로컬 파일로 재생합니다.

`file://` 주소로 `index.html`을 열면 모듈 로딩이 차단될 수 있습니다. 이 경우 화면의 안내대로 `start.cmd`를 사용하세요. 외부 CDN·음원 응답을 기다리는 로더는 없습니다.

## Quest에서 개발용 접속

1. PC와 Quest를 같은 Wi-Fi에 연결합니다.
2. `start-quest-https.cmd`를 실행합니다.
3. 콘솔의 `Quest / same Wi-Fi: https://...:4219/` 주소 중 실제 Wi-Fi/LAN 어댑터 주소를 Quest 브라우저에 입력합니다. VPN·가상 어댑터 주소는 연결되지 않을 수 있습니다.
4. 로컬 테스트용 자체 서명 인증서의 경고가 표시됩니다. 해당 로컬 주소를 신뢰하는 경우에만 브라우저에서 예외를 선택합니다. 기기에 루트 인증서를 설치하는 과정은 필요하지 않습니다. 브라우저 정책이 예외 후에도 WebXR을 허용하지 않으면 아래의 신뢰된 HTTPS 배포를 사용합니다.
5. 페이지에서 **VR로 들어가기**를 누르고 브라우저의 VR 사용 권한을 허용합니다.
6. 양손 Touch 컨트롤러를 사용합니다. 손 추적 모드는 이번 데모의 입력 대상이 아닙니다.

서버는 HTTPS `4219` 포트를 사용합니다. Windows 방화벽이 연결을 차단한다면 해당 개발 서버의 로컬 네트워크 접근을 허용해야 합니다. 스크립트는 방화벽·공유기·인증서 신뢰 설정을 자동 변경하지 않습니다. PC 미리보기 `http://localhost`는 예외적으로 안전한 로컬 컨텍스트지만, **Quest에서 여는 PC의 `http://192.168...` 주소는 그 예외에 해당하지 않습니다.**

테스트 인증서와 개인 키는 `.local/`에만 생성되며 웹 서버에서 읽을 수 없도록 막고 배포 ZIP에서도 제외합니다. 네트워크 주소가 바뀌면 인증서를 새로 생성합니다.

## 정식 웹 주소로 배포

`rockman-vr-web.zip`을 풀면 `index.html`, `app/`, `engine/`, `nes-toon-kit/`, `vendor/`, `docs/` 등이 나옵니다. **폴더 관계를 유지한 채 전체 내용**을 HTTPS 정적 호스팅에 올립니다. 예: GitHub Pages의 배포 브랜치, Netlify의 정적 배포, 이미 보유한 HTTPS 웹 서버. 특정 서비스를 가입·게시하는 작업은 자동으로 실행하지 않습니다.

Cloudflare Pages는 `rockman3d-pages.zip`을 압축 그대로 Direct Upload에 사용합니다. Workers는 `rockman3d-workers-project.zip`을 풀어 Wrangler로 배포합니다. `assets/audio/`도 함께 들어 있습니다. 자세한 명령과 ZIP 선택은 [Cloudflare 가이드](CLOUDFLARE.md)에 있습니다.

시작이 실패하면 타이틀의 **오류 상세**에서 실제 실패 코드와 파일 경로를 확인할 수 있습니다. 음원 다운로드는 게임 진입을 잠그지 않습니다. 단순 지연·음원 실패와 WebGL 그래픽 초기화 실패를 각각 표시하며, 기존 오류가 시간 초과 문구로 덮이지 않습니다.

- 빌드 명령을 사용하는 호스팅: `npm ci && npm run build`, 출력 폴더 `dist`.
- 수동 업로드: `dist/`의 내용 또는 웹 ZIP의 내용을 사이트 루트에 업로드.
- `/rockman-vr/` 같은 하위 경로도 상대 경로 import map으로 동작합니다. 모든 하위 폴더를 함께 올리세요.
- `.js`, `.mjs`는 JavaScript MIME으로 제공해야 합니다. SPA의 전체 경로 → index.html 재작성 규칙으로 모듈 404를 가리지 마세요.
- 직접 전체 페이지로 여는 방식을 권장합니다. 다른 사이트의 iframe에 넣으려면 상위 페이지의 `allow="xr-spatial-tracking; fullscreen"` 및 Permissions-Policy 구성을 별도 확인합니다.
- 초기 VR 지원 확인 뒤에도 `requestSession`은 사용자의 버튼 클릭 안에서 실행되어야 합니다.
- `_headers`를 이해하는 호스팅은 포함된 XR 정책을 적용합니다. 다른 서버는 같은 헤더를 자체 설정할 수 있습니다.

배포된 게임에는 npm·Playwright·IWER·개발 인증서·게임 서버가 필요하지 않습니다. 브라우저가 정적 파일을 내려받아 렌더링합니다.

## 손과 이동

기본은 **오른손 무기 / 왼손 이동**입니다. 반대손 사용은 타이틀의 플레이 설정에서 바꾸고 VR에 진입합니다.

| 기능 | 기본 | 왼손 무기일 때 |
|---|---|---|
| 직접 조준 | 오른손이 가리키는 방향 | 왼손이 가리키는 방향 |
| 연속 발사 | 오른손 트리거 | 왼손 트리거 |
| 이동 | 왼손 스틱, 머리가 바라보는 수평 방향 기준 | 오른손 스틱 |
| 점프 | X | A |
| 슬라이딩 | Y / 왼손 스틱 클릭 | B / 오른손 스틱 클릭 |
| 스냅 회전 | 오른손 스틱 좌우, 30°씩 | 왼손 스틱 좌우 |
| 메뉴 열기 / 닫기 | 오른손 B | 왼손 Y |
| 메뉴 선택 | 무기 손으로 항목을 가리키고 트리거 | 동일 |

머리를 돌리는 동작은 조준 방향을 바꾸지 않습니다. 팔을 내리면 탄도 아래로 나갑니다. 적의 현재 위치에 자동으로 맞추거나 이동 방향을 예측하지 않으므로 움직이는 적에게는 직접 앞을 겨눠야 합니다.

슬라이딩 중 가상 시점 높이가 낮아지지만 머리 방향과 양안 간격은 계속 헤드셋이 결정합니다. 실제로 몸을 숙여도 충돌 높이가 낮아집니다. 가상 벽 쪽으로 실제 머리를 내밀면 화면이 어두워집니다. 뒤로 물러나면 돌아옵니다. 방 안 이동이 스틱 이동과 중복 적용되지 않습니다.

**편안하게**: 걷기 2.8m/s, 슬라이드 최고 5.5m/s. **빠르게**: 4.2m/s, 8m/s. 기본은 편안하게이며 이동 시 주변부를 어둡게 합니다. 화면 흔들림·카메라 롤·연출용 FOV 변화는 사용하지 않습니다.

## 코스와 적

시작에서 녹색 관로를 따라 전진합니다. 25m 지점 낮은 통로는 슬라이딩으로 통과합니다. 슬라이드가 끝나도 천장 아래에서는 낮은 자세로 전진할 수 있습니다. 가운데 발판은 점프로 넘거나 옆의 바닥 길을 이용할 수 있습니다.

41m, 81m에서 체크포인트와 일부 체력이 회복됩니다. HP와 슬라이드 2회 충전 상태는 이동 손 위의 패널에 있습니다. 손을 시야 안으로 들어 확인하세요. 사망 시 최근 체크포인트에서 재시작합니다.

가디언은 조준 사격, 낮은 파동, 높은 파동, 정면 반사 방어, 도약 사격을 순환합니다. 낮은 금색 파동은 점프, 높은 주황색 파동은 슬라이딩으로 피합니다. 방어 링이 켜진 정면에 발사하면 들어온 탄도를 반사합니다. 측면이나 회복 구간을 노리세요. 적이 움직여 버스터가 빗나가는 것은 정상 동작입니다.

## 성능 설정

Quest 2는 기본 **가볍게**를 사용합니다. 0.85 XR 프레임버퍼와 높은 고정 포비에이션으로 픽셀 비용을 줄입니다. 런타임이 지원하는 경우 72Hz를 요청합니다. 설정을 바꾸려면 VR을 종료한 다음 타이틀에서 변경하고 다시 진입합니다. 프레임버퍼 크기는 실행 중 바꾸지 않습니다.

Quest 3 이상에서는 **선명하게**를 시험할 수 있습니다. 이 설정은 1.0 배율, 포비에이션 0.65, 지원 시 90Hz를 요청합니다. 기기 이름만으로 속도를 보장하지 않으며 실제 런타임의 지원 목록을 확인합니다. 프레임 지연이 누적되면 장식 거리·입자 수·주변부 품질을 자동으로 낮춥니다. 적의 활성 거리와 공격 판정은 바뀌지 않습니다.

Quest 실기기 FPS·발열·멀미 정도는 PC 에뮬레이션으로 검증할 수 없습니다. `DEVICE_TEST.md`에 실기기 확인 순서를 정리했습니다.
