230 lines
5.7 KiB (Stored with Git LFS)
Markdown
230 lines
5.7 KiB (Stored with Git LFS)
Markdown
# Streamingle 플러그인 아키텍처 설계서
|
|
|
|
## 1. 시스템 개요
|
|
|
|
### 1.1 목적
|
|
- 스트림덱 플러그인과 유니티 간의 실시간 양방향 통신
|
|
- 여러 컨트롤러를 하나의 플러그인에서 통합 관리
|
|
- 연결 즉시 데이터 공유 및 동적 UI 업데이트
|
|
|
|
### 1.2 핵심 특징
|
|
- WebSocket 기반 실시간 통신
|
|
- JSON 프로토콜을 통한 구조화된 데이터 교환
|
|
- 연결 시 즉시 데이터 동기화
|
|
- 확장 가능한 컨트롤러 아키텍처
|
|
|
|
## 2. 통신 프로토콜
|
|
|
|
### 2.1 기본 메시지 구조
|
|
```json
|
|
{
|
|
"type": "메시지_타입",
|
|
"timestamp": "2024-01-01T00:00:00Z",
|
|
"data": {
|
|
// 메시지별 데이터
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.2 메시지 타입 정의
|
|
|
|
#### 2.2.1 연결 관련
|
|
- `connection_established`: 연결 성공
|
|
- `connection_failed`: 연결 실패
|
|
- `heartbeat`: 연결 상태 확인
|
|
|
|
#### 2.2.2 데이터 요청/응답
|
|
- `request_data`: 데이터 요청
|
|
- `data_response`: 데이터 응답
|
|
- `data_update`: 데이터 업데이트 알림
|
|
|
|
#### 2.2.3 액션 실행
|
|
- `execute_action`: 액션 실행 요청
|
|
- `action_result`: 액션 실행 결과
|
|
|
|
#### 2.2.4 UI 업데이트
|
|
- `ui_update`: UI 업데이트 요청
|
|
- `ui_state`: UI 상태 정보
|
|
|
|
## 3. 연결 시 즉시 데이터 공유 구조
|
|
|
|
### 3.1 연결 핸드셰이크 프로세스
|
|
1. 스트림덱 → 유니티: 연결 시도
|
|
2. 유니티 → 스트림덱: `connection_established` + 초기 데이터
|
|
3. 스트림덱: UI 즉시 업데이트
|
|
|
|
### 3.2 초기 데이터 구조
|
|
```json
|
|
{
|
|
"type": "connection_established",
|
|
"timestamp": "2024-01-01T00:00:00Z",
|
|
"data": {
|
|
"available_controllers": [
|
|
{
|
|
"id": "camera_controller",
|
|
"name": "카메라 컨트롤러",
|
|
"type": "camera",
|
|
"items": [
|
|
{
|
|
"id": "camera_1",
|
|
"name": "메인 카메라",
|
|
"description": "메인 스트리밍 카메라"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": "item_controller",
|
|
"name": "아이템 컨트롤러",
|
|
"type": "item",
|
|
"items": [
|
|
{
|
|
"id": "item_1",
|
|
"name": "무기 1",
|
|
"description": "기본 무기"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"ui_state": {
|
|
"current_selection": null,
|
|
"available_actions": []
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 4. 컨트롤러 아키텍처
|
|
|
|
### 4.1 기본 컨트롤러 인터페이스
|
|
모든 컨트롤러는 다음 인터페이스를 구현해야 함:
|
|
- `GetControllerInfo()`: 컨트롤러 정보 반환
|
|
- `GetItems()`: 관리 항목 목록 반환
|
|
- `ExecuteAction(action_id, parameters)`: 액션 실행
|
|
- `OnDataUpdate()`: 데이터 업데이트 알림
|
|
|
|
### 4.2 컨트롤러 등록 시스템
|
|
- 유니티 시작 시 자동 컨트롤러 스캔
|
|
- 동적 컨트롤러 추가/제거 지원
|
|
- 컨트롤러별 설정 관리
|
|
|
|
### 4.3 지원 컨트롤러 타입
|
|
- CameraController: 카메라 전환, 설정
|
|
- ItemController: 아이템 관리, 장착
|
|
- AnimationController: 애니메이션 재생
|
|
- EffectController: 이펙트 제어
|
|
- AudioController: 오디오 제어
|
|
|
|
## 5. 데이터 동기화 전략
|
|
|
|
### 5.1 실시간 업데이트
|
|
- 컨트롤러 상태 변경 시 즉시 알림
|
|
- UI 상태 자동 동기화
|
|
- 연결 끊김 시 자동 재연결
|
|
|
|
### 5.2 데이터 캐싱
|
|
- 스트림덱 측 로컬 캐시
|
|
- 변경된 데이터만 전송
|
|
- 캐시 무효화 전략
|
|
|
|
### 5.3 동기화 우선순위
|
|
1. 연결 시 전체 데이터
|
|
2. 상태 변경 알림
|
|
3. 주기적 하트비트
|
|
4. 요청 시 데이터
|
|
|
|
## 6. 에러 처리 및 복구
|
|
|
|
### 6.1 연결 관리
|
|
- 자동 재연결 (지수 백오프)
|
|
- 연결 상태 모니터링
|
|
- 타임아웃 처리
|
|
|
|
### 6.2 데이터 무결성
|
|
- JSON 유효성 검증
|
|
- 필수 필드 확인
|
|
- 기본값 처리
|
|
|
|
### 6.3 로깅 및 디버깅
|
|
- 구조화된 로그 시스템
|
|
- 에러 추적 및 보고
|
|
- 성능 모니터링
|
|
|
|
## 7. 확장성 고려사항
|
|
|
|
### 7.1 새로운 컨트롤러 추가
|
|
- 인터페이스 구현만으로 추가 가능
|
|
- 플러그인 재시작 없이 동적 로드
|
|
- 설정 기반 컨트롤러 활성화
|
|
|
|
### 7.2 새로운 메시지 타입
|
|
- 프로토콜 버전 관리
|
|
- 하위 호환성 유지
|
|
- 점진적 기능 추가
|
|
|
|
### 7.3 성능 최적화
|
|
- 메시지 압축
|
|
- 배치 처리
|
|
- 연결 풀링
|
|
|
|
## 8. 개발 로드맵
|
|
|
|
### 8.1 Phase 1: 기본 구조
|
|
- WebSocket 통신 기반 구축
|
|
- 기본 컨트롤러 인터페이스
|
|
- 연결 시 데이터 공유
|
|
|
|
### 8.2 Phase 2: 컨트롤러 구현
|
|
- CameraController 구현
|
|
- ItemController 구현
|
|
- 기본 UI 업데이트
|
|
|
|
### 8.3 Phase 3: 고급 기능
|
|
- 동적 컨트롤러 로드
|
|
- 고급 에러 처리
|
|
- 성능 최적화
|
|
|
|
### 8.4 Phase 4: 확장
|
|
- 추가 컨트롤러 타입
|
|
- 고급 UI 기능
|
|
- 플러그인 마켓플레이스 준비
|
|
|
|
## 9. 기술 스택
|
|
|
|
### 9.1 유니티 측
|
|
- WebSocketSharp: WebSocket 서버
|
|
- JSON.NET: JSON 직렬화
|
|
- Unity Coroutines: 비동기 처리
|
|
|
|
### 9.2 스트림덱 측
|
|
- ws: WebSocket 클라이언트
|
|
- Node.js 내장 모듈: 파일 시스템, 로깅
|
|
- JSON: 데이터 직렬화
|
|
|
|
## 10. 보안 고려사항
|
|
|
|
### 10.1 인증
|
|
- 연결 시 인증 토큰 검증
|
|
- 권한 기반 액션 제어
|
|
- 세션 관리
|
|
|
|
### 10.2 데이터 보호
|
|
- 민감한 데이터 암호화
|
|
- 로그 데이터 마스킹
|
|
- 접근 제어
|
|
|
|
## 11. 테스트 전략
|
|
|
|
### 11.1 단위 테스트
|
|
- 컨트롤러 인터페이스 테스트
|
|
- JSON 프로토콜 검증
|
|
- 에러 처리 테스트
|
|
|
|
### 11.2 통합 테스트
|
|
- 전체 시스템 통합 테스트
|
|
- 성능 테스트
|
|
- 부하 테스트
|
|
|
|
### 11.3 사용자 테스트
|
|
- 실제 스트리밍 환경 테스트
|
|
- 사용자 피드백 수집
|
|
- UI/UX 개선 |