Streamingle_URP/StreamDock-Plugin-SDK/Unity_StreamDock_통신_가이드.md

# Unity ↔ StreamDock 통신 플러그인 사용 가이드

## 🎮 개요
이 가이드는 Unity 게임과 Mirabox StreamDock 간의 실시간 통신을 위한 플러그인 사용법을 설명합니다.

## 📋 시스템 요구사항

### StreamDock 측
- **Node.js**: v14.0.0 이상
- **StreamDock 소프트웨어**: 미라박스에서 제공하는 최신 버전
- **포트**: 15732 (WebSocket), 15733 (HTTP)

### Unity 측
- **Unity**: 2019.4 LTS 이상
- **.NET 4.x** 또는 **.NET Standard 2.1**
- **WebSocket 지원**: System.Net.WebSockets

## 🚀 설치 및 설정

### 1. StreamDock 플러그인 설치

```bash
# 플러그인 폴더로 이동
cd SDNodeJsSDK/unity-communication-plugin

# 의존성 설치
npm install

# 플러그인 실행
npm start
```

### 2. Unity 프로젝트 설정

1. **스크립트 복사**
   - `Unity_Scripts/StreamDockCommunicator.cs` → Unity 프로젝트의 `Scripts` 폴더
   - `Unity_Scripts/GameController.cs` → Unity 프로젝트의 `Scripts` 폴더

2. **GameObject 설정**
   ```
   GameManager (Empty GameObject)
   ├── StreamDockCommunicator 컴포넌트
   └── GameController 컴포넌트
   ```

## 🔧 사용법

### StreamDock 플러그인 설정

1. **StreamDock 소프트웨어 실행**
2. **플러그인 폴더 지정**: `SDNodeJsSDK/unity-communication-plugin`
3. **버튼 추가**:
   - "Unity 이벤트 전송" 버튼
   - "Unity 상태 수신" 버튼

### Unity 스크립트 설정

```csharp
// StreamDockCommunicator 설정
[SerializeField] private string serverUrl = "ws://localhost:15732";
[SerializeField] private bool autoConnect = true;

// 이벤트 연결
streamDock.OnStreamDockMessageReceived.AddListener(OnStreamDockMessage);
streamDock.OnConnected.AddListener(OnStreamDockConnected);
streamDock.OnDisconnected.AddListener(OnStreamDockDisconnected);
```

## 📡 통신 프로토콜

### WebSocket 메시지 형식

#### Unity → StreamDock
```json
{
  "type": "game_state_update",
  "data": {
    "playerHP": 100,
    "playerScore": 1500,
    "currentLevel": 3
  },
  "timestamp": 1640995200000
}
```

#### StreamDock → Unity
```json
{
  "type": "streamdock_button_clicked",
  "data": {
    "buttonId": "action1",
    "action": "send_event"
  },
  "timestamp": 1640995200000
}
```

## 🎯 이벤트 타입

### Unity에서 전송하는 이벤트
- `game_state_update`: 게임 상태 업데이트
- `player_action`: 플레이어 액션
- `level_complete`: 레벨 완료
- `test_message`: 테스트 메시지

### StreamDock에서 전송하는 이벤트
- `streamdock_button_clicked`: 버튼 클릭
- `dial_rotate`: 다이얼 회전
- `dial_press`: 다이얼 누름
- `request_game_state`: 게임 상태 요청

## 🛠️ 개발 예제

### 1. 기본 연결 테스트

```csharp
public class StreamDockTest : MonoBehaviour
{
    [SerializeField] private StreamDockCommunicator communicator;
    
    void Start()
    {
        // 연결 이벤트 구독
        communicator.OnConnected.AddListener(() => {
            Debug.Log("StreamDock 연결됨!");
        });
        
        // 메시지 수신 이벤트 구독
        communicator.OnStreamDockMessageReceived.AddListener((type, data) => {
            Debug.Log($"이벤트 수신: {type}");
        });
    }
}
```

### 2. 게임 상태 동기화

```csharp
public class GameStateManager : MonoBehaviour
{
    [SerializeField] private StreamDockCommunicator communicator;
    
    public void UpdatePlayerHP(int newHP)
    {
        // Unity 내부 상태 업데이트
        playerHP = newHP;
        
        // StreamDock으로 상태 전송
        communicator.UpdateGameState(hp: newHP);
    }
    
    public void AddScore(int points)
    {
        // Unity 내부 상태 업데이트
        score += points;
        
        // StreamDock으로 상태 전송
        communicator.UpdateGameState(score: score);
    }
}
```

### 3. StreamDock 버튼 이벤트 처리

```csharp
public class StreamDockEventHandler : MonoBehaviour
{
    [SerializeField] private StreamDockCommunicator communicator;
    
    void Start()
    {
        communicator.OnStreamDockMessageReceived.AddListener(HandleStreamDockEvent);
    }
    
    private void HandleStreamDockEvent(string eventType, object data)
    {
        switch (eventType)
        {
            case "button_clicked":
                // 버튼 클릭 시 게임 액션 실행
                ExecuteGameAction();
                break;
                
            case "dial_rotate":
                // 다이얼 회전 시 볼륨 조절
                AdjustVolume(data);
                break;
        }
    }
}
```

## 🔍 디버깅

### StreamDock 플러그인 로그 확인
```bash
# 플러그인 실행 시 로그 출력
npm start
```

### Unity 콘솔 로그
- Unity Console 창에서 연결 상태 및 메시지 확인
- `Debug.Log()` 출력 확인

### HTTP API 테스트
```bash
# 상태 확인
curl http://localhost:15733/status

# 이벤트 전송
curl -X POST http://localhost:15733/send-event \
  -H "Content-Type: application/json" \
  -d '{"eventType": "test", "data": {"message": "test"}}'
```

## 🚨 문제 해결

### 연결 문제
1. **포트 확인**: 15732, 15733 포트가 사용 가능한지 확인
2. **방화벽 설정**: Windows 방화벽에서 포트 허용
3. **서버 실행 확인**: `npm start` 명령어로 서버 실행

### Unity 연결 실패
1. **WebSocket 지원 확인**: .NET 4.x 또는 .NET Standard 2.1 사용
2. **URL 확인**: `ws://localhost:15732` 올바른지 확인
3. **재연결**: 자동 재연결 기능이 5초마다 시도

### 메시지 전송 실패
1. **JSON 형식 확인**: 올바른 JSON 형식인지 확인
2. **연결 상태 확인**: Unity와 StreamDock이 모두 연결되어 있는지 확인
3. **로그 확인**: Unity Console과 StreamDock 로그 확인

## 📚 고급 기능

### 1. 커스텀 이벤트 추가
```csharp
// Unity에서 커스텀 이벤트 전송
communicator.SendMessageToStreamDock("custom_event", new {
    action = "special_skill",
    power = 100,
    target = "boss"
});
```

### 2. 다중 Unity 인스턴스 지원
```csharp
// Unity 인스턴스 ID 추가
communicator.SendMessageToStreamDock("game_state_update", new {
    instanceId = "unity_001",
    gameState = currentGameState
});
```

### 3. 실시간 게임 통계
```csharp
// 게임 통계 전송
communicator.SendMessageToStreamDock("game_stats", new {
    playTime = Time.time,
    enemiesKilled = enemyCount,
    itemsCollected = itemCount
});
```

## 🎮 게임 통합 예제

### RPG 게임
- **HP/MP 표시**: StreamDock 버튼에 실시간 표시
- **스킬 단축키**: StreamDock 버튼으로 스킬 발동
- **인벤토리 관리**: 다이얼로 아이템 선택

### 액션 게임
- **콤보 카운터**: StreamDock에 콤보 수 표시
- **특수 액션**: StreamDock 버튼으로 특수 스킬
- **보스 체력**: StreamDock에 보스 HP 표시

### 퍼즐 게임
- **레벨 진행도**: StreamDock에 현재 레벨 표시
- **힌트 시스템**: StreamDock 버튼으로 힌트 제공
- **타이머**: StreamDock에 남은 시간 표시

---

**Happy Gaming! 🎮**