# VR 장보기 시뮬레이션 (Shopping VR) > Unity 6 · XR Interaction Toolkit 기반 1인칭 VR 장보기 게임. 주문서대로 매장에서 상품을 골라 셀프 계산대에서 결제하고, NPC와 대화하며 시식·허기 관리까지 수행한다. --- ## 데모 영상 - 메인 데모(2분): _업로드 예정_ - 하이라이트(30초): _업로드 예정_ - 빌드(.apk, Quest 사이드로드): _업로드 예정_ --- ## 프로젝트 정보 | | | |---|---| | **개발 기간** | _YYYY.MM ~ YYYY.MM_ | | **인원** | 1인 (기획·개발·일부 에셋 통합) | | **플랫폼** | Meta Quest (Android XR / OpenXR), PC VR | | **엔진** | Unity 6000.3.9f1 · URP 17.3 | | **주요 패키지** | XR Interaction Toolkit 3.3, XR Hands 1.7, OpenXR 1.16, Oculus XR 4.5 | --- ## 게임 플로우 1. **GameStartScene** — 시작 화면에서 게임 진입 2. **GameScene (매장)** — 좌측 컨트롤러 Primary 버튼으로 주문서 펼치기 3. **상품 픽업** — XR Direct Interactor로 상품을 잡고 손에 든다 (Hover 하이라이트로 피드백) 4. **셀프 계산대** — 바코드 스캔 영역에 상품을 가져가면 항목이 행으로 추가됨, 합계 자동 갱신 5. **결제** — `PlayerWallet`에서 차감 → 주문서 충족 검사 → Clear / Missing 패널 분기 6. **카트** — 카트 영역에 떨어뜨려 둔 상품은 일정 시간 후 자동으로 카트에 정착(부착)되어 카트와 함께 움직인다. 다시 손으로 집으면 분리. 7. **부가 시스템** — NPC 대화·시식으로 허기 회복, 시간이 지나면 허기가 깎이고 굶주리면 이동 속도 저하 --- ## 핵심 기능 ### 1. 쇼핑 주문 미션 시스템 - `ItemData`(ScriptableObject) — 상품 ID·브랜드·`ItemCategory`(과일/유제품/스낵 등)·`ProductGroup`(브랜드별 구체 상품) 분리. **카테고리는 매대 분류용, 그룹은 미션 매칭용**으로 의도적으로 두 단계로 나눔. - `ShoppingOrderList` — 주문서를 SO로 데이터화. 미션마다 다른 주문서를 에셋만 교체해 재사용. - `PlayerController.ShoppingOrderMissionClearCheck` — 결제 시 구매 항목을 `ProductGroup`으로 집계 후 부족분을 (group, shortage) 튜플 리스트로 반환. 부족분 0이면 클리어. ### 2. 셀프 계산대 (`CheckoutMachine`, `BarcodeScaner`) - `Physics.OverlapBoxNonAlloc`로 스캔 영역 안의 콜라이더를 GC 부담 없이 수집한 뒤, 영역 중심에 가장 가까운 `ItemInstance` 한 개만 스캔. - 결제 행은 `Dictionary`로 동일 상품 묶음·수량 카운트를 O(1)로 처리. - UI 행 추가 시 **`OnEnable` 지연 트릭**: 행을 비활성 상태로 인스턴스화 → `LayoutRebuilder.ForceRebuildLayoutImmediate`로 레이아웃 확정 → 활성화. 활성 직후 첫 프레임에 RectTransform이 0인 채로 OnEnable이 도는 문제를 피한다. ### 3. NPC 대화·립싱크 시스템 - **데이터 그래프**: `DialogGroup` → `DialogNode`(대사·제스처·표정·보이스·선택지) → `DialogChoice` → 다음 노드. 모두 ScriptableObject로 노드 그래프를 자산화. - `DialogPlayer` — Unity 6의 `Awaitable`로 `await PlayNode → await WaitForChoice → 다음 노드` 흐름을 코루틴 없이 비동기 직렬화. 대화 종료 시 초기 제스처/표정 상태를 `CrossFade`로 복원. - **플레이어 향해 회전** — 대화 중 NPC가 카메라 방향으로 부드럽게 회전, 종료 시 원래 회전으로 복귀. - **블렌드셰이프 립싱크 (`LipSync`)** — `AudioSource.GetOutputData`로 RMS amplitude 계산 → 0~1로 매핑 → 입 관련 블렌드셰이프 7종에 가중치 분배. **`LateUpdate`에서 적용**해 같은 프레임에 Animator가 0으로 덮어쓴 값을 다시 씌우는 방식으로 표정 애니메이션과 충돌 없이 공존. ### 4. 플레이어 시스템 - `PlayerHunger` — 시간 경과로 허기 게이지 감소. 0이 되면 `ContinuousMoveProvider.moveSpeed`를 `_starvedMoveSpeed`로 교체, 시식으로 회복 시 원본 속도 복구. UI는 `Action` 이벤트로 게이지 바인딩. - `PlayerWallet` — 결제 시 잔고 차감, 부족 시 `false` 반환해 결제 자체를 막음. - `InputManager` — XR 컨트롤러 버튼 이벤트(`XRLeftControllerPrimaryButton_Event` 등)를 게임 로직 측에서 구독. ### 5. 카트 시스템 (`RideController`, `RideDetectionZone`) VR에서 "물건을 카트에 담는다"는 단순해 보여도 실제로는 네 가지 문제가 동시에 발생한다. 각 문제를 다음과 같이 해결했다. **(1) 플레이어가 카트와 함께 움직이게 만들기 — `ParentConstraint`** - 카트에 `ParentConstraint`를 붙이고 source로 `XROrigin`을 잡음. 결과적으로 **XROrigin(=플레이어)이 카트의 자식처럼 따라다님**. - `ActiveRide()` / `DeactiveRide()`로 constraint 활성/비활성 토글 → 카트에서 내릴 때는 constraint만 끊으면 되고, XROrigin 계층은 건드리지 않음. **(2) 물건이 카트와 같이 안 움직이는 문제 — Reparent + Kinematic** - `Rigidbody` 상태로 바구니에 얹혀 있어도 카트가 움직이면 충돌·관성으로 즉시 튀어나옴. - 정착이 확정되면 `transform.SetParent(_itemRoot)`로 카트 하위에 부착하고 `isKinematic = true`로 전환. 이때부터는 카트의 transform을 그대로 따라가고 물리 시뮬레이션에서 빠짐. **(3) 관성으로 물건이 빠져나오는 문제 — 정착 타이머** - 단순히 "트리거 진입 = 부착"으로 하면 던져 넣자마자 위로 튀는 운동량 때문에 카트 밖으로 다시 튀어나감. 게다가 한 번 부착되면 더 이상 던질 수 없음(움직이는 카트 바깥으로 떨어뜨릴 수 없음). - `OnDetectionStay`에서 매 프레임 검사: - `linearVelocity.magnitude > _settleVelocity`(임계 속도)면 타이머 리셋 — 아직 움직이는 중 - 임계 속도 이하 상태가 `_settleDuration` 동안 **연속으로 유지**되면 부착 확정 - `XRGrabInteractable.isSelected`(현재 손에 잡혀있음)면 타이머 무효화 — 잡고 있는 동안엔 절대 부착되지 않음 - `_settleTimer`는 `Dictionary`로 아이템별 타이머를 독립 관리. **(4) 물건 위에 물건을 쌓는 문제** - 위 정착 타이머는 **각 Rigidbody별로** 독립적으로 흐름. 아래 물건이 먼저 정착해 kinematic이 되면, 그 위에 떨어뜨린 물건은 단단한 받침대 위에서 속도가 0에 수렴 → 자기 차례에 정착 → 다음 물건의 받침대가 됨. - 트리거 영역(`RideDetectionZone`)을 카트 바구니보다 충분히 높게 잡아 쌓인 물건도 검사 대상에 포함. **(5) 카트에서 다시 꺼낼 때의 함정 — `retainTransformParent` & isKinematic 복원 덮어쓰기** - `XRGrabInteractable`은 **잡힐 때 부모/kinematic 상태를 스냅샷**해 두고, 놓을 때 그 상태로 되돌린다. 카트에서 부착될 때 부모=ItemRoot, kinematic=true로 잡혔으니, 손으로 꺼냈다가 어딘가 놔도 **다시 ItemRoot 자식으로 + kinematic 상태로** 복원되어 공중에 박제되는 버그. - 두 단계로 차단: - 부착 시 `grab.retainTransformParent = false` — 부모 복원 비활성화. - 꺼낼 때 `selectEntered` → 즉시 부모 해제, `selectExited`에서 `isKinematic = false`를 다시 강제로 덮어쓰기. ``` 물건 던져넣기 → 트리거 진입 → [속도 < 임계 && 잡혀있지 않음] 0.3s 유지 → SetParent(ItemRoot) + isKinematic=true + retainTransformParent=false → 카트 이동에 종속 손으로 다시 잡음 → SetParent(null) → 일반 물리로 복귀 → 놓을 때 isKinematic=false 강제 복원 ``` ### 6. 씬 전환 라이프사이클 - `ITransScenePossible` 인터페이스 — 씬 로드 직후 `OnSceneLoaded()`를 일괄 호출해 **씬을 가로지르는 매니저(GameManager 등)가 새 씬의 매니저(GameSceneUIManager)와 다시 결선**되도록 함. 싱글톤이 죽지 않은 채 새 씬의 UI 참조만 갱신. --- ## 아키텍처 ``` Managers (DontDestroyOnLoad, 싱글톤) ├─ GameManager 전역 상태·씬 매니저 결선 ├─ InputManager XR 컨트롤러 입력 이벤트 허브 ├─ SoundManager BGM / SE └─ SceneLoadManager ITransScenePossible 알림 디스패치 │ ▼ Scene-local (GameScene) ├─ GameSceneUIManager HUD·패널 컨트롤 ├─ PlayerController 주문서 토글, 결제 진입점 ├─ PlayerWallet / PlayerHunger ├─ RideController + RideDetectionZone 카트 (ParentConstraint로 플레이어 종속) └─ CheckoutMachine ← BarcodeScaner ← ItemInstance(ItemData SO) │ ▼ Data (ScriptableObject) ├─ ItemData / ShoppingOrderList / ShoppingOrderEntry ├─ DialogGroup / DialogNode / DialogChoice / VoiceClip └─ CharacterData / ExpressionData / GestureData / BGMClip ``` --- ## 폴더 구조 ``` Assets/ ├─ 01_Scenes/MyProject/ GameStartScene, GameScene ├─ 02_Scripts/ 자체 구현 코드 (네임스페이스 VRShopping.*) │ ├─ Managers/ GameManager, InputManager, SoundManager, SceneLoadManager... │ ├─ Player/ PlayerController, PlayerHunger, PlayerWallet, RideController │ ├─ Shopping/ BarcodeScaner, CheckoutMachine │ ├─ Communication/ Dialog/, Voice/ (LipSync, DialogPlayer, CharacterVoiceObject) │ ├─ Item/ ItemData, ItemInstance, TastingSample │ ├─ Interact/ ItemHoverHighlight, ItemInfoOnGrab, DialogInteractable │ ├─ Data/ ScriptableObject 정의 │ └─ UI/ HUD·패널 (HungerHud, GameTimerHud, ChoiceHud, ClearPanel...) ├─ 03_Models/ ~ 10_Audio/ 아트·오디오 에셋 └─ 99_Settings/ XR / URP / Input 설정 ``` --- ## 사용한 외부 에셋 | 분류 | 에셋 | 용도 | |---|---|---| | XR | XR Interaction Toolkit, XR Hands, OpenXR, Oculus XR | 컨트롤러·핸드 인터랙션 기반 | | XR 확장 | MikeNspired XRI Starter Kit | Climbing, DistanceGrab, HandPoser | | 캐릭터 | BoZo Modular Anime Characters | NPC 모델·블렌드셰이프 | | 의상 시뮬 | Magica Cloth 2 | 옷·머리카락 물리 | | 셰이딩 | RealToon, Umbra Soft Shadows, BadDog AreaLight | 툰 셰이딩·소프트 섀도우 | | 인터랙션 피드백 | HighlightPlus, Outline Plus | Hover/Grab 외곽선 | | VFX | CartoonVFX9X | 스캔·결제 이펙트 | > 자체 구현은 `Assets/02_Scripts/` (네임스페이스 `VRShopping.*`). --- ## 빌드 / 실행 ### 요구 사항 - Unity **6000.3.9f1** - (Quest 빌드) Android Build Support, OpenXR Loader: Meta Quest ### 실행 1. 저장소 클론 후 Unity Hub에서 프로젝트 열기 2. `Assets/01_Scenes/MyProject/GameStartScene.unity` 열기 3. PC: Quest Link / Air Link 연결 후 Play 4. Android 빌드: Build Settings → Android → Build, Quest에 사이드로드 --- ## 트러블슈팅 / 학습 포인트 ### 1. 립싱크와 표정 애니메이션 충돌 - **문제**: `Animator`가 표정 레이어에서 매 프레임 블렌드셰이프 가중치를 0으로 덮어써 립싱크가 동작하지 않음. - **해결**: 립싱크를 `LateUpdate`에서 적용. `Animator`는 `Update` 이후 동작이지만 같은 프레임의 `LateUpdate`에서 다시 가중치를 씌우는 순서로 충돌을 회피. ### 2. UI 행 추가 직후 RectTransform 0 문제 - **문제**: `Instantiate` 후 활성 상태에서 바로 `OnEnable`이 돌면 부모 레이아웃이 아직 갱신 전이라 사이즈 0으로 잡힘. - **해결**: 비활성 상태로 생성 → `LayoutRebuilder.ForceRebuildLayoutImmediate` → 활성. 첫 프레임 깜빡임 제거. ### 3. 씬 전환 시 매니저 참조 끊김 - **문제**: `DontDestroyOnLoad` 매니저가 새 씬의 UI 매니저를 못 찾음. - **해결**: `ITransScenePossible` 인터페이스로 통일 → `SceneLoadManager`가 씬 로드 콜백에서 일괄 `OnSceneLoaded()` 호출 → 각자 필요한 씬-로컬 참조를 다시 잡음. ### 4. 스캔 영역 다중 상품 처리 - **문제**: 스캔 박스 안에 여러 상품이 들어오면 한 번에 다 결제됨. - **해결**: `OverlapBoxNonAlloc` 결과 중 박스 중심에 **가장 가까운 한 개**만 스캔 대상으로 선택. ### 5. 카트에 담은 물건이 카트와 따로 노는 문제 - **문제**: VR 카트가 움직이면 안에 든 물건이 충돌·관성으로 튀어나옴. 그렇다고 진입 즉시 부착하면 던져 넣을 때 운동량으로 다시 빠져나감. - **해결**: **속도 임계값(`_settleVelocity`) 이하 상태가 `_settleDuration` 동안 연속 유지**되면 카트 자식으로 reparent + `isKinematic = true`. 잡혀있는 동안엔 타이머 자체를 무효화. (자세한 흐름은 [카트 시스템 섹션](#5-카트-시스템-ridecontroller-ridedetectionzone) 참고) ### 6. XRGrabInteractable의 상태 스냅샷·복원이 카트 부착을 깨뜨림 - **문제**: `XRGrabInteractable`은 잡힐 때 부모/kinematic을 스냅샷하고 놓을 때 복원함. 카트에 kinematic 상태로 부착된 물건을 잡았다 놓으면, **놓는 순간 다시 카트 자식 + kinematic으로 복원되어 공중에 박제**됨. - **해결**: 부착 시 `retainTransformParent = false`로 부모 복원 차단 + `selectExited`에서 `isKinematic = false`를 직접 덮어씀. --- ## 향후 개선 - [ ] 카트(`RideController`)에 담은 아이템 별도 인벤토리화 - [ ] 대화 노드 진행 입력을 VR 컨트롤러 버튼으로 (현재 임시 1초 대기) - [ ] PlayerController의 임시 bool 플래그 → 상태 머신 전환 - [ ] 주문서 종류 다양화 (난이도별 SO 추가) --- ## 라이선스 자체 구현 코드(`Assets/02_Scripts/`)에 대해서만 권리 주장. 외부 에셋은 각 에셋 라이선스를 따른다.