잠금화면 입력 콜백 활성화¶

호스트 PC가 Windows 잠금화면 상태로 전환되면 운영체제(OS) 보안 정책으로 인해 OS 수준의 키보드·마우스 입력이 차단됩니다. 이 때문에 원격 환경에서는 화면과 사운드 스트리밍이 가능하지만 실제 게임 조작은 불가능한 상태가 됩니다.

이를 해결하기 위해 기존에는 원격 사용자가 Windows 계정 암호를 입력해 잠금을 해제해야 했으나, PC 전체 제어 권한 노출 위험 및 접속 절차의 번거로움이 존재합니다.

리모트 플레이 플러그인은 Hive 콘솔의 리모트 플레이 설정에서 ‘잠금화면 해제 없이 플레이’ 기능을 제공합니다. 본 기능을 활성화하면 키보드, 마우스, 터치, 조이스틱·휠, 줌과 같은 모든 입력 이벤트가 게임 콜백으로 직접 전달됩니다.

주요 동작 방식¶

• 콜백 기반 전달: 모든 입력 이벤트가 RegisterCallback으로 등록된 콜백 함수에 eventType: "Control" 형태로 전달됩니다. 잠금 상태와 무관하게 동일하게 동작하며, 잠금이 해제되어도 콜백 전달이 그대로 유지됩니다.
• OS 입력 경로 우회: OS의 SendInput 경로는 더 이상 사용되지 않으며, Windows 잠금 여부와 무관하게 일관된 입력 이벤트를 수신합니다.
• 게임 내 직접 주입: 게임은 콜백으로 수신한 입력 데이터를 내부 입력 시스템에 직접 주입하여 잠금 및 일반 상태 모두에서 동일한 조작을 처리합니다.

사전 준비¶

본 기능을 적용하기 전에 아래 사항이 준비되어야 합니다.

• 리모트 플레이 플러그인 임포트
• 이벤트 수신용 콜백 함수 등록.
• 지원 SDK / 플러그인 버전:
  • 리모트 플레이 플러그인 1.2.0 이상
  • Hive SDK V4 26.4.0 이상

Control 이벤트 프로토콜¶

‘잠금화면 해제 없이 플레이’ 기능을 활성화한 후 콜백으로 전달되는 입력 이벤트는 채팅 이벤트와 동일한 JSON 형식으로 전달되며, eventType 값은 "Control"로 고정됩니다. 실제 입력 종류는 안쪽 controlType으로 구분됩니다.

Envelope 공통 구조¶

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "<Key | Click | Wheel | Zoom>",
            "controlValue": {
                "value"  : "<controlType-specific-value>",
                "action" : "<controlType-specific-action>"
            }
        }
    },
    "etc"       : { }
}

controlType = "Key" — 키보드 입력¶

키보드 단일 키의 누름/뗌 상태를 전달합니다. 사용자가 웹 클라이언트에서 발생시킨 키 입력과 조이스틱 입력 모두 controlType으로 변환합니다.

조이스틱의 방향 코드는 매핑 설정(WASD / DIRECTION)에 따라 단일 키 이벤트로 분해되어 controlType으로 전달됩니다. 즉 게임 측에서는 키 입력과 조이스틱 입력이 동일한 형식으로 보입니다. 대각선 이동도 호스트가 두 개의 단일 키 이벤트로 분해하여 보냅니다.

예제 — 'A' 키 누름

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Key",
            "controlValue": { "value": "0x41", "action": "Down" }
        }
    },
    "etc"       : { }
}

예제 — 조이스틱 ↑ (WASD 매핑 시 'W' 키)

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Key",
            "controlValue": { "value": "0x57", "action": "Down" }
        }
    },
    "etc"       : { }
}

controlType = "Click" — 마우스/터치 좌표 입력¶

마우스 클릭/이동 및 터치 좌표를 전달합니다. 사용자가 웹 클라이언트에서 발생시킨 마우스 입력과 터치 입력 모두 게임 윈도우의 클라이언트 영역 픽셀 좌표(GetClientRect() 기준)로 자동 변환되어 전달됩니다.

좌표 변환 참고¶

curWidth / curHeight는 게임 윈도우의 GetClientRect() 기준 클라이언트 영역 크기입니다. 따라서 게임에서는 윈도우 좌표로 그대로 적용하세요.

예제 — 마우스 클릭 (Down → Up)

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Click",
            "controlValue": { "value": "526.5#792.5", "action": "Down" }
        }
    },
    "etc"       : { }
}

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Click",
            "controlValue": { "value": "526.5#792.5", "action": "Up" }
        }
    },
    "etc"       : { }
}

예제 — 드래그 (Move)

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Click",
            "controlValue": { "value": "645.1#681.7", "action": "Move" }
        }
    },
    "etc"       : { }
}

controlType = "Wheel" — 마우스 휠¶

마우스 휠 스크롤 동작을 전달합니다.

예제 — 휠 다운 (마우스 위치 1234.0 px, 567.0 px)

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Wheel",
            "controlValue": { "value": "1234.0#567.0", "action": "Down" }
        }
    },
    "etc"       : { }
}

controlType = "Zoom" — 줌 인/아웃¶

카메라 또는 지도 화면의 줌 인/아웃 동작을 전달합니다.

예제 — 줌 인

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Zoom",
            "controlValue": { "value": "1", "action": "In" }
        }
    },
    "etc"       : { }
}

예제 — 줌 아웃

{
    "version"   : "1.02.00",
    "eventType" : "Control",
    "eventValue": {
        "value": {
            "controlType" : "Zoom",
            "controlValue": { "value": "1", "action": "Out" }
        }
    },
    "etc"       : { }
}

입력 타입 변환 매핑 요약¶

웹 클라이언트가 보낸 원본 입력 타입이 호스트 콜백 이벤트로 변환되는 매핑 구조입니다.

상태(Event) / 채팅(Message) 이벤트는 본 Control 이벤트로 전달되지 않고 기존 프로토콜 규격으로 별도로 전달됩니다.

게임 측 입력 처리 가이드¶

Hive 콘솔의 리모트 플레이 설정에서 ‘잠금화면 해제 없이 플레이’ 기능을 활성화하면 리모트 플레이는 입력 이벤트를 운영체제(OS)의 입력 큐로 전달하지 않고, 등록된 콜백을 통해 게임에 직접 전달합니다.

따라서 콜백에서 수신한 입력 이벤트는 게임 내부 입력 시스템(예: Unity Input System, Unreal Input Subsystem)으로 직접 전달하여 처리해야 합니다.

이 방식은 Windows의 잠금화면 환경에서 OS 수준 입력 주입(SendInput, SendKey 등)이 제한되는 문제를 우회하기 위한 구조입니다. 입력 이벤트가 게임 프로세스 내부에서 직접 디스패치되므로, 잠금화면 상태와 일반 상태를 구분하지 않고 동일한 처리 경로를 사용하는 것을 권장합니다.

즉, ‘잠금화면 해제 없이 플레이’ 기능 활성화 이후에는 본 콜백을 통해 전달되는 모든 입력 이벤트를 수신하여 게임의 내부 입력 시스템으로 전달하는 방식으로 구현하는 것이 바람직합니다. 이를 통해 잠금화면 여부와 관계없이 일관된 입력 처리와 원격 플레이 동작을 보장할 수 있습니다.

• Unity: InputSystem.QueueEvent 또는 자체 입력 매니저로 디스패치
• Unreal Engine: FSlateApplication::OnKeyDown / OnMouseButtonDown 등 슬레이트 이벤트로 디스패치하거나 게임 자체 입력 매니저 사용

잠금화면 환경에서의 백그라운드 렌더링·오디오 처리 가이드¶

Windows 잠금화면 환경에서 리모트 플레이를 사용하려면 게임이 백그라운드 상태에서도 정상적으로 동작할 수 있어야 합니다. 대부분의 게임 엔진은 포커스를 잃거나 백그라운드 상태로 전환되면 CPU 사용량 절감을 위해 렌더링을 중단하거나 프레임을 제한하고, 오디오 재생도 일시 중지하므로, 원격 스트리밍을 정상 유지하기 위해서는 게임 프로세스가 백그라운드에서도 작동하도록 구성을 변경해야 합니다.

1. 리모트 플레이 연결 상태에 따른 권장 정책¶

게임은 리모트 플레이 연결 상태를 확인하여 원격 사용자가 접속 중인지 판단해야 합니다. 권장 동작은 아래와 같습니다.

연결 상태는 상태 이벤트 콜백(eventType: "Event", value REMOTE_PLAY_CONNECTED / REMOTE_PLAY_DISCONNECTED)으로 판별할 수 있습니다.

2. 백그라운드 렌더링 유지¶

잠금화면 상태에서도 리모트 플레이가 화면을 캡처할 수 있도록 렌더링 루프를 계속 동작시켜야 합니다. 점검 항목 예시는 아래와 같습니다.

• 프레임 업데이트 중단 금지
• 렌더 루프 유지
• 카메라 렌더링 유지
• UI 갱신 유지
• 백그라운드 프레임 제한 정책 검토

3. 백그라운드 오디오 출력 유지¶

리모트 플레이는 게임 프로세스에서 출력되는 오디오를 캡처해 원격 플레이어에게 전달합니다. 따라서 아래와 같은 백그라운드 오디오 차단 정책은 비활성화해야 합니다.

• Focus Lost 시 오디오 일시 정지
• Window Deactivate 시 Audio Engine 중지
• Background Mute 기능 활성화

엔진별 점검 및 참고 사항¶

Unity¶

Unity는 기본적으로 백그라운드 진입 시 업데이트를 제한할 수 있습니다. 잠금화면 리모트 플레이 기능을 사용하는 경우 아래와 같은 백그라운드 실행 활성화를 권장합니다.

Application.runInBackground = true;

또한 포커스 손실 시 오디오를 중지하는 커스텀 로직이 있는 경우, 리모트 플레이 연결 상태를 고려하여 예외 처리해야 합니다.

Unreal Engine¶

Unreal Engine 프로젝트에서도 포커스 손실 시 Tick, 렌더링 또는 오디오 처리를 제한하는 설정이 적용되어 있는지 확인해야 합니다. 특히 아래 항목을 점검하는 것을 권장합니다.

• Background Tick 동작 여부
• Focus Lost 시 Pause 처리 여부
• Audio Mixer 동작 여부
• 백그라운드 FPS 제한 정책

리모트 플레이 접속 중에는 백그라운드 상태에서도 정상적인 게임 루프가 유지되도록 구현해야 합니다.

권장 동작 시나리오¶

1. 사용자가 Windows 잠금화면 상태로 전환
2. 리모트 플레이 클라이언트 접속
3. 게임은 연결 상태를 감지하여 백그라운드 렌더링 및 오디오 출력 상태 유지
   • 게임 렌더링 지속
   • 게임 오디오 출력 지속
4. 리모트 플레이 플러그인이 화면과 오디오를 정상적으로 캡처 및 전송
5. 원격 사용자가 게임 화면·사운드를 실시간으로 수신
6. 입력 이벤트는 리모트 플레이 입력 Control 콜백을 통해 게임 내부 입력 시스템으로 전달

관련 문서¶

• 이벤트 수신을 위한 콜백 함수 등록
• 블라인드 이미지 변경