9.5 KiB
9.5 KiB
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 계층의 구조·주요 매니저·상호작용 패턴을 전수 식별하여:
- 전투·카드·데이터 문서(08·09·10)에 이은 Phase 0-B 완결 (UI는 기획 밸런싱·시뮬레이션의 최종 표시 계층)
- 코어 프레임워크 Tier 1
NerdNavis.UI.UGUI·NerdNavis.UI.Components에 흡수할 범용 패턴 vs 프로젝트 특수 로직 경계 확정 (C11) - 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/디렉토리: AndroidEscape키 통합 처리- 열린 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 §검증)
- 각 행의 파일 경로는
Assets/Script/UGUI/{클러스터}/{파일명}.cs에서 실존 확인 가능 (본 문서 작성 시ls로 전수 확인 완료) - LOC 표기는
wc -l결과 기준 - 범용성 분류(★/○/△/❌)는 의존성 스캔(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 실측 기반.