2026-06-19 UI, UI로직

Assets/My project/Memory Scripts/UI/README_KR.md

@@ -0,0 +1,268 @@
+# 기억의 조각 진행도 UI 스크립트 설명서
+
+이 패키지는 `기억의 조각 0/5 ~ 5/5` 진행도를 UI에 표시하고, 리듬게임/낚시/미니게임 성공 시 기억의 조각을 지급하기 위한 스크립트 세트입니다.
+
+## 포함 파일
+
+```text
+MemoryProgressUI.cs
+MemoryProgressManager.cs
+MemoryPieceReward.cs
+MemoryPiecePickup.cs
+MemoryProgressPopupUI.cs
+```
+
+## 1. Unity에 넣을 위치
+
+추천 경로:
+
+```text
+Assets/My project/MemoryProgress/Scripts
+```
+
+위 폴더를 만들고 `.cs` 파일들을 넣으세요.
+
+---
+
+## 2. 필요한 UI Hierarchy
+
+기억의 조각 UI는 아래 구조를 추천합니다.
+
+```text
+MemoryProgressCanvas
+└── MemoryProgressUI
+    ├── ProgressBG
+    ├── TitleText
+    ├── PieceSlotRoot
+    │   ├── PieceSlot_01
+    │   │   ├── EmptyIcon
+    │   │   ├── FilledIcon
+    │   │   └── GlowIcon
+    │   ├── PieceSlot_02
+    │   ├── PieceSlot_03
+    │   ├── PieceSlot_04
+    │   └── PieceSlot_05
+    └── CountText
+```
+
+중요:
+
+- `EmptyIcon`은 항상 켜둡니다.
+- `FilledIcon`은 처음에 꺼둡니다.
+- `GlowIcon`은 선택 사항입니다. 처음에는 꺼둡니다.
+- `CountText`는 TextMeshProUGUI로 만듭니다.
+
+---
+
+## 3. MemoryProgressUI.cs 붙이는 곳
+
+붙일 오브젝트:
+
+```text
+MemoryProgressUI
+```
+
+Inspector 연결:
+
+```text
+Title Text  → TitleText
+Count Text  → CountText
+Filled Icons 배열
+  Element 0 → PieceSlot_01/FilledIcon
+  Element 1 → PieceSlot_02/FilledIcon
+  Element 2 → PieceSlot_03/FilledIcon
+  Element 3 → PieceSlot_04/FilledIcon
+  Element 4 → PieceSlot_05/FilledIcon
+
+Glow Icons 배열 선택
+  Element 0 → PieceSlot_01/GlowIcon
+  Element 1 → PieceSlot_02/GlowIcon
+  Element 2 → PieceSlot_03/GlowIcon
+  Element 3 → PieceSlot_04/GlowIcon
+  Element 4 → PieceSlot_05/GlowIcon
+```
+
+설정 추천:
+
+```text
+Max Pieces: 5
+Title: 기억의 조각
+Show Glow Only When Completed: true
+```
+
+---
+
+## 4. MemoryProgressManager.cs 붙이는 곳
+
+빈 오브젝트를 만듭니다.
+
+```text
+MemoryProgressSystem
+```
+
+여기에 붙입니다.
+
+```text
+MemoryProgressManager.cs
+```
+
+Inspector 연결:
+
+```text
+Memory Progress UIs 배열
+  Element 0 → MemoryProgressUI 오브젝트
+
+Required Pieces: 5
+Current Pieces: 0
+```
+
+여러 UI에 동시에 표시하고 싶다면 배열에 여러 개를 넣으면 됩니다.
+예: HUD용 작은 진행도 UI, 방 선택 화면용 큰 진행도 UI.
+
+---
+
+## 5. MemoryPieceReward.cs 붙이는 곳
+
+미니게임 오브젝트에 붙입니다.
+
+예:
+
+```text
+RhythmGameSystem
+FishingGameSystem
+BlackjackGameSystem
+MazeGameSystem
+```
+
+Inspector 연결:
+
+```text
+Memory Progress Manager → MemoryProgressSystem의 MemoryProgressManager
+Reward Amount → 1
+Give Only Once → true
+Auto Find Manager → true 또는 false
+```
+
+### 리듬게임 성공 시 연결 예시
+
+`RhythmGameManager` 컴포넌트의 이벤트에서:
+
+```text
+On Game Success
++ 버튼 클릭
+RhythmGameSystem 오브젝트 드래그
+MemoryPieceReward → GiveReward()
+```
+
+이렇게 하면 리듬게임 성공 시 기억의 조각이 1개 증가합니다.
+
+---
+
+## 6. MemoryPiecePickup.cs 선택 사용
+
+기억의 조각을 실제 월드 오브젝트로 만들어 플레이어가 직접 획득하게 할 때 사용합니다.
+
+붙일 오브젝트:
+
+```text
+MemoryPiece_Object
+```
+
+필요 조건:
+
+```text
+Collider
+Is Trigger: true
+Player 오브젝트 Tag: Player
+```
+
+또는 XR Grab/Event에서 `PickUp()`을 직접 호출해도 됩니다.
+
+---
+
+## 7. MemoryProgressPopupUI.cs 선택 사용
+
+기억의 조각을 얻었을 때 잠깐 뜨는 알림입니다.
+
+추천 구조:
+
+```text
+MemoryRewardPopup
+├── PopupPanel
+│   ├── PopupTitleText
+│   └── PopupCountText
+```
+
+붙일 곳:
+
+```text
+MemoryRewardPopup
+```
+
+Inspector 연결:
+
+```text
+Popup Panel → PopupPanel
+Title Text → PopupTitleText
+Count Text → PopupCountText
+Message → 기억의 조각을 얻었다!
+Show Time → 1.5
+```
+
+`MemoryProgressManager`의 `On Progress Changed` 이벤트에 연결:
+
+```text
+On Progress Changed
++ 버튼 클릭
+MemoryRewardPopup 오브젝트 드래그
+MemoryProgressPopupUI → ShowPopup(int, int)
+```
+
+---
+
+## 8. 테스트 방법
+
+1. `MemoryProgressSystem`에 `MemoryProgressManager`를 붙입니다.
+2. `MemoryProgressUI`에 `MemoryProgressUI.cs`를 붙이고 FilledIcon 5개를 연결합니다.
+3. `MemoryProgressManager`의 `Memory Progress UIs` 배열에 해당 UI를 넣습니다.
+4. 임시 버튼을 만들고 OnClick에 아래 함수를 연결합니다.
+
+```text
+MemoryProgressManager → AddMemoryPiece()
+```
+
+5. Play 후 버튼을 누르면 UI가 `1 / 5`, `2 / 5`로 증가해야 합니다.
+
+---
+
+## 9. 리듬게임과 연결하는 방법
+
+`RhythmGameSystem`에 `MemoryPieceReward.cs`를 추가합니다.
+
+연결:
+
+```text
+Memory Progress Manager → MemoryProgressSystem
+```
+
+`RhythmGameManager`의 `On Game Success` 이벤트에:
+
+```text
+RhythmGameSystem → MemoryPieceReward.GiveReward()
+```
+
+이렇게 연결하면 리듬게임 성공 시 기억의 조각을 지급합니다.
+
+---
+
+## 10. 최종 체크리스트
+
+```text
+MemoryProgressUI에 CountText가 연결되어 있는가?
+FilledIcon 5개가 배열에 순서대로 들어갔는가?
+MemoryProgressManager에 MemoryProgressUI가 연결되어 있는가?
+MemoryPieceReward에 MemoryProgressManager가 연결되어 있는가?
+미니게임 성공 이벤트에 MemoryPieceReward.GiveReward()가 연결되어 있는가?
+```
+
+이 구성이 완료되면 기억의 조각 진행도 UI는 다른 미니게임과 방 선택 UI에서도 재사용할 수 있습니다.