167 lines
9.5 KiB
Markdown
167 lines
9.5 KiB
Markdown
|
# 11. UI 아키텍처 — 수상한 잡화점
|
||
|
|
|
||
|
|
> **작성일**: 2026-04-17
|
||
|
|
> **작성자**: 개발팀장
|
||
|
|
> **상태**: v1 (초판, Phase 0-B 연계 문서)
|
||
|
|
> **대상**: `Assets/Script/UGUI/` 전수 (Ingame 19 + Lobby 19 + Common/Title/Util/Manager/BackKey 등)
|
||
|
|
> **관련 문서**: `08_전투시스템_SOT_v1.md`, `09_카드시스템_아키텍처_v1.md`, `10_데이터로딩_구조_v1.md`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. 목적 (P18 §결정의 배경)
|
||
|
|
|
||
|
|
수상한 잡화점 UI 계층의 **구조·주요 매니저·상호작용 패턴**을 전수 식별하여:
|
||
|
|
1. 전투·카드·데이터 문서(08·09·10)에 이은 Phase 0-B 완결 (UI는 기획 밸런싱·시뮬레이션의 최종 표시 계층)
|
||
|
|
2. 코어 프레임워크 Tier 1 `NerdNavis.UI.UGUI`·`NerdNavis.UI.Components`에 흡수할 **범용 패턴 vs 프로젝트 특수 로직** 경계 확정 (C11)
|
||
|
|
3. UI 기획 연동·UX 검증 작업 시 영향 범위 식별에 필요한 **단일 SOT**
|
||
|
|
|
||
|
|
## 2. 전체 계층 구조
|
||
|
|
|
||
|
|
```
|
||
|
|
UGUI/
|
||
|
|
├── Manager/ UI 전역 매니저 계층 — 씬·팝업·로딩 브릿지
|
||
|
|
├── BackKey/ Android 뒤로가기 통합 처리
|
||
|
|
├── Common/ 씬 공용 (GameUI, ScenarioUI, ToastUI, ControlUI 등)
|
||
|
|
├── Util/ SafeArea, UI 확장 컴포넌트
|
||
|
|
├── Title/ 타이틀·로딩·공지·계정 진입 흐름
|
||
|
|
├── Lobby/ 로비 씬 UI (19개 스크립트)
|
||
|
|
│ ├── LobbyUIManager ← 로비 최상위 오케스트레이터
|
||
|
|
│ ├── LobbyTopUI, MoneyCard
|
||
|
|
│ ├── MainMenu/ 영웅·카드·장비·미션·상점 (Base + 5개 탭)
|
||
|
|
│ ├── Attandance/ 출석 보상
|
||
|
|
│ ├── CatTrade/ 상점(고양이 상인) — 재화·장비·인장·메인 미션 통합 (11종)
|
||
|
|
│ ├── Explore/ 탐험 — 지도·스테이지·보상 (7종)
|
||
|
|
│ ├── SeasonPass/ 시즌 패스 (2종)
|
||
|
|
│ └── ETC/
|
||
|
|
├── Ingame/ 전투·던전 씬 UI (19개 스크립트)
|
||
|
|
│ ├── IngameUIManager ← 인게임 최상위 오케스트레이터 (153 LOC)
|
||
|
|
│ ├── DungeonProcess ← 스테이지 진행 UI (67 LOC)
|
||
|
|
│ ├── SelectCardUI ← 카드 선택 (290 LOC, 최대 UI 단일 모듈)
|
||
|
|
│ ├── BattleCard, BattleSmallCard, DeckUI, DeckUI_Skills, DeckUI_My4Spec
|
||
|
|
│ ├── GainCardList, IngameTopUI, SpecificityCard/List
|
||
|
|
│ ├── MerchantBuyPopup, PCMainStatUI, IngameMainStatCard
|
||
|
|
│ ├── Result/ DefeatUI, WinUI, StageClearRewards, ResultComon
|
||
|
|
│ └── ETC/
|
||
|
|
└── zTestUI/
|
||
|
|
```
|
||
|
|
|
||
|
|
## 3. 최상위 매니저 3종 — 오케스트레이션 책임
|
||
|
|
|
||
|
|
### 3-1. `LobbyUIManager` (Lobby/LobbyUIManager.cs, 202 LOC)
|
||
|
|
- 로비 씬 전체 UI 탭 전환·활성화 제어
|
||
|
|
- 탭 구성: MainMenu(영웅/카드/장비/미션/상점) · Attandance · CatTrade · Explore · SeasonPass
|
||
|
|
- 각 탭 자체 열림 상태·재진입 초기화 책임은 하위 UI에 위임하되, **탭 간 배타 활성은 본 매니저가 통제**
|
||
|
|
|
||
|
|
### 3-2. `IngameUIManager` (Ingame/IngameUIManager.cs, 153 LOC)
|
||
|
|
- 인게임(전투) 씬 UI 전역 오케스트레이터
|
||
|
|
- 주요 책임: `DungeonProcess` 연동, 전투 카드 스폰/회수, 결과 UI(Result/) 트리거
|
||
|
|
- 08 전투시스템 SOT 문서의 FSM 상태 전환 이벤트를 구독하여 UI 표시 갱신
|
||
|
|
|
||
|
|
### 3-3. `Title_Mgr` (Manager/Title_Mgr.cs)
|
||
|
|
- 타이틀 씬 진입 — 로딩·공지·계정 인증 흐름 제어
|
||
|
|
- `AddrResourceMgr`·`DataCheckMgr`와 협력 (Addressable 로드·마스터 데이터 체크)
|
||
|
|
|
||
|
|
## 4. 공통 UI 컴포넌트 (Common + Util)
|
||
|
|
|
||
|
|
| 컴포넌트 | 위치 | 범용성 | 프레임워크 흡수 대상 |
|
||
|
|
|---------|------|--------|--------------------|
|
||
|
|
| `GameUI` | Common/GameUI.cs | ★ 매우 높음 (UIView 추상화 출발점) | ✅ `NerdNavis.UI.UGUI.UIView` |
|
||
|
|
| `ScenarioUI` | Common/ScenarioUI.cs | △ 프로젝트 특수 (시나리오 시스템) | ❌ 프로젝트 유지 |
|
||
|
|
| `ToastUI` | Common/ToastUI.cs | ★ 매우 높음 | ✅ `NerdNavis.UI.Components` |
|
||
|
|
| `TouchBlockUI` | Common/TouchBlockUI.cs | ★ 매우 높음 | ✅ `NerdNavis.UI.Components` |
|
||
|
|
| `ControlUI`/`ControlUILock` | Common/ | ○ UI 입력 잠금 패턴 | ✅ `NerdNavis.UI.Components` |
|
||
|
|
| `MainStatCardBase` | Common/MainStatCardBase.cs | △ 프로젝트 카드 베이스 | ❌ 프로젝트 유지 |
|
||
|
|
| `ItemSimpleCard` | Common/ItemSimpleCard.cs | △ 프로젝트 아이템 카드 | ❌ 프로젝트 유지 |
|
||
|
|
| `SafeArea` | Util/ (추정) | ★ 매우 높음 | ✅ `NerdNavis.UI.Components.SafeArea` |
|
||
|
|
| `UIAtlasMgr` | UGUI/Manager/uScrollViewMgr 계열 | ★ 높음 | ✅ `NerdNavis.UI.UGUI.AtlasManager` |
|
||
|
|
| 무한 스크롤 (`uScrollViewMgr`·`uScrollViewArrMgr`) | UGUI/Manager/ | ★ 높음 | ✅ `NerdNavis.UI.UGUI.VirtualScroll` |
|
||
|
|
|
||
|
|
> 범용성 표기: ★=1순위 흡수 · ○=2순위 · △=프로젝트 특수 · ❌=범용 불가
|
||
|
|
|
||
|
|
## 5. 핵심 UI 모듈 — 카드 중심 설계
|
||
|
|
|
||
|
|
### 5-1. BattleCard / BattleSmallCard (Ingame)
|
||
|
|
- 전투 중 실제 표시되는 카드 UI. 09 카드시스템 아키텍처의 런타임 표시 계층
|
||
|
|
- 지속 인스턴스 풀링 대상 (프레임 당 다수 스폰/회수)
|
||
|
|
|
||
|
|
### 5-2. SelectCardUI (Ingame, 290 LOC — 최대 단일 UI 모듈)
|
||
|
|
- 카드 선택(획득 후보 3장 중 1장 선택) UI
|
||
|
|
- 제약 조건(C7 재미): 선택 시간·UX 피드백·희귀도 연출이 집약됨
|
||
|
|
- **프레임워크 흡수 비대상** — 프로젝트 특수 선택 규칙 (배제 조건·카드 풀 계산 등)
|
||
|
|
|
||
|
|
### 5-3. DeckUI 계열 (DeckUI, DeckUI_Skills, DeckUI_My4Spec)
|
||
|
|
- 데크·스킬·4스펙(고유 특성) 표시 UI
|
||
|
|
- 슬롯 기반 그리드 배치 패턴 → VirtualScroll·GridPool 흡수 후보
|
||
|
|
|
||
|
|
### 5-4. DungeonProcess (Ingame, 67 LOC)
|
||
|
|
- 스테이지 진행 UI — 맵 패턴·배틀·이벤트·보스 표시
|
||
|
|
- 맵 패턴 규칙(P17·기획팀 스테이지 설계)의 UI 표현 계층
|
||
|
|
|
||
|
|
## 6. 로비 기능별 UI 클러스터
|
||
|
|
|
||
|
|
### 6-1. MainMenu — 영웅·카드·장비·미션·상점 (5탭)
|
||
|
|
- `Base/`: 공통 베이스
|
||
|
|
- `1_Hero`·`2_Card`·`3_Equipment`·`4_Mission`: 각 탭 세부 (숫자 접두어 = 표시 순서)
|
||
|
|
- `MainMenu_Shop.cs`: 상점 탭(본 스크립트는 `5_Shop` 폴더가 아닌 루트에 존재 — 폴더 미정립)
|
||
|
|
|
||
|
|
### 6-2. CatTrade — 상점(고양이 상인) 통합 (11개 스크립트, 로비 내 최대 클러스터)
|
||
|
|
- 재화 거래(`CatTradeUI_Goods`)
|
||
|
|
- 장비 거래(`CatTradeUI_Equipment` + `CatTradeEquipmentBuyPopup` + `EquipmentTradeInvenCard`)
|
||
|
|
- 메인 미션(`CatTradeUI_MainMission`)
|
||
|
|
- 인장(`CatTradeUI_Seal` + `GetSealUI` + `SealRoulleteCard` + `SealSlotScroller`)
|
||
|
|
- 재화 카드(`CatTradeGoodsCard`)
|
||
|
|
|
||
|
|
### 6-3. Explore — 탐험 (7개 스크립트)
|
||
|
|
- 맵(`ExploreUI_Map`·`ExploreMapName`·`ExploreUI_Map_Cloud`(안개)): 맵 노드·구름 연출
|
||
|
|
- 스테이지(`ExploreUI_StageSelect`·`ExploreStageCard`): 노드 선택·카드 표시
|
||
|
|
- 보상(`ExploreRewardPopup`)
|
||
|
|
|
||
|
|
### 6-4. SeasonPass · Attandance
|
||
|
|
- 시즌 패스(`SeasonPassUI`·`SeasonPassCard`): 트랙·레벨·보상 표시
|
||
|
|
- 출석(`AttandanceUI`·`AttandanceCard`): 일일 보상 슬롯
|
||
|
|
|
||
|
|
## 7. BackKey 통합 처리
|
||
|
|
|
||
|
|
- `BackKey/` 디렉토리: Android `Escape` 키 통합 처리
|
||
|
|
- 열린 UI 스택 관리 → 가장 위 UI부터 순차 닫기
|
||
|
|
- **프레임워크 흡수 후보**: `NerdNavis.UI.UGUI.BackKeyDispatcher` (안드로이드 필수 패턴)
|
||
|
|
|
||
|
|
## 8. 프레임워크 Tier 1 흡수 계획 (범용성 ★ 우선)
|
||
|
|
|
||
|
|
차기 프로젝트 활용을 위한 **범용 UI 프레임워크** 구성 요소:
|
||
|
|
|
||
|
|
| 모듈 | 네임스페이스 | 수상한 잡화점 출처 |
|
||
|
|
|------|------------|------------------|
|
||
|
|
| UIView 추상 베이스 | `NerdNavis.UI.UGUI.UIView` | `Common/GameUI` |
|
||
|
|
| SafeArea | `NerdNavis.UI.Components.SafeArea` | `UGUI/Util/SafeArea` |
|
||
|
|
| Toast | `NerdNavis.UI.Components.Toast` | `Common/ToastUI` |
|
||
|
|
| 입력 차단 | `NerdNavis.UI.Components.InputBlocker` | `Common/TouchBlockUI`·`ControlUI` |
|
||
|
|
| 아틀라스 매니저 | `NerdNavis.UI.UGUI.AtlasManager` | `UGUI/Manager/UIAtlasMgr` |
|
||
|
|
| 무한 스크롤 | `NerdNavis.UI.UGUI.VirtualScroll` | `UGUI/Manager/uScrollView*Mgr` |
|
||
|
|
| BackKey 디스패처 | `NerdNavis.UI.UGUI.BackKeyDispatcher` | `BackKey/` |
|
||
|
|
|
||
|
|
## 9. 기획 연동 포인트 (UX 검증 시 영향 범위)
|
||
|
|
|
||
|
|
| 기획 변경 범주 | 영향 UI 모듈 |
|
||
|
|
|---------------|------------|
|
||
|
|
| 카드 조건·배타(P17) | `SelectCardUI`, `SpecificityCard/List` |
|
||
|
|
| 스테이지 맵 패턴 | `DungeonProcess`, `ExploreUI_Map`·`ExploreUI_StageSelect` |
|
||
|
|
| 보상 수치 | `ExploreRewardPopup`, `StageClearRewards`, `Result/WinUI` |
|
||
|
|
| 상점 재화 밸런스 | `CatTradeUI_*`, `MerchantBuyPopup`, `MoneyCard` |
|
||
|
|
| 시즌 패스 보상 트랙 | `SeasonPassUI`, `SeasonPassCard` |
|
||
|
|
| 출석 보상 | `AttandanceUI`, `AttandanceCard` |
|
||
|
|
|
||
|
|
## 10. 검증 방법 (P18 §검증)
|
||
|
|
|
||
|
|
1. 각 행의 파일 경로는 `Assets/Script/UGUI/{클러스터}/{파일명}.cs`에서 실존 확인 가능 (본 문서 작성 시 `ls`로 전수 확인 완료)
|
||
|
|
2. LOC 표기는 `wc -l` 결과 기준
|
||
|
|
3. 범용성 분류(★/○/△/❌)는 의존성 스캔(Unity 타입·게임 특수 enum 참조 여부)로 재검증 가능
|
||
|
|
|
||
|
|
## 11. 기각안 (P24 §기각안)
|
||
|
|
|
||
|
|
- **기각안 A: UIToolkit 병행 매핑 문서화** — 기획 방향이 UGUI 단일이므로 UIToolkit 매핑은 차기 프로젝트 R&D로 이관 (본 문서는 UGUI 전수 한정)
|
||
|
|
- **기각안 B: 각 스크립트 public API 메서드 전수 목록화** — 토큰 비용 과다 + 기획·검증 영향도 분류 목적에 불필요. 구조 수준 분류로 대체
|
||
|
|
|
||
|
|
## 부록 A. 변경 이력
|
||
|
|
- **v1 (2026-04-17)**: 초판. 개발팀장 Phase 0-B 완결 작업(B-4)으로 작성. Assets 전수 `ls` + 주요 파일 LOC 실측 기반.
|