Remote Control API WebSocket のリファレンス

エンジンをリモートで制御するために Remote Control API が提供する WebSocket エンドポイントの詳細です。

Windows
MacOS
Linux

このページでは、Remote Control API で提供される WebSocket メッセージ タイプを説明します。これらの WebSocket メッセージの使用およびテスト方法が示すために、JavaScript 付きの HTML ファイルがページの最後に付いています。

エンジンの WebSocket ポートはデフォルトが 30020 です。WebSocket サーバーを ws://127.0.0.1:30020 に接続してメッセージの送信を開始します。使用するプロジェクト用に WebSocket ポートを変更することができます。

  • エディタのメイン メニューから [Edit (編集)] > [Project Settings (プロジェクト設定)] を選択して、[Project Settings (プロジェクト設定)] ウィンドウを開きます。

  • [Project Settings (プロジェクト設定)] ウィンドウで、[Plugin] セクションの [Web Remote Control] を選択します。

  • [Remote Control WebSocket Server Port] フィールドを使用するポートに変更します。

Remote Control Plugin Settings

WebSocket メッセージ

Remote Control API は WebSocket メッセージに JSON 形式を使用します。サーバーに送信されるすべての WebSocket メッセージは以下のプロパティをもつ JSON オブジェクトでなければなりません。

プロパティ

説明

MessageName

識別子は送信するメッセージのタイプです。オプションは次のとおりです。

  • HTTP

  • Preset.Register

  • Preset.Unregister

Parameters

各メッセージ タイプのパラメータ。詳細は以下のセクションを参照してください。

Id

オプションです。サーバーからの応答遅延に便利な識別子。

WebSocket メッセージ タイプ - HTTP

WebSocket メッセージを介した HTTP ルートの呼び出しにこのメッセージ タイプを使用します。呼び出し可能な HTTP ルートの詳細については、「Remote Control 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

リモート コントロール プリセット から発行されたイベントにサブスクライブするためにこのメッセージ タイプを使用します。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)"
    ]
}

Remote Control Preset Event - PresetFieldsRenamed

このメッセージは、プロパティまたは関数がプリセットで名前い変更されると送信されます。

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

WebSocket メッセージ タイプ - Preset.Unregister

リモート コントロール プリセット から発行されたイベントからサブスクライブを解除するためにこのメッセージ タイプを使用します。JSON メッセージの例:

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

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>
                // Variable to hold the WebSocket connection if it's successful.
                var connection = null;
    
                /**
                 * This function sends a WebSocket message to subscribe to events emitted by a Remote Control Preset.
                 * The Remote Control Preset is specified by the user in the HTML input field.
                 */
                function sendMessage() {
                    if (connection) {
                        let input = document.getElementById("in");
                        const registerPayload = {
                            "MessageName": "preset.register",
                            "Parameters": {
                                "PresetName": `${input.value}`
                            }
                        };
                        connection.send(JSON.stringify(registerPayload));
                    }
                }
    
                /**
                 * This function is called every time the page loads.
                 * It sets up a WebSocket connection and updates the page with "Connection Open" if the connection is successful.
                 * Any message it receives from the WebSocket server, it converts from JSON to HTML elements and renders them on the page.
                 * It also logs the full JSON message responses in the console.
                 */
                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. ブラウザのコンソール ログを開いて、応答メッセージが記録されているかを確認します。

Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
閉じる