언리얼 엔진 5 문서가 에픽 디벨로퍼 커뮤니티로 이전되었습니다

리모트 컨트롤 API WebSocket 레퍼런스

엔진 원격 조작에 사용되는 리모트 컨트롤 API에서 제공하는 WebSocket 엔드포인트를 자세히 다룹니다.

Choose your operating system:

Windows

macOS

Linux

이 페이지는 리모트 컨트롤 API(Remote Control API) 가 제공하는 WebSocket 메시지 유형을 설명합니다. 페이지 마지막 부분에서는 JavaScript 함수를 포함한 샘플 HTML 파일을 통해 해당 WebSocket 메시지를 테스트하는 방법을 보여줍니다.

엔진의 기본 WebSocket 포트는 30020입니다. WebSocket 서버를 `ws://127.0.0.1:30020`에 연결해 메시지 전송을 시작하세요. 여러분 프로젝트에 맞게 WebSocket 포트를 바꿀 수 있습니다.

  • 에디터의 메인 메뉴에서 편집(Edit) > 프로젝트 세팅…(Edit Project Settings…) 을 선택해 프로젝트 세팅(Project Settings) 창을 여세요.

  • 프로젝트 세팅 창에서 플러그인(Plugins) 항목의 웹 리모트 컨트롤(Web Remote Control) 을 선택하세요.

    • 리모트 컨트롤 WebSocket 서버 포트(Remote Control WebSocket Server Port) 항목을 사용할 포트로 변경하세요.

Remote Control Plugin Settings

WebSocket 메시지

리모트 컨트롤 API는 WebSocket 메시지에 JSON 형식을 사용합니다. 서버로 전송할 모든 메시지는 다음과 같은 프로퍼티가 있는 JSON 오브젝트여야 합니다.

프로퍼티

설명

MessageName

전송할 메시지의 유형을 구별합니다. 선택지는 다음과 같습니다.

  • HTTP

  • Preset.Register

  • Preset.Unregister

Parameter

메시지 유형에 지정된 파라미터입니다. 자세한 내용은 아래 항목을 참조하세요.

Id

선택사항: 서버에서 지연된 응답을 구별할 때 유용한 식별자입니다.

WebSocket 메시지 유형 - HTTP

이 메시지 유형을 사용하면 WebSocket 메시지를 통해 HTTP 경로를 호출합니다. 호출 가능한 HTTP 경로에 대한 추가 정보는 리모트 컨트롤 API HTTP 레퍼런스 를 참조하세요.

JSON 메시지 예시: 

{
    "MessageName": "http",
    "Parameters": {
        "Url": "/remote/object/property",
        "Verb": "PUT",
        "Body": {
            "ObjectPath": "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.CubeMesh_5.StaticMeshComponent0",
            "propertyName": "StreamingDistanceMultiplier",
            "access": "READ_ACCESS"
        }
    }
}

WebSocket 서버를 호출하면 다음과 같은 JSON 메시지를 회신합니다. 

{
    "RequestId": -1,
    "ResponseCode": 200,
    "ResponseBody": {
        "StreamingDistanceMultiplier": 1
    }
}

WebSocket 메시지 유형 - Preset.Register

이 메시지 유형을 사용하면 리모트 컨트롤 프리셋(Remote Control Preset) 에서 생긴 이벤트를 등록합니다. JSON 메시지 예시: 

{
    "MessageName": "preset.register",
    "Parameters": {
        "PresetName": "MyPreset"
    }
}

다음 항목은 프리셋 및 프리셋의 JSON 메시지로 인한 이벤트를 설명합니다.

리모트 컨트롤 프리셋 이벤트 - PresetFieldsChanged

누군가가 프리셋에 표시된 값을 변경할 때마다 이 메시지를 전송합니다. 

 {
       "Type": "PresetFieldsChanged",
       "PresetName": "MyPreset",
       "ChangedFields":  [
           {
                "PropertyLabel": "Relative Rotation (LightSource_0)",
                "ObjectPath": "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.LightSource_0.LightComponent0",
                "PropertyValue":  {
                    "Pitch": 14.4,
                    "Yaw": 0,
                    "Roll": 169.2
                }
           }
        ]
    }

리모트 컨트롤 프리셋 이벤트 - PresetFieldsAdded

프로퍼티가 프리셋에 노출될 때마다 이 메시지를 전송합니다. 응답은 프로퍼티가 추가된 그룹만 포함합니다. 

{
    "Type": "PresetFieldsAdded",
    "PresetName": "MyPreset",
    "Description": {
        "Name": "MyPreset",
        "Path": "/Game/Presets/MyPreset.MyPreset",
        "Groups": [
            {
                "Name": "Lighting",
                "ExposedProperties": [
                    {
                        "DisplayName": "Light Color (LightSource_0)",
                        "UnderlyingProperty": {
                            "Name": "LightColor",
                            ... 
                        }
                    }
                 ],
                 "ExposedFunctions": []
            }
        ]
    }
}

리모트 컨트롤 프리셋 이벤트 - PresetFieldsRemoved

프로퍼티나 함수가 프리셋에서 제거될 때마다 이 메시지를 전송합니다. 

{
    "Type": "PresetFieldsRemoved",
    "PresetName": "MyPreset",
    "RemovedFields": [
        "Light Color (LightSource_0)"
    ]
}

리모트 컨트롤 프리셋 이벤트 - PresetFieldsRenamed

프리셋에 있는 프로퍼티나 함수의 이름이 변경될 때마다 이 메시지를 전송합니다. 

{
    "Type": "PresetFieldsRenamed",
    "PresetName": "MyPreset",
    "RenamedFields": [
        {
            "OldFieldLabel": "Relative Rotation (LightSource_0)",
            "NewFieldLabel": "Directional Light Rotation"
        }
    ]
}

WebSocket 메시지 유형 - Preset.Unregister

이 메시지 유형을 사용하면 리모트 컨트롤 프리셋 에서 생긴 이벤트의 등록을 해제합니다. JSON 메시지 예시: 

{

     {

    }
}

HTML/JavaScript 파일 샘플

  1. Index.html 파일에서 다음 코드를 저장하세요. 

        <!DOCTYPE html>
    <html>
    <head></head>
    <body>
        <h3 id="status">Connection Closed</h3>
        <input id="in"></input>
        <button id="btn" onclick="sendMessage()">Register Preset</button>
        <div id="holder"></div>
        <script>
            // 성공했을 때 WebSocket 연결을 유지하기 위한 변수입니다.
            var connection = null;

            /**
             * 이 함수는 WebSocket 메시지를 보내 리모트 컨트롤 프리셋에서 생긴 이벤트를 등록합니다.
             * 리모트 컨트롤 프리셋은 HTML 입력 항목을 사용하는 사용자에 의해 명시됩니다.
             */
            function sendMessage() {
                if (connection) {
                    let input = document.getElementById("in");
                    const registerPayload = {
                        "MessageName": "preset.register",
                        "Parameters": {
                            "PresetName": `${input.value}`
                        }
                    };
                    connection.send(JSON.stringify(registerPayload));
                }
            }

            /**
              * 이 함수는 페이지를 불러올 때마다 호출됩니다.
              * 연결에 성공하면 WebSocket 연결을 설정하고 "연결 열기"로 페이지를 업데이트합니다.
              * WebSocket 서버에서 받은 모든 메시지는 JSON에서 HTML 엘리먼트로 변환한 뒤 페이지에 렌더링합니다. 
              * 콘솔에 기록된 전체 JSON 메시지 반응도 기록합니다.
             */
            window.onload = function() {
                console.log("Starting test")
                connection = new WebSocket('ws://127.0.0.1:30020');
                connection.onopen = function () {
                    document.getElementById("status").innerHTML = "Connection Open";
                };
                connection.onerror = function (error) {};
                connection.onmessage = function (message) {
                    if (message.data instanceof Blob) {
                        reader = new FileReader();
                        reader.onload = () => {
                            let holder = document.getElementById("holder");
                            let par = document.createElement("pre");
                            par.style = style="white-space: pre-line";
                            let json = JSON.parse(reader.result);
                            let text = json.Type;
                            par.innerHTML = text;
                            holder.appendChild(par);
                            console.log(reader.result)
                        };
                        reader.readAsText(message.data);
                    } else {}
                };
                connection.onclose = function(event) {
                  console.log("WebSocket is closed now.");
                };
            }
        </script>
    </body>
    </html>

  2. 웹 브라우저에서 index.html 파일을 여세요. WebSocket 서버 연결에 성공하면 해당 페이지에서 연결 열림(Connection Open) 문구가 표시됩니다.

    Screenshot of test HTML/JavaScript page

  3. 입력 항목에 리모트 컨트롤 프리셋 의 이름을 입력하고 프리셋 항목을 변경하세요.

  4. 브라우저의 콘솔 로그를 열고 응답 메시지가 기록되었는지 확인하세요.

언리얼 엔진 문서의 미래를 함께 만들어주세요! 더 나은 서비스를 제공할 수 있도록 문서 사용에 대한 피드백을 주세요.
설문조사에 참여해 주세요
건너뛰기