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) 항목을 사용할 포트로 변경하세요.
-
WebSocket 메시지
리모트 컨트롤 API는 WebSocket 메시지에 JSON 형식을 사용합니다. 서버로 전송할 모든 메시지는 다음과 같은 프로퍼티가 있는 JSON 오브젝트여야 합니다.
프로퍼티 |
설명 |
---|---|
MessageName |
전송할 메시지의 유형을 구별합니다. 선택지는 다음과 같습니다.
|
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 파일 샘플
-
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>
-
웹 브라우저에서 index.html 파일을 여세요. WebSocket 서버 연결에 성공하면 해당 페이지에서 연결 열림(Connection Open) 문구가 표시됩니다.
-
입력 항목에 리모트 컨트롤 프리셋 의 이름을 입력하고 프리셋 항목을 변경하세요.
-
브라우저의 콘솔 로그를 열고 응답 메시지가 기록되었는지 확인하세요.