XRLib/Assets/Scripts/UVC/CLAUDE.md

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)

// 필드/프로퍼티에 [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로 변환하는 매핑 시스템입니다.

// 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 - 오브젝트 풀링

// 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 시스템

// 모달 열기
var content = new ModalContent("Prefabs/UI/ConfirmModal")
{
    Title = "확인",
    Message = "정말 삭제하시겠습니까?"
};
bool confirmed = await Modal.Open<bool>(content);

// 모달 닫기
await Modal.Close();

Tab 시스템

// 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 시스템

// PropertyWindow에서 다양한 속성 타입 지원
UTKStringPropertyItem   // 문자열
UTKIntPropertyItem      // 정수
UTKFloatPropertyItem    // 실수
UTKBoolPropertyItem     // 불리언
UTKVector2/3PropertyItem // 벡터
UTKColorPropertyItem    // 색상
UTKDatePropertyItem     // 날짜
UTKEnumPropertyItem     // 열거형
UTKDropdownPropertyItem // 드롭다운
UTKRadioPropertyItem    // 라디오 버튼

6. Network - HTTP/디바운스

// 디바운스 요청 (실시간 검색 등)
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 확장

// 자식 순회
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