261 lines
6.8 KiB
Markdown
261 lines
6.8 KiB
Markdown
# UVC 라이브러리 가이드
|
|
|
|
UVC(Unity View Components)는 프로젝트 전반에서 사용되는 공통 유틸리티, UI 컴포넌트, 데이터 처리 라이브러리입니다.
|
|
|
|
---
|
|
|
|
## 모듈 구조
|
|
|
|
```
|
|
UVC/
|
|
├── Core/ # DI, Injector 시스템
|
|
├── Data/ # 데이터 매핑, HTTP/MQTT 통신
|
|
├── DB/ # SQLite 데이터베이스
|
|
├── Edit/ # 3D 오브젝트 편집 (Gizmo, Selection)
|
|
├── Event/ # UniTask 기반 이벤트 핸들러
|
|
├── Extention/ # C# 확장 메서드
|
|
├── GLTF/ # GLTF 내보내기
|
|
├── Json/ # JSON 유틸리티
|
|
├── Linq/ # GameObject LINQ 확장
|
|
├── Locale/ # 다국어 지원
|
|
├── Log/ # 로깅 시스템
|
|
├── Network/ # HTTP 요청, Debounce
|
|
├── Object3d/ # 3D 인터랙션
|
|
├── Pool/ # 오브젝트 풀링
|
|
├── Tests/ # 단위 테스트
|
|
├── Threading/ # 메인 스레드 디스패처
|
|
├── UI/ # uGUI 기반 UI 컴포넌트
|
|
├── UIToolkit/ # UI Toolkit 기반 컴포넌트 ⭐
|
|
└── Util/ # 기타 유틸리티
|
|
```
|
|
|
|
---
|
|
|
|
## 핵심 모듈
|
|
|
|
### 1. Core - 의존성 주입 (DI)
|
|
|
|
```csharp
|
|
// 필드/프로퍼티에 [Inject] 어트리뷰트로 자동 주입
|
|
public class PlayerController : MonoBehaviour
|
|
{
|
|
[Inject] private ILogService _logger;
|
|
[Inject(Optional = true)] private IDebugService _debugService; // 선택적
|
|
}
|
|
|
|
// 서비스 등록
|
|
Injector.Register<ILogService, ConsoleLogger>(ServiceLifetime.App);
|
|
```
|
|
|
|
**주입 시점:**
|
|
- MonoBehaviour: `InjectorSceneContext.PerformSceneInjection()`
|
|
- 순수 C#: 인스턴스 생성 직후
|
|
- 수동: `Injector.Inject(target)`
|
|
|
|
### 2. Data - 데이터 매핑 시스템
|
|
|
|
JSON 데이터를 `DataObject`/`DataArray`로 변환하는 매핑 시스템입니다.
|
|
|
|
```csharp
|
|
// DataMask로 타입 정의
|
|
var mask = DataMask.Parse(@"{ ""name"": """", ""age"": 0 }");
|
|
mask.ObjectIdKey = "name";
|
|
|
|
// DataMapper로 변환
|
|
var mapper = new DataMapper(mask);
|
|
DataObject result = mapper.Map(sourceJson);
|
|
|
|
// 풀링 지원
|
|
var obj = DataObjectPool.Get();
|
|
obj.ReturnToPool(); // 사용 후 반환
|
|
```
|
|
|
|
**주요 클래스:**
|
|
- `DataMapper`: JSON → DataObject 변환
|
|
- `DataMask`: 타입 정의 마스크
|
|
- `DataObject/DataArray`: 통합 데이터 컨테이너
|
|
- `DataObjectPool/DataArrayPool`: 메모리 풀링
|
|
|
|
### 3. Pool - 오브젝트 풀링
|
|
|
|
```csharp
|
|
// GameObjectPool 사용
|
|
var pool = new GameObjectPool<Bullet>(bulletPrefab, container);
|
|
|
|
// 풀에서 가져오기
|
|
Bullet bullet = pool.GetItem("bullet_1");
|
|
|
|
// 풀에 반환
|
|
pool.ReturnItem("bullet_1");
|
|
|
|
// 통계 확인
|
|
Debug.Log(pool.GetStats()); // 최대 사용량, 현재 사용량, 풀 미스 횟수
|
|
```
|
|
|
|
### 4. UI - uGUI 컴포넌트
|
|
|
|
#### Modal 시스템
|
|
```csharp
|
|
// 모달 열기
|
|
var content = new ModalContent("Prefabs/UI/ConfirmModal")
|
|
{
|
|
Title = "확인",
|
|
Message = "정말 삭제하시겠습니까?"
|
|
};
|
|
bool confirmed = await Modal.Open<bool>(content);
|
|
|
|
// 모달 닫기
|
|
await Modal.Close();
|
|
```
|
|
|
|
#### Tab 시스템
|
|
```csharp
|
|
// TabView 초기화
|
|
tabView.InitializeTabs(tabs, configs, OnTabSelected, togglable: false);
|
|
|
|
// 탭 전환
|
|
await tabView.UpdateActiveTab(tabIndex, prevIndex, tabData);
|
|
```
|
|
|
|
### 5. UIToolkit - UI Toolkit 컴포넌트 ⭐
|
|
|
|
**권장**: 새 UI는 이 모듈의 컴포넌트를 사용하세요.
|
|
|
|
#### 리스트 컴포넌트
|
|
| 클래스 | 용도 |
|
|
|--------|------|
|
|
| `UTKTreeList` | 트리 구조 리스트 |
|
|
| `UTKAccordionList` | 접이식 리스트 |
|
|
| `UTKComponentList` | 컴포넌트 리스트 |
|
|
| `UTKImageList` | 이미지 리스트 |
|
|
|
|
#### 모달 컴포넌트
|
|
| 클래스 | 용도 |
|
|
|--------|------|
|
|
| `UTKColorPicker` | 색상 선택기 |
|
|
| `UTKColorPickerHSV` | HSV 색상 선택기 |
|
|
| `UTKDatePicker` | 날짜 선택기 |
|
|
| `UTKModalBlocker` | 모달 배경 차단 |
|
|
|
|
#### Property 시스템
|
|
```csharp
|
|
// PropertyWindow에서 다양한 속성 타입 지원
|
|
UTKStringPropertyItem // 문자열
|
|
UTKIntPropertyItem // 정수
|
|
UTKFloatPropertyItem // 실수
|
|
UTKBoolPropertyItem // 불리언
|
|
UTKVector2/3PropertyItem // 벡터
|
|
UTKColorPropertyItem // 색상
|
|
UTKDatePropertyItem // 날짜
|
|
UTKEnumPropertyItem // 열거형
|
|
UTKDropdownPropertyItem // 드롭다운
|
|
UTKRadioPropertyItem // 라디오 버튼
|
|
```
|
|
|
|
### 6. Network - HTTP/디바운스
|
|
|
|
```csharp
|
|
// 디바운스 요청 (실시간 검색 등)
|
|
var requester = new DebounceRequester();
|
|
|
|
void OnSearchTextChanged(string text)
|
|
{
|
|
requester.Request<SearchResult>(
|
|
300, // 300ms 디바운스
|
|
"/api/search",
|
|
"get",
|
|
$"{{\"query\": \"{text}\"}}",
|
|
null,
|
|
useAuth: true,
|
|
result => DisplayResults(result)
|
|
);
|
|
}
|
|
|
|
// 리소스 해제 필수
|
|
requester.Dispose();
|
|
```
|
|
|
|
### 7. Extention - 확장 메서드
|
|
|
|
| 파일 | 확장 대상 |
|
|
|------|-----------|
|
|
| `DictionaryEx` | Dictionary |
|
|
| `ImageEx` | Image |
|
|
| `LayoutGroupEx` | LayoutGroup |
|
|
| `NumberEx` | 숫자 타입 |
|
|
| `OrderedDictionary` | 순서 유지 딕셔너리 |
|
|
| `RectTransformEx` | RectTransform |
|
|
| `StringEx` | string |
|
|
| `TransformEx` | Transform |
|
|
| `TMP_InputFieldEx` | TMP_InputField |
|
|
|
|
### 8. Linq - GameObject 확장
|
|
|
|
```csharp
|
|
// 자식 순회
|
|
foreach (var child in gameObject.Children()) { }
|
|
|
|
// 조건부 검색
|
|
var buttons = gameObject.Descendants<Button>().Where(b => b.interactable);
|
|
|
|
// 부모 검색
|
|
var canvas = gameObject.Ancestors<Canvas>().FirstOrDefault();
|
|
```
|
|
|
|
---
|
|
|
|
## 사용 지침
|
|
|
|
### 새 UI 개발 시
|
|
1. **UIToolkit 모듈 사용** (`UVC/UIToolkit/`)
|
|
2. UXML/USS로 구조/스타일 분리
|
|
3. `UTK*` 접두사 클래스 활용
|
|
|
|
### 데이터 처리 시
|
|
1. `DataMapper` + `DataMask`로 JSON 매핑
|
|
2. `DataObjectPool`/`DataArrayPool`로 메모리 최적화
|
|
3. 사용 후 `ReturnToPool()` 호출
|
|
|
|
### 서비스 개발 시
|
|
1. 인터페이스 정의 (`IMyService`)
|
|
2. `InjectorAppContext` 또는 `InjectorSceneContext`에서 수동 등록
|
|
3. `[Inject]`로 주입 받기
|
|
|
|
> **참고**: `[Register]` 어트리뷰트는 향후 자동 스캔용으로 정의되어 있으나, 현재는 수동 등록이 필요합니다.
|
|
|
|
### 네트워크 요청 시
|
|
1. 연속 요청은 `DebounceRequester` 사용
|
|
2. `CancellationToken` 전달
|
|
3. 리소스 해제 (`Dispose()`) 필수
|
|
|
|
---
|
|
|
|
## 네이밍 규칙
|
|
|
|
| 접두사 | 의미 |
|
|
|--------|------|
|
|
| `UTK*` | UI Toolkit 컴포넌트 |
|
|
| `Data*` | 데이터 처리 클래스 |
|
|
| `I*` | 인터페이스 |
|
|
| `*Pool` | 풀링 클래스 |
|
|
| `*Ex` | 확장 메서드 클래스 |
|
|
|
|
---
|
|
|
|
## 테스트
|
|
|
|
```
|
|
UVC/Tests/
|
|
├── Editor/
|
|
│ └── Data/
|
|
│ ├── DataArrayTests.cs
|
|
│ ├── DataMapperTests.cs
|
|
│ ├── DataObjectTests.cs
|
|
│ ├── HttpDataFetcherTests.cs
|
|
│ └── MqttDataReceiverTests.cs
|
|
└── MockHttpRequester.cs
|
|
└── MockMQTTService.cs
|
|
```
|
|
|
|
에디터 테스트 실행: `Window > General > Test Runner`
|