192 lines
11 KiB
Markdown
192 lines
11 KiB
Markdown
# VR 장보기 시뮬레이션 (Shopping VR)
|
|
|
|
> Unity 6 · XR Interaction Toolkit 기반 1인칭 VR 장보기 게임. 주문서대로 매장에서 상품을 골라 셀프 계산대에서 결제하고, NPC와 대화하며 시식·허기 관리까지 수행한다.
|
|
|
|
<!-- 헤더용 GIF/이미지 자리 (TODO: 매장 입장 → 주문서 펼치기 → 스캔 → 결제 4컷 GIF) -->
|
|
<!--  -->
|
|
|
|
---
|
|
|
|
## 데모 영상
|
|
|
|
<!-- TODO: 유튜브/구글드라이브 링크 또는 GIF -->
|
|
- 메인 데모(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<string, CheckoutProductionRow>`로 동일 상품 묶음·수량 카운트를 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<float, float>` 이벤트로 게이지 바인딩.
|
|
- `PlayerWallet` — 결제 시 잔고 차감, 부족 시 `false` 반환해 결제 자체를 막음.
|
|
- `InputManager` — XR 컨트롤러 버튼 이벤트(`XRLeftControllerPrimaryButton_Event` 등)를 게임 로직 측에서 구독.
|
|
|
|
### 5. 카트 시스템
|
|
<img src="/readme/cart2.png" width="300"><br>
|
|
- 해당 영역에 아이템이 들어오면, 아이템의 움직임이 없어질 때(혹은 0.3초가 지났을 때) 물리영향을 끄고 카트의 움직임을 `ParentConstraint` 로 추적한다.
|
|
- 이렇게 해야 카트와 아이템이 따로 움직이지 않고, 물건 위에 물건이 쌓였을 때의 버그가 없었다.
|
|
|
|
### 6. 씬 전환 커스텀 사이클
|
|
- `ITransScenePossible` 인터페이스 — **씬을 가로지르는 매니저(SceneLoadManager)**가 새 씬 로드 직후 씬 내의 모든 `ITransScenePossible`를 전부 찾아 `OnSceneLoaded()`를 호출함.
|
|
|
|
---
|
|
|
|
## 아키텍처
|
|
|
|
```
|
|
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/`)에 대해서만 권리 주장. 외부 에셋은 각 에셋 라이선스를 따른다.
|