# Streamingle 플러그인 구현 가이드

## 1. 개발 환경 설정

### 1.1 필수 도구
- Unity 2022.3 LTS 이상
- Node.js 18.x 이상
- StreamDock 플러그인 SDK
- WebSocketSharp (Unity)
- ws 라이브러리 (Node.js)

### 1.2 프로젝트 구조
```
Streamingle_URP/
├── Assets/
│   └── Scripts/
│       └── Streamingle/
│           ├── WebSocketServer.cs
│           ├── ControllerManager.cs
│           ├── IController.cs
│           ├── CameraController.cs
│           └── ItemController.cs
└── Streamdeck/
    └── com.mirabox.streamingle.sdPlugin/
        ├── plugin.js
        ├── manifest.json
        └── package.json
```

## 2. 유니티 서버 구현

### 2.1 WebSocket 서버 설정
- 포트: 10701
- 바인딩: 127.0.0.1
- 프로토콜: ws://
- 경로: /

### 2.2 핵심 컴포넌트
1. **WebSocketServer**: 메인 서버 클래스
2. **ControllerManager**: 컨트롤러 관리
3. **IController**: 컨트롤러 인터페이스
4. **MessageHandler**: 메시지 처리

### 2.3 연결 시 즉시 데이터 전송
- 클라이언트 연결 시 자동으로 전체 데이터 전송
- 컨트롤러 목록, 아이템 목록, 액션 목록 포함
- UI 상태 정보 포함

## 3. 스트림덱 플러그인 구현

### 3.1 플러그인 구조
- WebSocket 클라이언트
- 메시지 파서
- UI 업데이트 핸들러
- 에러 처리 및 재연결

### 3.2 연결 관리
- 자동 연결 시도
- 연결 상태 모니터링
- 재연결 로직 (지수 백오프)
- 하트비트 처리

### 3.3 데이터 동기화
- 연결 시 초기 데이터 수신
- 실시간 업데이트 처리
- 로컬 캐시 관리
- UI 상태 동기화

## 4. 구현 단계

### 4.1 Phase 1: 기본 통신 (1-2주)
**목표**: WebSocket 연결 및 기본 메시지 교환

**유니티 측**:
1. WebSocketSharp 서버 설정
2. 기본 메시지 수신/전송
3. 연결 상태 관리
4. 로깅 시스템

**스트림덱 측**:
1. WebSocket 클라이언트 설정
2. 연결 시도 및 재연결
3. 기본 메시지 파싱
4. 연결 상태 표시

**테스트**:
- 연결 성공/실패
- 기본 메시지 교환
- 재연결 동작

### 4.2 Phase 2: 컨트롤러 시스템 (2-3주)
**목표**: 확장 가능한 컨트롤러 아키텍처

**유니티 측**:
1. IController 인터페이스 정의
2. ControllerManager 구현
3. CameraController 예시 구현
4. 동적 컨트롤러 등록

**스트림덱 측**:
1. 컨트롤러 목록 표시
2. 컨트롤러별 아이템 표시
3. 액션 버튼 생성
4. 선택 상태 관리

**테스트**:
- 컨트롤러 등록/해제
- 아이템 목록 표시
- 액션 실행

### 4.3 Phase 3: 고급 기능 (2-3주)
**목표**: 실시간 업데이트 및 고급 UI

**유니티 측**:
1. 실시간 데이터 업데이트
2. 액션 실행 결과 처리
3. 에러 처리 및 복구
4. 성능 최적화

**스트림덱 측**:
1. 실시간 UI 업데이트
2. 고급 에러 처리
3. 사용자 설정 저장
4. 성능 모니터링

**테스트**:
- 실시간 업데이트
- 에러 상황 처리
- 성능 테스트

### 4.4 Phase 4: 확장 및 최적화 (1-2주)
**목표**: 추가 컨트롤러 및 최적화

**유니티 측**:
1. ItemController 구현
2. AnimationController 구현
3. 메시지 압축
4. 배치 처리

**스트림덱 측**:
1. 추가 컨트롤러 지원
2. 고급 UI 기능
3. 설정 관리
4. 플러그인 배포 준비

**테스트**:
- 전체 시스템 통합 테스트
- 부하 테스트
- 사용자 테스트

## 5. 핵심 구현 포인트

### 5.1 연결 시 즉시 데이터 공유
```javascript
// 스트림덱 측 연결 처리
ws.on('open', () => {
    console.log('유니티 서버에 연결됨');
    // 연결 즉시 초기 데이터를 받음
});

ws.on('message', (data) => {
    const message = JSON.parse(data);
    if (message.type === 'connection_established') {
        // 즉시 UI 업데이트
        updateUIWithInitialData(message.data);
    }
});
```

### 5.2 컨트롤러 등록 시스템
```csharp
// 유니티 측 컨트롤러 등록
public class ControllerManager : MonoBehaviour
{
    private Dictionary<string, IController> controllers = new Dictionary<string, IController>();
    
    public void RegisterController(IController controller)
    {
        controllers[controller.GetControllerId()] = controller;
        // 연결된 클라이언트들에게 즉시 알림
        NotifyControllerAdded(controller);
    }
}
```

### 5.3 실시간 업데이트
```csharp
// 유니티 측 데이터 변경 알림
public void OnDataChanged(string controllerId, string itemId, object changes)
{
    var message = new {
        type = "data_update",
        timestamp = DateTime.UtcNow.ToString("o"),
        version = "1.0",
        data = new {
            controller_id = controllerId,
            item_id = itemId,
            changes = changes
        }
    };
    
    BroadcastMessage(message);
}
```

## 6. 에러 처리 전략

### 6.1 연결 에러
- 자동 재연결 (지수 백오프)
- 연결 상태 표시
- 사용자 알림

### 6.2 데이터 에러
- JSON 파싱 에러 처리
- 필수 필드 검증
- 기본값 처리

### 6.3 액션 에러
- 액션 실행 실패 처리
- 사용자 피드백
- 롤백 처리

## 7. 성능 최적화

### 7.1 메시지 최적화
- 필요한 데이터만 전송
- 메시지 압축
- 배치 처리

### 7.2 UI 최적화
- 가상 스크롤링
- 이미지 캐싱
- 렌더링 최적화

### 7.3 메모리 관리
- 객체 풀링
- 가비지 컬렉션 최적화
- 리소스 해제

## 8. 테스트 전략

### 8.1 단위 테스트
- 컨트롤러 인터페이스 테스트
- 메시지 파싱 테스트
- 에러 처리 테스트

### 8.2 통합 테스트
- 전체 시스템 테스트
- 성능 테스트
- 부하 테스트

### 8.3 사용자 테스트
- 실제 스트리밍 환경 테스트
- 사용자 피드백 수집
- UI/UX 개선

## 9. 배포 및 유지보수

### 9.1 배포 준비
- 플러그인 패키징
- 문서 작성
- 사용자 가이드

### 9.2 버전 관리
- Semantic Versioning
- 변경 로그 관리
- 호환성 유지

### 9.3 업데이트 시스템
- 자동 업데이트 체크
- 점진적 업데이트
- 롤백 지원

## 10. 개발 팁

### 10.1 디버깅
- 구조화된 로깅 사용
- WebSocket 메시지 모니터링
- 성능 프로파일링

### 10.2 코드 품질
- 코드 리뷰
- 단위 테스트 작성
- 문서화

### 10.3 협업
- Git 브랜치 전략
- 코드 컨벤션
- 리뷰 프로세스