kindnick/Streamingle_URP

Fork 0

KINDNICK 8b6a06e90f ADD : 스트림덱 플러그인 추가 업데이트 아이템 + 카메라 기능

2025-07-07 04:26:38 +09:00

9.0 KiB (Stored with Git LFS)

Raw Permalink Blame History

JSON 통신 프로토콜 상세 명세서

1. 기본 메시지 구조

1.1 공통 헤더

모든 메시지는 다음 구조를 가져야 합니다:

{
  "type": "메시지_타입",
  "timestamp": "ISO 8601 형식",
  "version": "1.0",
  "data": {
    // 메시지별 데이터
  }
}

1.2 필수 필드 설명

type: 메시지 타입 (문자열, 필수)
timestamp: 메시지 생성 시간 (ISO 8601, 필수)
version: 프로토콜 버전 (문자열, 필수)
data: 메시지 데이터 (객체, 필수)

2. 연결 관련 메시지

2.1 연결 성공 (connection_established)

{
  "type": "connection_established",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "session_id": "unique_session_id",
    "available_controllers": [
      {
        "id": "camera_controller",
        "name": "카메라 컨트롤러",
        "type": "camera",
        "description": "카메라 전환 및 설정 관리",
        "items": [
          {
            "id": "camera_1",
            "name": "메인 카메라",
            "description": "메인 스트리밍 카메라",
            "status": "active",
            "properties": {
              "fov": 60,
              "position": [0, 0, 0],
              "rotation": [0, 0, 0]
            }
          }
        ],
        "available_actions": [
          {
            "id": "switch_camera",
            "name": "카메라 전환",
            "description": "선택된 카메라로 전환"
          },
          {
            "id": "adjust_fov",
            "name": "FOV 조정",
            "description": "시야각 조정"
          }
        ]
      }
    ],
    "ui_state": {
      "current_selection": null,
      "available_actions": [],
      "theme": "dark",
      "language": "ko"
    }
  }
}

2.2 연결 실패 (connection_failed)

{
  "type": "connection_failed",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "error_code": "AUTH_FAILED",
    "error_message": "인증에 실패했습니다",
    "retry_after": 30
  }
}

2.3 하트비트 (heartbeat)

{
  "type": "heartbeat",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "status": "alive",
    "uptime": 3600
  }
}

3. 데이터 요청/응답 메시지

3.1 데이터 요청 (request_data)

{
  "type": "request_data",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_type": "controller_list",
    "controller_id": "camera_controller",
    "filters": {
      "status": "active",
      "category": "camera"
    }
  }
}

3.2 데이터 응답 (data_response)

{
  "type": "data_response",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_id": "req_12345",
    "request_type": "controller_list",
    "result": {
      "controllers": [
        {
          "id": "camera_controller",
          "name": "카메라 컨트롤러",
          "items": [
            {
              "id": "camera_1",
              "name": "메인 카메라",
              "status": "active"
            }
          ]
        }
      ]
    }
  }
}

3.3 데이터 업데이트 알림 (data_update)

{
  "type": "data_update",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "controller_id": "camera_controller",
    "update_type": "item_status_changed",
    "item_id": "camera_1",
    "changes": {
      "status": "inactive",
      "position": [10, 5, 0]
    }
  }
}

4. 액션 실행 메시지

4.1 액션 실행 요청 (execute_action)

{
  "type": "execute_action",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "action_id": "switch_camera",
    "controller_id": "camera_controller",
    "parameters": {
      "target_camera_id": "camera_2",
      "transition_time": 1.0
    },
    "request_id": "action_12345"
  }
}

4.2 액션 실행 결과 (action_result)

{
  "type": "action_result",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_id": "action_12345",
    "action_id": "switch_camera",
    "status": "success",
    "result": {
      "previous_camera": "camera_1",
      "current_camera": "camera_2",
      "transition_completed": true
    },
    "execution_time": 0.5
  }
}

4.3 액션 실행 실패

{
  "type": "action_result",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_id": "action_12345",
    "action_id": "switch_camera",
    "status": "failed",
    "error": {
      "code": "CAMERA_NOT_FOUND",
      "message": "요청된 카메라를 찾을 수 없습니다"
    }
  }
}

5. UI 업데이트 메시지

5.1 UI 업데이트 요청 (ui_update)

{
  "type": "ui_update",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "update_type": "selection_changed",
    "controller_id": "camera_controller",
    "selection": {
      "item_id": "camera_1",
      "item_name": "메인 카메라"
    }
  }
}

5.2 UI 상태 정보 (ui_state)

{
  "type": "ui_state",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "current_selection": {
      "controller_id": "camera_controller",
      "item_id": "camera_1"
    },
    "available_actions": [
      {
        "id": "switch_camera",
        "name": "카메라 전환",
        "enabled": true
      },
      {
        "id": "adjust_fov",
        "name": "FOV 조정",
        "enabled": false
      }
    ],
    "ui_theme": "dark",
    "language": "ko"
  }
}

6. 컨트롤러별 데이터 구조

6.1 카메라 컨트롤러 (CameraController)

{
  "id": "camera_controller",
  "name": "카메라 컨트롤러",
  "type": "camera",
  "items": [
    {
      "id": "camera_1",
      "name": "메인 카메라",
      "description": "메인 스트리밍 카메라",
      "status": "active",
      "properties": {
        "fov": 60,
        "position": [0, 1.7, -5],
        "rotation": [0, 0, 0],
        "near_clip": 0.1,
        "far_clip": 1000
      },
      "actions": [
        {
          "id": "activate",
          "name": "활성화",
          "description": "카메라 활성화"
        },
        {
          "id": "adjust_fov",
          "name": "FOV 조정",
          "description": "시야각 조정",
          "parameters": {
            "min": 30,
            "max": 120,
            "step": 5
          }
        }
      ]
    }
  ]
}

6.2 아이템 컨트롤러 (ItemController)

{
  "id": "item_controller",
  "name": "아이템 컨트롤러",
  "type": "item",
  "items": [
    {
      "id": "weapon_1",
      "name": "기본 무기",
      "description": "기본 공격 무기",
      "status": "equipped",
      "properties": {
        "damage": 10,
        "range": 5,
        "durability": 100
      },
      "actions": [
        {
          "id": "equip",
          "name": "장착",
          "description": "무기 장착"
        },
        {
          "id": "unequip",
          "name": "해제",
          "description": "무기 해제"
        }
      ]
    }
  ]
}

7. 에러 코드 정의

7.1 연결 관련 에러

CONNECTION_REFUSED: 연결 거부
AUTH_FAILED: 인증 실패
TIMEOUT: 연결 타임아웃
INVALID_PROTOCOL: 잘못된 프로토콜

7.2 데이터 관련 에러

INVALID_REQUEST: 잘못된 요청
DATA_NOT_FOUND: 데이터 없음
PERMISSION_DENIED: 권한 없음
VALIDATION_FAILED: 데이터 검증 실패

7.3 액션 관련 에러

ACTION_NOT_FOUND: 액션 없음
INVALID_PARAMETERS: 잘못된 매개변수
EXECUTION_FAILED: 실행 실패
RESOURCE_BUSY: 리소스 사용 중

8. 메시지 우선순위

8.1 높은 우선순위 (즉시 처리)

connection_established
connection_failed
heartbeat
action_result (실패)

8.2 중간 우선순위 (순차 처리)

execute_action
data_update
ui_update

8.3 낮은 우선순위 (배치 처리)

request_data
data_response
ui_state

9. 메시지 크기 제한

9.1 단일 메시지 제한

최대 크기: 1MB
권장 크기: 100KB 이하
압축 사용 권장

9.2 배치 메시지

최대 항목 수: 100개
페이지네이션 사용
스트리밍 응답 지원

10. 버전 관리

10.1 호환성 정책

하위 호환성 유지
점진적 기능 추가
마이그레이션 가이드 제공

10.2 버전 형식

Semantic Versioning (MAJOR.MINOR.PATCH)
예: "1.0.0", "1.1.2"

10.3 버전 확인

연결 시 버전 교환
호환성 검증
업그레이드 알림

9.0 KiB (Stored with Git LFS) Raw Permalink Blame History

JSON 통신 프로토콜 상세 명세서

1. 기본 메시지 구조

1.1 공통 헤더

1.2 필수 필드 설명

2. 연결 관련 메시지

2.1 연결 성공 (connection_established)

2.2 연결 실패 (connection_failed)

2.3 하트비트 (heartbeat)

3. 데이터 요청/응답 메시지

3.1 데이터 요청 (request_data)

3.2 데이터 응답 (data_response)

3.3 데이터 업데이트 알림 (data_update)

4. 액션 실행 메시지

4.1 액션 실행 요청 (execute_action)

4.2 액션 실행 결과 (action_result)

4.3 액션 실행 실패

5. UI 업데이트 메시지

5.1 UI 업데이트 요청 (ui_update)

5.2 UI 상태 정보 (ui_state)

6. 컨트롤러별 데이터 구조

6.1 카메라 컨트롤러 (CameraController)

6.2 아이템 컨트롤러 (ItemController)

7. 에러 코드 정의

7.1 연결 관련 에러

7.2 데이터 관련 에러

7.3 액션 관련 에러

8. 메시지 우선순위

8.1 높은 우선순위 (즉시 처리)

8.2 중간 우선순위 (순차 처리)

8.3 낮은 우선순위 (배치 처리)

9. 메시지 크기 제한

9.1 단일 메시지 제한

9.2 배치 메시지

10. 버전 관리

10.1 호환성 정책

10.2 버전 형식

10.3 버전 확인

9.0 KiB (Stored with Git LFS)

Raw Permalink Blame History