2026-06-19 UI, UI로직

2026-06-19 14:27:40 +09:00
parent b751a9ed66
commit b1e85a5b89
549 changed files with 18058 additions and 20 deletions
--- a/project/TruthFountain/Scripts/README_KR.md
+++ b/project/TruthFountain/Scripts/README_KR.md
@@ -0,0 +1,514 @@
+# 진실의 샘 UI 스크립트 사용 설명서
+
+이 폴더는 `진실의 샘 UI`를 만들기 위한 Unity C# 스크립트 세트입니다.
+
+진실의 샘은 질문에 답하면 선택지의 `Lie Amount`에 따라 코 게이지가 올라가고, 최종적으로 성공/실패를 판정하는 구조입니다.
+
+---
+
+## 1. 포함된 스크립트
+
+| 파일 | 역할 | 오브젝트에 붙이는가 |
+|---|---|---|
+| `TruthChoiceData.cs` | 선택지 하나의 데이터 | 붙이지 않음 |
+| `TruthQuestionData.cs` | 질문 하나의 데이터 | 붙이지 않음 |
+| `TruthFountainData.cs` | 전체 질문 묶음 ScriptableObject | 붙이지 않음, asset 생성용 |
+| `TruthChoiceButtonUI.cs` | 선택지 버튼 하나 표시/클릭 처리 | 선택지 버튼 3개 각각 |
+| `TruthFountainUI.cs` | 질문, 선택지, 코 게이지, 결과창 표시 | `TruthFountainUI` 오브젝트 |
+| `TruthFountainGameManager.cs` | 게임 진행, 점수 계산, 성공/실패 판정 | `TruthFountainSystem` |
+| `TruthFountainReward.cs` | 성공 보상 지급 | `TruthFountainSystem` |
+| `TruthFountainOpenClose.cs` | UI 열기/닫기, VR 카메라 앞 배치 | `TruthFountainUI` 또는 별도 시스템 오브젝트 |
+
+---
+
+## 2. Unity 폴더 위치
+
+추천 폴더 구조입니다.
+
+```text
+Assets
+└── My project
+    └── TruthFountain
+        ├── Data
+        ├── Prefabs
+        ├── Scripts
+        └── Sprites
+```
+
+스크립트는 여기에 넣으세요.
+
+```text
+Assets/My project/TruthFountain/Scripts
+```
+
+데이터 asset은 여기에 만드는 것을 추천합니다.
+
+```text
+Assets/My project/TruthFountain/Data
+```
+
+---
+
+## 3. 권장 Hierarchy
+
+```text
+TruthFountainCanvas
+└── TruthFountainUI
+    ├── TruthFountainUI.cs
+    ├── TruthFountainOpenClose.cs
+    ├── Background
+    ├── TitleText
+    ├── QuestionPanel
+    │   ├── QuestionBG
+    │   ├── QuestionText
+    │   └── QuestionHintText
+    ├── ChoiceRoot
+    │   ├── ChoiceButton_01
+    │   │   └── TruthChoiceButtonUI.cs
+    │   ├── ChoiceButton_02
+    │   │   └── TruthChoiceButtonUI.cs
+    │   └── ChoiceButton_03
+    │       └── TruthChoiceButtonUI.cs
+    ├── NoseGaugePanel
+    │   ├── NoseGaugeBG
+    │   ├── NoseGaugeFill
+    │   ├── NoseIcon
+    │   └── NoseValueText
+    ├── ProgressText
+    ├── ResultText
+    ├── FinalResultPanel
+    │   ├── FinalResultBG
+    │   ├── FinalTitleText
+    │   ├── FinalDescriptionText
+    │   └── ConfirmButton
+    │       └── ConfirmButtonText
+    └── CloseButton
+        └── CloseText
+
+TruthFountainSystem
+├── TruthFountainGameManager.cs
+└── TruthFountainReward.cs
+```
+
+---
+
+## 4. TruthFountainData asset 만들기
+
+Project 창에서 우클릭합니다.
+
+```text
+Create
+→ Adventure
+→ Truth Fountain
+→ Truth Fountain Data
+```
+
+파일 이름 예시:
+
+```text
+TruthFountainData_Default
+```
+
+설정 예시:
+
+```text
+Title: 진실의 샘
+Max Lie Score: 3
+Fail Immediately At Max Lie Score: 체크
+Result Delay: 1
+Success Title: 진실의 샘이 빛납니다
+Success Description: 당신의 진심이 샘에 닿았습니다. 기억의 조각을 획득했습니다.
+Fail Title: 코가 너무 길어졌습니다
+Fail Description: 샘이 당신의 대답을 믿지 못했습니다. 다시 도전해보세요.
+```
+
+질문은 `Questions` 배열에 추가합니다.
+
+---
+
+## 5. 질문 데이터 입력 예시
+
+### 질문 1
+
+```text
+Question Text:
+친구를 돕기 위해 거짓말을 해도 될까?
+
+Hint Text:
+당신의 선택에 따라 코가 반응합니다.
+
+Choice 1:
+Choice Text: 솔직하게 말한다
+Lie Amount: 0
+Result Message: 샘의 물결이 맑게 빛납니다.
+
+Choice 2:
+Choice Text: 좋은 의도라면 거짓말한다
+Lie Amount: 1
+Result Message: 피노키오의 코가 조금 길어졌습니다.
+```
+
+### 질문 2
+
+```text
+Question Text:
+위험을 피하려고 약속을 어겨도 될까?
+
+Choice 1:
+Choice Text: 약속을 지킨다
+Lie Amount: 0
+Result Message: 샘이 조용히 빛납니다.
+
+Choice 2:
+Choice Text: 아무 말 없이 도망친다
+Lie Amount: 1
+Result Message: 코끝이 불편하게 간질거립니다.
+```
+
+### 질문 3
+
+```text
+Question Text:
+보상을 얻기 위해 모르는 척해도 될까?
+
+Choice 1:
+Choice Text: 사실을 말한다
+Lie Amount: 0
+Result Message: 맑은 물방울이 떠오릅니다.
+
+Choice 2:
+Choice Text: 모르는 척한다
+Lie Amount: 1
+Result Message: 샘이 잠시 어두워집니다.
+```
+
+### 질문 4
+
+```text
+Question Text:
+실수를 숨기면 모두가 편해질까?
+
+Choice 1:
+Choice Text: 실수를 인정한다
+Lie Amount: 0
+Result Message: 물결이 부드럽게 퍼집니다.
+
+Choice 2:
+Choice Text: 아무도 모르게 숨긴다
+Lie Amount: 1
+Result Message: 코가 길어지는 느낌이 듭니다.
+```
+
+### 질문 5
+
+```text
+Question Text:
+진실이 아파도 말해야 할까?
+
+Choice 1:
+Choice Text: 조심스럽게 진실을 말한다
+Lie Amount: 0
+Result Message: 샘이 밝게 빛납니다.
+
+Choice 2:
+Choice Text: 상처 주지 않기 위해 숨긴다
+Lie Amount: 1
+Result Message: 샘의 빛이 흔들립니다.
+```
+
+---
+
+## 6. `TruthChoiceButtonUI.cs` 붙이기
+
+선택지 버튼 3개에 각각 붙입니다.
+
+```text
+ChoiceButton_01 → TruthChoiceButtonUI
+ChoiceButton_02 → TruthChoiceButtonUI
+ChoiceButton_03 → TruthChoiceButtonUI
+```
+
+각 버튼에서 연결할 것:
+
+```text
+Button → 자기 자신의 Button 컴포넌트
+Background Image → 자기 자신의 Image 컴포넌트
+Choice Text → ChoiceText
+```
+
+Sprite가 아직 없다면 아래는 비워도 됩니다.
+
+```text
+Normal Sprite
+Selected Sprite
+Truth Sprite
+Lie Sprite
+```
+
+Sprite가 없으면 색상으로 버튼 상태가 표시됩니다.
+
+---
+
+## 7. `TruthFountainUI.cs` 붙이기
+
+붙일 위치:
+
+```text
+TruthFountainCanvas
+└── TruthFountainUI
+    └── TruthFountainUI.cs
+```
+
+Inspector 연결:
+
+```text
+UI Root → TruthFountainUI
+Title Text → TitleText
+Question Text → QuestionPanel / QuestionText
+Question Hint Text → QuestionPanel / QuestionHintText
+Progress Text → ProgressText
+Result Text → ResultText
+
+Choice Buttons Size: 3
+Element 0 → ChoiceButton_01의 TruthChoiceButtonUI
+Element 1 → ChoiceButton_02의 TruthChoiceButtonUI
+Element 2 → ChoiceButton_03의 TruthChoiceButtonUI
+
+Nose Gauge Fill → NoseGaugePanel / NoseGaugeFill
+Nose Value Text → NoseGaugePanel / NoseValueText
+
+Final Result Panel → FinalResultPanel
+Final Title Text → FinalResultPanel / FinalTitleText
+Final Description Text → FinalResultPanel / FinalDescriptionText
+Confirm Button → FinalResultPanel / ConfirmButton
+```
+
+`NoseGaugeFill`의 Image 설정:
+
+```text
+Image Type: Filled
+Fill Method: Vertical
+Fill Origin: Bottom
+Fill Amount: 0
+```
+
+---
+
+## 8. `TruthFountainGameManager.cs` 붙이기
+
+빈 오브젝트를 만듭니다.
+
+```text
+TruthFountainSystem
+```
+
+여기에 붙입니다.
+
+```text
+TruthFountainSystem
+└── TruthFountainGameManager.cs
+```
+
+Inspector 연결:
+
+```text
+Fountain Data → TruthFountainData_Default
+UI → TruthFountainUI 오브젝트의 TruthFountainUI 컴포넌트
+Reward → TruthFountainSystem의 TruthFountainReward 컴포넌트
+Start On Awake → 테스트할 때만 체크
+Show Debug Log → 체크
+```
+
+테스트할 때는 `Start On Awake`를 켜면 Play 직후 바로 질문이 표시됩니다.
+실제 게임에서는 `TruthFountainOpenClose.Open()`에서 시작하게 하는 것을 추천합니다.
+
+---
+
+## 9. `TruthFountainReward.cs` 붙이기
+
+붙일 위치:
+
+```text
+TruthFountainSystem
+└── TruthFountainReward.cs
+```
+
+기본 설정:
+
+```text
+Give Only Once → 체크
+Show Debug Log → 체크
+```
+
+### 기억의 조각 보상과 연결하는 방법 A
+
+이미 만든 `MemoryPieceReward.cs`를 `TruthFountainSystem`에 같이 붙입니다.
+
+```text
+TruthFountainSystem
+├── TruthFountainGameManager
+├── TruthFountainReward
+└── MemoryPieceReward
+```
+
+`TruthFountainReward`에서:
+
+```text
+Reward Receiver → MemoryPieceReward 컴포넌트
+Reward Method Name → GiveReward
+```
+
+이렇게 하면 진실의 샘 성공 시 `MemoryPieceReward.GiveReward()`가 자동 호출됩니다.
+
+### 기억의 조각 보상과 연결하는 방법 B
+
+`TruthFountainReward`의 `On Reward Given` 이벤트에 직접 연결합니다.
+
+```text
+On Reward Given
+→ MemoryPieceReward
+→ GiveReward()
+```
+
+방 클리어 상태도 같이 바꾸고 싶으면 `On Reward Given` 이벤트에 `RoomProgressManager.MarkRoomCleared(RoomData)` 또는 `RoomProgressManager.MarkMemoryPieceCollected(RoomData)`를 추가로 연결할 수 있습니다.
+
+---
+
+## 10. `TruthFountainOpenClose.cs` 붙이기
+
+붙일 위치 추천:
+
+```text
+TruthFountainCanvas
+└── TruthFountainUI
+    └── TruthFountainOpenClose.cs
+```
+
+Inspector 연결:
+
+```text
+Truth Fountain Root → TruthFountainUI
+Game Manager → TruthFountainSystem의 TruthFountainGameManager
+Target Camera → Main Camera 또는 XR Camera
+Open On Start → 테스트할 때만 체크
+Start Game On Open → 체크
+Place In Front Of Camera On Open → 체크
+Face Camera On Open → 체크
+Distance From Camera → 2.2
+Vertical Offset → -0.1
+```
+
+닫기 버튼 연결:
+
+```text
+CloseButton OnClick
+→ TruthFountainUI
+→ TruthFountainOpenClose.Close()
+```
+
+방 선택 UI에서 진실의 샘 방 입장 시 연결:
+
+```text
+RoomEnterHandler 또는 진실의 샘 입장 이벤트
+→ TruthFountainOpenClose.Open()
+```
+
+---
+
+## 11. 최종 작동 흐름
+
+```text
+TruthFountainOpenClose.Open()
+→ TruthFountainUI 켜짐
+→ TruthFountainGameManager.StartGame()
+→ 첫 질문 표시
+→ 플레이어 선택지 클릭
+→ lieScore 증가 또는 유지
+→ NoseGaugeFill 갱신
+→ 다음 질문 표시
+→ 모든 질문 종료
+→ 성공/실패 판정
+→ 성공 시 TruthFountainReward.GiveReward()
+→ 최종 결과 패널 표시
+```
+
+---
+
+## 12. 테스트 순서
+
+```text
+1. TruthFountainData_Default asset 만들기
+2. 질문 5개 입력하기
+3. ChoiceButton 3개에 TruthChoiceButtonUI 붙이기
+4. TruthFountainUI 오브젝트에 TruthFountainUI.cs 붙이기
+5. TruthFountainSystem 만들기
+6. TruthFountainGameManager 붙이기
+7. TruthFountainReward 붙이기
+8. GameManager에 Data, UI, Reward 연결하기
+9. Start On Awake 체크
+10. Play 누르기
+11. 질문이 표시되는지 확인
+12. 선택지를 누르면 ResultText와 NoseGaugeFill이 바뀌는지 확인
+13. 최종 성공/실패 패널이 뜨는지 확인
+14. 성공 시 보상 이벤트가 호출되는지 확인
+```
+
+---
+
+## 13. 자주 나는 오류
+
+### 질문이 안 뜸
+
+확인할 것:
+
+```text
+TruthFountainGameManager의 Fountain Data가 비어 있지 않은가?
+TruthFountainData의 Questions 배열에 질문이 들어 있는가?
+TruthFountainGameManager의 UI가 연결되어 있는가?
+```
+
+### 선택지 버튼이 안 보임
+
+확인할 것:
+
+```text
+TruthQuestionData의 Choices 배열에 선택지가 들어 있는가?
+TruthFountainUI의 Choice Buttons 배열이 연결되어 있는가?
+각 ChoiceButton에 TruthChoiceButtonUI가 붙어 있는가?
+```
+
+### 코 게이지가 안 움직임
+
+확인할 것:
+
+```text
+NoseGaugeFill이 TruthFountainUI에 연결되어 있는가?
+NoseGaugeFill의 Image Type이 Filled인가?
+Fill Method가 Vertical인가?
+선택지의 Lie Amount가 1 이상인가?
+```
+
+### 버튼 클릭이 안 됨
+
+확인할 것:
+
+```text
+Canvas에 Graphic Raycaster가 있는가?
+씬에 EventSystem이 있는가?
+Button Image의 Raycast Target이 켜져 있는가?
+VR이라면 XR UI Input Module과 XR Ray Interactor UI Interaction이 켜져 있는가?
+```
+
+---
+
+## 14. 현재 단계에서 가장 먼저 할 것
+
+처음에는 보상 연결보다 아래 3가지만 먼저 확인하세요.
+
+```text
+1. 질문 표시
+2. 선택지 클릭
+3. 코 게이지 증가
+```
+
+이 3개가 정상 작동하면 진실의 샘 UI의 핵심은 완성입니다.