# VR 엔진 어댑터 / Fable 전달 메모

이 문서는 `F:\testgame\rockman_vr`의 구현을 설명합니다. 원본 `F:\testgame\testgame_4`를 수정하거나 실행 시 참조하지 않습니다. `reference/`에는 허용된 원본 문서의 복사본이 있고 `shared-snapshot.json`에는 복사한 68개 파일의 SHA-256과 시각이 있습니다. 원본이 작업 중이므로 현재 원본과 해시가 달라도 자동 갱신하지 않습니다.

## 배치와 경계

```text
index.html                 로컬 Three import map, 타이틀 / PC UI
app/
  main.js                  호스트: WebXR 수명주기, 고정 루프 연결, UI 조립
  config.js                입력 매핑, ReleaseGate, SnapTurn, 품질/기동 데이터
  input.js                 XR Touch / PC 입력 어댑터, 단일 손 조준 결과
  rig.js                   floor anchoring, head-centered snap turn
  game.js                  DOM 없는 모터·AI·탄·피해·체크포인트 시뮬레이션
  sky-course.js            새 공중 기지, 정적 충돌체·청크·관제탑·구름
  player-avatar.js         챔퍼 메카 메시 + 기존 BipedProcedural
  desktop-view.js          충돌하는 PC 카메라 / 1·3인칭 / 정확한 화면 ray
  game-audio.js            기존 원작 Ogg 5곡·24 cue 연결 / PCM 캐시
  geometry.js              정적 vertex-color 메시 베이킹
  visuals.js               인스턴스·풀 기반 적/탄/효과
  toon-vr.js               키트의 ToonMaterials 위 VR 셰이더 어댑터
  spatial-ui.js            손목 HUD / 월드 메뉴 / 주변부·벽 페이드
engine/                    고정된 공통 엔진, 수정 없음
nes-toon-kit/src/           고정된 카툰 키트, 수정 없음
vendor/three/              Three r170, 수정 없음
tools/                     정적 HTTP/HTTPS 서버, 빌드·검사·IWER QA
```

`engine/`, `nes-toon-kit/`, `vendor/`의 상대 배치를 유지합니다. 기존 `engine/render/index.js`의 `../../nes-toon-kit/src/` 계약도 보존됩니다. VR 자체는 해당 런타임의 Composer 경로를 부르지 않고 ToonMaterials를 직접 사용합니다. 번들 중복을 피하려고 브라우저의 모든 `three` import는 한 로컬 r170 import map으로 모읍니다. npm의 Three는 Node 검사에서 같은 버전 수학 클래스를 해석하기 위한 개발 의존성입니다.

## 재사용한 것과 VR에서 바꾼 것

| 영역 | 사용 / VR 조정 |
|---|---|
| FixedLoop | 120Hz, 최대 6스텝 그대로. XR `setAnimationLoop`가 프레임을 공급 |
| Time | 고정 스텝에서 `Time.step()` 결과가 게임 시간. 실제 프레임 dt는 `beginFrame()` |
| Actions | 장치 입력을 move / jump / dash / fire로 추상화. 슬라이드가 dash에 대응 |
| Kernel / CharacterMotor | 정적 AABB·격자·스윕, 점프 버퍼·코요테·저천장·대시 충돌 재사용. 수치만 인스턴스 복사본에서 변경 |
| Projectiles | 고정 풀 80개, 움직이는 캡슐과 상대 운동 연속 판정. 직선 속도 유지 |
| 액터 / Events | 플레이어·적 HP / 위치·팀·aimPoint 계약 재사용. 효과·합성음은 이벤트 구독 |
| resolveAim | 데스크톱 록온/리드 계산기를 사용하지 않음. 컨트롤러 `updateAim()` 하나를 레이와 발사에 공유 |
| 카메라 | XR native pose / projection / IPD에 권위. 데스크톱 yaw/pitch와 완전 분리 |
| 렌더 | ToonMaterials의 색·밴드·림·하이라이트 유지, per-eye world light 어댑터. 직접 render |
| 효과 / UI | 시점 흔들림·화면 히트스톱 대신 무기 후퇴·메시 섬광·기하 입자·선택적 진동. HUD는 실제 3D 평면 |
| 오디오 | Mixer를 공유하고 GameAudio가 사용자가 지정한 기존 원작 Ogg를 로컬 재생. SfxSynth snapshot은 보존하지만 현재 재생 경로에는 사용하지 않음. `hurt`는 `{target, weapon}` 형식 유지 |

공통 엔진 문서의 8번(단일 조준), 9번(시점 권위)은 의도를 유지하면서 VR용 권위 원천으로 교체한 것입니다. 기존 3인칭 카메라에 XR 행렬을 덧붙이거나 적을 중심으로 카메라를 회전시키지 않습니다.

이번 새 `app/`은 프로토타입 호스트이며 원본 `games/`로 합치지 않았습니다. 원본의 JSDoc 파일을 바꾸지 않았고 새 코드의 검증은 Node 문법/행동 검사와 브라우저 QA입니다. 새 어댑터 전체에 대한 TypeScript/JSDoc 타입 검사는 아직 별도 도입하지 않았습니다. 공통 엔진으로 승격할 때 입력·세션·렌더 타입을 정식 계약으로 추가해야 합니다.

## 프레임 순서와 시간

```text
XR animation callback
  native viewerPose / controller poses 유효성 확인
  헤드 floor position → world head / 수평 이동 yaw
  xr-standard 버튼·축 읽기 → release gates → Actions.sample
  고정 120Hz × N
    Actions.nextStep (버튼 edge는 한 번만)
    tracked head XZ에 body capsule 이동 (room-scale)
    CharacterMotor (virtual locomotion)
    동일 손 조준 origin을 virtual delta만큼 이동
    적 → 탄 → swept collision → 피해 / 이벤트
    rig에 virtual delta만 더함
  native head pose는 시뮬레이션 alpha / slowmo에 종속하지 않음
  가상 슬라이드 높이 / 주변부·벽 페이드
  컨트롤러 muzzle / beam / wrist / 인스턴스 갱신
  직접 renderer.render(scene, camera) → 양안
```

게임에는 현재 히트스톱·슬로모 요청을 넣지 않습니다. 나중에 추가해도 HMD 추적은 실시간으로 유지해야 합니다. AI·탄·물리는 Time의 같은 결과를 쓰고 머리 행렬은 절대로 정지시키지 마세요. GPU가 너무 느려 최대 6스텝을 넘으면 엔진 계약대로 게임 시간이 늦어집니다. 품질 조정으로 피해야 할 상태이며 게임 판정을 건너뛰어 속도를 맞추지 않습니다.

## 좌표 / 손 조준 계약

- 게임 코스는 +Z 진행입니다. Three 카메라/컨트롤러 forward는 −Z입니다. 리그 초기 yaw=π로 맞춥니다.
- 실제 위치 단위는 미터입니다. `local-floor`가 필수입니다. `viewer` 기준을 floor로 가장하지 않습니다.
- `XRControls.aim = { origin: Vector3, direction: Vector3, valid: boolean }`는 호출자가 소유한 재사용 객체입니다.
- weapon의 `targetRaySpace` world quaternion으로 `(0,0,-1)`을 변환합니다. ray 원점에서 .28m 전방이 muzzle입니다.
- 그 결과가 레이와 Buster `velocity=direction*42m/s`에 공유됩니다. `aimPoint`, 적 중심, 리드, 유도 가속은 **플레이어 탄**에 쓰지 않습니다.
- HMD 회전과 무기 손 회전은 독립입니다. 장치 좌표를 마우스 movementX로 변환하지 않습니다.
- 무기 후퇴는 메시 위치만 약 .035m 움직입니다. 탄 방향·머리·IPD는 움직이지 않습니다.
- 적 사격은 발사 순간 플레이어 위치로 향합니다. 발사 후에는 직선입니다. 보스 방어는 실제 입사 벡터와 전면 법선의 반사입니다.
- 컨트롤러 추적이 유효한지는 매 프레임 `frame.getPose`로 확인합니다. 지난 프레임 메시가 보인다는 이유로 계속 발사하지 않습니다.
- 실제 손이 가상 벽 너머로 들어가더라도 head→muzzle의 정적 스윕이 막히면 발사를 금지합니다. 이 상태가 이동까지 막지는 않습니다. PC 총구는 시점→총구 스윕으로 벽 앞에 제한하고, 중앙 화면의 정적 지형 교차점으로 수렴합니다. 적 위치로 수렴시키지 않습니다.

## 방 안 이동 / 회전

헤드 XZ의 world 위치를 충돌 몸체 목표로 사용합니다. 실제 방 안에서 .4m 움직이면 몸체도 .4m만 이동하고, 이 이동을 리그에 다시 더하지 않습니다. 스틱 모터가 만든 delta만 리그에 더합니다. 이를 섞으면 실제 움직임이 두 배가 되거나 스틱 이동이 다음 프레임 취소됩니다.

가상 벽에 실제 머리를 밀어 넣었을 때 머리를 강제로 당기지 않습니다. 충돌 캡슐은 벽에서 멈추고 머리·몸 분리 거리와 머리의 충돌체 침입으로 화면을 어둡게 합니다. 실제로 뒤로 돌아오면 회복합니다. 페이드는 충돌 경고이며 현실 공간의 안전 경계를 대신하지 않습니다.

일시 정지 중에도 같은 고정 틱에서 실제 방 안 이동에 대한 안전 캡슐만 따라갑니다. AI·게임 시간·탄·피해는 멈춥니다. 메뉴를 켠 채 빈 공간에서 한 걸음 옮겼다는 이유만으로 몸체와 머리가 떨어져 화면이 검어지는 오류를 막습니다.

스냅 회전은 회전 전·후 headWorld 차이를 리그 XZ로 보상합니다. floor 원점이 머리에서 떨어진 경우에도 머리가 원을 그리며 옮겨지지 않습니다. 스틱 |x|<.25에서 재무장, |x|>.7에서 30° 회전 1회입니다.

가상 슬라이드는 floor offset을 감쇠시켜 눈 높이를 약 .68m로 낮춥니다. native pose는 계속 살아 있으며 실제 숙이기도 충돌 캡슐 높이에 반영합니다. 이것은 순간이동·순수 room-scale만 쓰는 게임보다 수직 가상 움직임이 있는 방식입니다. 더 보수적인 제품에서는 슬라이드 중 외곽 페이드를 늘리거나 수직 이동 없이 몸체만 낮추는 선택지를 검토할 수 있습니다.

## 수명주기

`requestSession`은 VR 버튼의 사용자 제스처 안에서 실행합니다. `local-floor` 필수, `bounded-floor` 선택 기능입니다. 지원되지 않는 프레임레이트를 요청하지 않고 실패해도 진입을 중단하지 않습니다. 해상도 배율은 `setSession` 전에 적용합니다.

`visibilitychange`, `inputsourceschange`, reference-space `reset`, window blur, pointer lock 변경에서 입력 상태를 정리합니다. 추적 상실은 게임을 일시 정지합니다. 양손이 돌아와도 트리거·점프·슬라이드 버튼을 놓기 전에는 입력이 활성화되지 않습니다.

세션 종료 시 핸들러, refSpace, controller state, spatial UI, rig/camera 설정을 정리합니다. 새 세션에서 새 refSpace로 다시 보정합니다. Three XRManager가 연결한 컨트롤러 객체 2개를 재사용하고 재진입마다 메시를 추가 생성하지 않습니다. 메뉴는 DOM overlay를 요구하지 않아 Quest immersive 화면 안에서도 동작합니다.

## 렌더링 예산과 확장

기본 Quest 2: .85 framebuffer scale, foveation 1, 지원 시 72Hz. 고화질: 1.0 / .65 / 지원 시 90Hz. r170 WebGLRenderer의 두 눈별 렌더 경로이며 **multiview 최적화를 구현한 것은 아닙니다.**

ToonMaterials의 `shaderHook`에서 `nprKey`의 view-space 변환을 `mat3(viewMatrix)*vrWorldKey`로 바꿉니다. 각 눈의 실제 viewMatrix가 광원 좌표를 결정하므로 양안 사이에 명암이 어긋나는 오류를 피합니다. 기존 키트 파일은 고치지 않습니다.

캐릭터 외곽은 용접·평균 법선을 가진 inverted hull로 확장했습니다. 기존 내부 grazing-normal 잉크도 유지합니다. PC는 배경 EdgesGeometry와 1024 태양 그림자를 사용합니다. VR에서는 배경 선·실시간 shadow pass를 끄고 고정 투영 그림자로 바꿉니다. SSR·다중 동적 광원·DOF·motion blur·bloom은 넣지 않습니다. 에너지 부품은 Basic 재질, 폭발은 짧은 불투명 조각입니다. 추가 아트 설계는 `ART_DIRECTION.md`를 참고합니다.

코스는 15m 단위 정적 vertex-color 배치입니다. 렌더 청크는 거리로 숨기지만 전체 충돌체와 40m AI 활성 거리는 유지합니다. 적 종류별 InstancedMesh, 탄·입자·그림자 풀을 재사용합니다. 투명 메시는 주변부 오버레이와 가는 레이 정도로 제한합니다. CanvasTexture는 작은 손목 HUD와 메뉴·간판만 사용하고, HUD 업로드는 최대 10Hz입니다.

부하 누적 시 청크 거리 38m, 입자 48개, foveation 1로 낮춥니다. framebuffer scale을 몰래 세션 중 바꾸거나 적·탄을 소거해 게임 난도를 낮추지 않습니다. 현재 CPU/GPU timer query 측정기나 실기기 자동 품질 인증은 없습니다. FPS 수치는 실기기에서 수집해야 합니다.

## 다음 엔진 업데이트

1. 원본은 그대로 두고 갱신 후보를 이 프로젝트 밖/별도 임시 후보 폴더로 복사합니다.
2. `shared-snapshot.json`과 API 차이를 먼저 비교합니다. 특히 motor.step 인자, Kernel 반환 객체 수명, Actions edge 소비, Projectiles hit payload, ToonMaterials shaderHook을 확인합니다.
3. `engine/`, `nes-toon-kit/`, `vendor/`를 함께 갱신하고 단일 Three 버전을 유지합니다.
4. `npm test`, `npm run qa`, `npm run build`, `npm run qa:release`를 실행합니다. 개발자가 실제 Quest에서도 확인합니다.
5. 통과한 버전의 파일 목록·SHA-256을 새 snapshot으로 기록합니다. 원본 엔진이나 동결 데모에 역으로 덮어쓰지 않습니다.

검사는 현재 좌표·입력·탄도·가드·천장·파동·체크포인트와 XR 수명주기를 겨냥합니다. 모델 미감 변경만 할 때는 물리 수치나 카메라를 건드리지 않아도 됩니다.
