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 플러그인 설치

# 플러그인 폴더로 이동
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 스크립트 설정

// 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

{
  "type": "game_state_update",
  "data": {
    "playerHP": 100,
    "playerScore": 1500,
    "currentLevel": 3
  },
  "timestamp": 1640995200000
}

StreamDock → Unity

{
  "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. 기본 연결 테스트

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. 게임 상태 동기화

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 버튼 이벤트 처리

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 플러그인 로그 확인

# 플러그인 실행 시 로그 출력
npm start

Unity 콘솔 로그

• Unity Console 창에서 연결 상태 및 메시지 확인
• Debug.Log() 출력 확인

HTTP API 테스트

# 상태 확인
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. 커스텀 이벤트 추가

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

2. 다중 Unity 인스턴스 지원

// Unity 인스턴스 ID 추가
communicator.SendMessageToStreamDock("game_state_update", new {
    instanceId = "unity_001",
    gameState = currentGameState
});

3. 실시간 게임 통계

// 게임 통계 전송
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! 🎮