2026-06-19 UI, UI로직

Assets/My project/Inventory/Scripts/README_KR.md

@@ -0,0 +1,359 @@
+# 인벤토리 UI 스크립트 설명서
+
+이 패키지는 Unity 인벤토리 HUD를 만들기 위한 스크립트 세트입니다.  
+아이템 개수 관리와 UI 표시를 분리해서, 낚시/리듬게임/미로 같은 다른 시스템과 연결하기 쉽게 만든 구조입니다.
+
+## 포함 파일
+
+| 파일 | 역할 |
+|---|---|
+| `InventoryItemType.cs` | 아이템 종류 enum 정의 |
+| `InventoryManager.cs` | 실제 아이템 개수 관리 |
+| `InventoryUI.cs` | 전체 인벤토리 UI 갱신 |
+| `InventorySlotUI.cs` | 슬롯 하나의 아이콘/개수/NEW 표시 관리 |
+| `ItemReward.cs` | 미니게임 성공, 이벤트 완료 시 아이템 지급 |
+| `ItemPickup.cs` | 월드 오브젝트를 직접 주워서 아이템 획득 |
+| `InventoryTooltipUI.cs` | 아이템 설명 툴팁 표시 |
+
+필수로 먼저 쓰는 파일은 아래 5개입니다.
+
+```text
+InventoryItemType.cs
+InventoryManager.cs
+InventoryUI.cs
+InventorySlotUI.cs
+ItemReward.cs
+```
+
+선택 파일은 아래 2개입니다.
+
+```text
+ItemPickup.cs
+InventoryTooltipUI.cs
+```
+
+---
+
+## 권장 폴더 구조
+
+```text
+Assets
+└── My project
+    └── Inventory
+        ├── Scripts
+        ├── Sprites
+        └── Prefabs
+```
+
+스크립트는 여기에 넣습니다.
+
+```text
+Assets/My project/Inventory/Scripts
+```
+
+---
+
+## Unity Hierarchy 예시
+
+```text
+InventorySystem
+└── InventoryManager
+
+InventoryCanvas
+└── InventoryMiniUI
+    ├── InventoryUI
+    ├── InventoryBG
+    ├── TitleText
+    ├── ItemSlotRoot
+    │   ├── FishSlot
+    │   │   ├── SlotBG
+    │   │   ├── ItemIcon
+    │   │   ├── CountText
+    │   │   └── NewBadge
+    │   ├── CompassSlot
+    │   ├── TrashSlot
+    │   └── BottleSlot
+    └── TooltipText 또는 TooltipPanel
+```
+
+---
+
+## 1. InventorySystem 만들기
+
+Hierarchy에서 빈 오브젝트를 만듭니다.
+
+```text
+Create Empty → InventorySystem
+```
+
+`InventorySystem`에 붙일 스크립트:
+
+```text
+InventoryManager.cs
+```
+
+Inspector 설정:
+
+```text
+Initial Items: 테스트용 시작 아이템을 넣고 싶으면 사용
+Show Debug Log: 체크
+```
+
+예시:
+
+```text
+Fish 1
+OldCompass 0
+Trash 0
+Bottle 0
+```
+
+---
+
+## 2. InventoryMiniUI에 InventoryUI 붙이기
+
+`InventoryCanvas > InventoryMiniUI` 오브젝트에 붙입니다.
+
+```text
+InventoryUI.cs
+```
+
+Inspector 연결:
+
+```text
+Inventory Manager → InventorySystem
+Inventory Panel → InventoryMiniUI
+Slots Size → 슬롯 개수만큼 설정
+```
+
+예시:
+
+```text
+Slots Size: 4
+Element 0 → FishSlot
+Element 1 → CompassSlot
+Element 2 → TrashSlot
+Element 3 → BottleSlot
+```
+
+---
+
+## 3. 각 슬롯에 InventorySlotUI 붙이기
+
+각 슬롯 오브젝트에 붙입니다.
+
+```text
+FishSlot → InventorySlotUI.cs
+CompassSlot → InventorySlotUI.cs
+TrashSlot → InventorySlotUI.cs
+BottleSlot → InventorySlotUI.cs
+```
+
+각 슬롯의 Inspector 연결:
+
+```text
+Item Type → Fish / OldCompass / Trash / Bottle
+Slot Background → SlotBG
+Item Icon → ItemIcon
+Count Text → CountText
+New Badge → NewBadge
+Canvas Group → 슬롯 오브젝트에 CanvasGroup이 있으면 연결
+Tooltip UI → InventoryTooltipUI를 쓸 경우 연결
+```
+
+각 슬롯의 아이템 타입 예시:
+
+```text
+FishSlot: Fish
+CompassSlot: OldCompass
+TrashSlot: Trash
+BottleSlot: Bottle
+```
+
+---
+
+## 4. 테스트 버튼으로 확인하기
+
+임시 UI Button을 만들고 Button OnClick에 아래 함수를 연결합니다.
+
+```text
+InventorySystem → InventoryManager.AddItem(InventoryItemType, int)
+```
+
+Unity 이벤트에서 enum+int가 바로 안 보일 수 있으므로, 테스트는 `ItemReward`를 쓰는 방식이 더 쉽습니다.
+
+테스트 방법:
+
+1. 빈 오브젝트 `TestFishReward` 생성
+2. `ItemReward.cs` 붙이기
+3. 설정:
+
+```text
+Inventory Manager → InventorySystem
+Reward Item Type → Fish
+Reward Amount → 1
+Give Only Once → 해제
+```
+
+4. 테스트 버튼 OnClick에 연결:
+
+```text
+TestFishReward → ItemReward.GiveReward()
+```
+
+Play 후 버튼을 누르면 FishSlot의 CountText가 `x1`, `x2`로 증가해야 합니다.
+
+---
+
+## 5. 미니게임 성공 보상 연결
+
+예: 낚시 성공 시 생선 지급
+
+`FishingGameSystem`에 `ItemReward.cs`를 붙입니다.
+
+```text
+Reward Item Type → Fish
+Reward Amount → 1
+Give Only Once → 필요에 따라 체크
+```
+
+낚시 게임 매니저의 성공 이벤트에 연결:
+
+```text
+On Fishing Success
+→ FishingGameSystem
+→ ItemReward.GiveReward()
+```
+
+예: 리듬게임 시작 전 생선 보유 확인은 별도 게임 매니저에서 처리합니다.
+
+```csharp
+if (inventoryManager.HasItem(InventoryItemType.Fish))
+{
+    rhythmGameManager.StartGameWithFishBonus();
+}
+```
+
+---
+
+## 6. ItemPickup 사용법
+
+월드에 떠 있는 아이템을 직접 줍게 만들 때 사용합니다.
+
+아이템 오브젝트에 필요한 것:
+
+```text
+Collider
+Is Trigger 체크
+ItemPickup.cs
+```
+
+Inspector 설정:
+
+```text
+Inventory Manager → InventorySystem
+Item Type → Fish / OldCompass / Trash / Bottle
+Amount → 1
+Player Tag → Player
+Destroy After Pickup → 체크
+```
+
+플레이어 오브젝트에는 `Player` 태그가 있어야 합니다.
+
+---
+
+## 7. Tooltip 사용법
+
+툴팁을 쓰려면 UI에 이런 구조를 만듭니다.
+
+```text
+InventoryMiniUI
+└── TooltipPanel
+    ├── TooltipTitleText
+    ├── TooltipDescriptionText
+    └── TooltipCountText
+```
+
+`TooltipPanel` 또는 별도 오브젝트에 붙입니다.
+
+```text
+InventoryTooltipUI.cs
+```
+
+Inspector 연결:
+
+```text
+Tooltip Panel → TooltipPanel
+Title Text → TooltipTitleText
+Description Text → TooltipDescriptionText
+Count Text → TooltipCountText
+```
+
+그리고 각 `InventorySlotUI`의 `Tooltip UI` 슬롯에 이 `InventoryTooltipUI`를 연결합니다.
+
+---
+
+## 초기 상태 추천
+
+```text
+FishSlot CountText: x0
+CompassSlot CountText: x0
+TrashSlot CountText: x0
+BottleSlot CountText: x0
+NewBadge 전부 비활성화
+TooltipPanel 비활성화
+```
+
+---
+
+## 자주 생기는 문제
+
+### 슬롯 숫자가 안 바뀜
+
+확인할 것:
+
+```text
+InventoryUI의 Inventory Manager가 연결되어 있는가?
+InventoryUI의 Slots 배열에 각 슬롯이 들어가 있는가?
+각 슬롯에 InventorySlotUI가 붙어 있는가?
+각 InventorySlotUI의 Item Type이 올바른가?
+```
+
+### NEW 표시가 계속 켜져 있음
+
+`NewBadge` 오브젝트를 처음에는 비활성화하세요.  
+`InventorySlotUI`가 아이템 증가 시 자동으로 잠깐 켰다가 끕니다.
+
+### 0개 아이템이 너무 밝게 보임
+
+각 슬롯에 `CanvasGroup`을 추가하고 `InventorySlotUI`의 `Canvas Group`에 연결하세요.  
+`Dim When Zero`가 켜져 있으면 0개일 때 흐리게 보입니다.
+
+### 아이템 줍기가 안 됨
+
+확인할 것:
+
+```text
+아이템 오브젝트에 Collider가 있는가?
+Is Trigger가 켜져 있는가?
+플레이어 오브젝트 태그가 Player인가?
+ItemPickup의 Inventory Manager가 연결되어 있는가?
+```
+
+---
+
+## 최종 작업 순서
+
+```text
+1. 스크립트들을 Inventory/Scripts 폴더에 넣기
+2. InventorySystem 오브젝트 만들기
+3. InventoryManager 붙이기
+4. InventoryMiniUI 만들기
+5. InventoryUI 붙이기
+6. FishSlot, CompassSlot, TrashSlot, BottleSlot 만들기
+7. 각 슬롯에 InventorySlotUI 붙이기
+8. InventoryUI의 Slots 배열에 슬롯 연결
+9. ItemReward로 테스트 보상 만들기
+10. Play 후 아이템 개수 증가 확인
+11. 낚시/리듬/미로 이벤트와 연결
+```