Streamingle_URP/Streamdeck/Implementation_Guide.md

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 연결 시 즉시 데이터 공유

// 스트림덱 측 연결 처리
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 컨트롤러 등록 시스템

// 유니티 측 컨트롤러 등록
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 실시간 업데이트

// 유니티 측 데이터 변경 알림
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 브랜치 전략
• 코드 컨벤션
• 리뷰 프로세스